Sample data in tests, prompts and UI placeholders uses Alex Morgan instead of the maintainer's name; decision attributions say "owner". Personal details in two test fixtures are replaced. Local paths (D:/Projects/...) and paths into the maintainer's planning repository are reworded. Clone and install URLs in CONTRIBUTING.md and the getting started guide use placeholders until the public repository location is decided (Q9). The Benchmarks page no longer names the maintainer's hive-mind repository, and the upstream fixes log names the main Waggle repository instead of an internal git host.
5.1 KiB
Contributing to Waggle
Prerequisites
- Node.js 20+ (required)
- Rust toolchain (only for the desktop app --
app/package) - Docker (only for team mode tests -- PostgreSQL and Redis)
Setup
git clone <repository-url> waggle-os # the public repository location is not decided yet
cd waggle-os
npm install
Running the App
# Local server / sidecar (http://localhost:3333)
cd packages/server && npx tsx src/local/start.ts
# — or, from the repo root: npm run dev:server
# Web app (http://localhost:8080)
npm run dev # — or: npm run dev:web
# Desktop app (requires Rust)
cd app && npm run tauri dev
# CLI REPL
cd packages/cli && npx tsx src/index.ts
Running Tests
Tests are the product's safety net. All PRs must pass the full test suite.
# Run all tests (3000+ across 190+ files)
npx vitest run
# Watch mode during development
npx vitest
# Run tests for a specific package
npx vitest run packages/core
# Run a specific test file
npx vitest run packages/agent/src/__tests__/tools.test.ts
# Coverage report
npx vitest run --coverage
Test Requirements
- All existing tests must pass before submitting a PR
- New features require accompanying tests
- Bug fixes require a regression test
- Team mode tests require Docker services running (
docker compose up -d)
Test Organization
Tests live alongside source files in __tests__/ directories or as .test.ts siblings. The monorepo uses a single Vitest config at the root.
Pull Request Process
- Fork the repository and create a feature branch from
main - Read the CLAUDE.md for execution rules and product truths
- Make your changes following the slice-based approach (one focused change per PR)
- Write tests for new functionality
- Run the full test suite:
npx vitest run - Verify the build:
npx tsc --noEmit - Submit a pull request against
main - Describe your changes: what was added, what was preserved, what was tested
PR Title Format
Use descriptive titles that indicate the type of change:
feat: add Notion connector-- new featurefix: memory search scope filtering-- bug fixrefactor: extract FrameStore from MindDB-- code restructuringtest: add coverage for approval gates-- test additionsdocs: update API reference-- documentation
Code Style
TypeScript
- ESM modules (
"type": "module"in package.json) - Explicit imports (no barrel re-exports)
- Strict TypeScript (
strict: true) - Use
typeimports where possible:import type { Foo } from './foo.js' - Include
.jsextensions in imports (ESM requirement)
File Organization
- One concept per file where practical
- Co-locate tests:
foo.tsand__tests__/foo.test.ts - Route files export a Fastify plugin async function
- Types go in the
@waggle/sharedpackage if used across packages
Naming Conventions
- Files:
kebab-case.ts - Types/Interfaces:
PascalCase - Functions/variables:
camelCase - Constants:
UPPER_SNAKE_CASE - Route handlers: descriptive comments with HTTP method and path
Error Handling
- Route handlers catch errors and return appropriate HTTP status codes
- Non-critical operations use try/catch with empty catch (logging is acceptable)
- Critical operations throw with descriptive error messages
- Avoid swallowing errors silently in core logic
Package Structure
Adding to an Existing Package
- Add your source file in the appropriate directory
- Export from the package's
index.tsif it's a public API - Add tests in the
__tests__/directory - Run
npx vitest run packages/<name>to verify
Key Directories
packages/<name>/
src/
index.ts # Public exports
__tests__/ # Test files
package.json # Package metadata
tsconfig.json # TypeScript config
Product Rules
Read CLAUDE.md in the repo root for the full execution protocol. Key rules:
- Waggle is workspace-native -- do not collapse into a global chat
- Memory is a product primitive -- do not treat it as decorative
- Tool transparency matters -- users see what the agent does
- Approval gates are required for sensitive operations
- No scope reduction without approval -- do not simplify features "for now"
- Tests are part of the product -- not an afterthought
Troubleshooting
Windows: sidecar fails to start with an esbuild platform error
The Fastify sidecar runs through tsx, which uses esbuild. On a clean Windows
machine the platform-specific esbuild binary is sometimes not resolved, and
npm run dev:server (or npx tsx src/local/start.ts) fails with an error like
Cannot find module @esbuild/win32-x64 or an esbuild version/host mismatch.
Fix it by installing the matching Windows esbuild binary without adding it to
package.json:
npm i @esbuild/win32-x64@0.28.0 --no-save
This affects Windows only — macOS and Linux resolve their esbuild binaries
normally. The version should match the esbuild your install resolved; 0.28.0
is the known-good pin for the sidecar.
Questions?
Open an issue for architecture questions, feature proposals, or bug reports.