Contributing

Code of conduct

This project follows the Contributor Covenant v2.1. Be respectful. Assume good faith. Focus on the work, not the person.

Development setup

Prerequisites

• →Node.js 18 or later
• →npm (or pnpm / yarn)
• →OpenCode CLI in $PATH (brew install anomalyco/tap/opencode or download from opencode.ai)
• →Git

Clone and build

git clone https://github.com/johnmwhitman/agent-mesh.git
cd agent-mesh
npm install
npm run build

Run the test suite

npm test           # 181 unit tests, runs in ~2s
npm run typecheck   # tsc --noEmit

The test suite uses node --test with the tsx loader. Tests are isolated via an in-memory setLedgerOverride pattern — see test/core.test.ts for the approach.

Dev workflow

npm run dev        # tsx watch — auto-rebuild on file changes
npm run inspect    # run the CLI inspector against your real ledger
npm run benchmark  # re-run the perf suite, outputs to BENCHMARKS.md

Pull request process

1. Fork the repo and create a feature branch: git checkout -b feat/your-feature
2. Write tests first. New behavior must have a failing test that becomes passing. Bug fixes must have a regression test.
3. Match the existing style. TypeScript strict mode, ESM, single quotes, .js extensions in imports. Look at neighboring code before adding new files.
4. Run the full suite before opening the PR: npm test && npm run typecheck && npm run build
5. Write a clear commit message following Conventional Commits:
   • feat: for new features
   • fix: for bug fixes
   • chore: for maintenance
   • docs: for documentation only
   • refactor: for code changes that neither fix nor add
6. Open the PR with: summary of what changed, test plan, and any BREAKING CHANGE: notes.

Coding conventions

• →TypeScript strict mode. No any, no @ts-ignore. Use unknown and narrow.
• →ESM only. This package is "type": "module". Use .js extensions in imports.
• →Layered architecture. Pure data in src/core.ts. MCP transport in src/index.ts. CLI tools in src/bin/. This lets us test the data layer without spinning up an MCP server.
• →Pure formatting in src/inspector.ts. No I/O, no side effects — easy to test.
• →Minimal dependencies. One runtime dep: @modelcontextprotocol/sdk. Add a new one only after discussion.
• →Update specs when you change architecture. AGENT-MESH-SPEC.md and SPEC-P2P.md are the source of truth.

Architecture overview

src/
├── core.ts          # Pure data layer: ledger, messages, capabilities, events
├── inspector.ts     # Pure formatters for CLI output
├── index.ts         # MCP server: transport, tool handlers
├── retry.ts         # Exponential-backoff retry (v0.8.0)
├── heartbeat.ts     # Liveness watchdog (v0.7.0)
├── routing-feedback.ts  # Wilson-style score adjustment (v0.8.2)
├── skill-taxonomy.ts   # Hierarchical skill matching (v0.8.1)
├── synonyms.ts      # Semantic-ish expansion (v0.8.3)
├── templates.ts     # Versioned, shareable fleet templates (v0.6.0, v0.8.5, v0.8.6)
├── health.ts        # ping + get_health tools (v0.5.1)
├── sse-server.ts    # Inbox push (v0.7.0)
├── realtime.ts      # Subscriber registry (v0.7.0)
├── spawn-config.ts  # Spawn contract (v0.7.0 stdin fix)
└── bin/
    ├── inspect.ts   # CLI: `npx agent-mesh inspect`
    └── dashboard.ts # TUI: `npx agent-mesh-dashboard` (v0.8.7)

The data layer (core.ts) is the only place that reads/writes the JSON ledger. The MCP server (index.ts) imports it for tool handlers. The CLI (bin/inspect.ts) imports it directly. This separation lets us test the data layer without spinning up an MCP server, and test the formatters without touching the filesystem.

Adding a new MCP tool

1. Add the pure function to src/core.ts
2. Add the tool schema to src/index.ts (the tools array in ListToolsRequestSchema)
3. Add the handler in src/index.ts (the CallToolRequestSchema block)
4. Add unit tests to test/core.test.ts (or a new test/your-feature.test.ts)
5. Update /docs/api on this site (or submit a PR to the website repo)
6. Add a CHANGELOG entry under [Unreleased]

Reporting issues

Open a GitHub issue with:

• →What you expected to happen
• →What actually happened
• →Steps to reproduce
• →Environment (Node version, OpenCode version, OS)
• →Relevant output from npx agent-mesh inspect (redact sensitive data)
• →If related to a fleet crash, include the last 50 lines of ~/.config/opencode/agent-mesh.events.log

Good first issues

Look for issues labeled good first issue on the issue tracker. These are scoped, well-defined, and a good way to learn the codebase. If you don't see any that interest you, open one and ask — there are always more things to build.

Security issues

Do not open a public GitHub issue for security vulnerabilities. See /security for the reporting process.

License

By contributing, you agree that your contributions will be licensed under the MIT License.