Agent Mesh — meshfleet.app

Auditable multi-agent coordination for OpenCode. Spawn parallel agents as independent OS processes. Route work to specialists. Let agents collaborate peer-to-peer — with witnessed receipts and quorum ratification, so you can answer: who saw this, who approved it, prove it. The core is MIT and free.

Website: meshfleet.app · Version: 0.11.1 · Tests: 209/209 passing · CI

Project status — deliberately pre-1.0, actively maintained. Releases are intentionally infrequent (we cut versions when something is worth shipping, not on a calendar); the repo carries a monthly maintenance heartbeat and issues get a first response within 48 hours.

The boundary, as a covenant: the mechanisms are free and stay free — coordination, receipts, councils, and the ability to run verification are MIT, forever. Cryptographic signing and auditor-grade attestation are the paid layer (meshfleet-pro); signatures never enter this core. The developer's question (what happened?) is answered here; the auditor's question (could anyone have changed this?) is what you pay for.

Host portability: this is an agent audit trail, OpenCode first — not an OpenCode-only idea. The core is a standard MCP server; broader host support tracks real demand.

Why Meshfleet?

OpenCode is a single-agent runtime. You talk to it, it does things. The moment you need multiple specialists running in parallel — explore, then review, then implement — you hit the 30-minute background-task timeout.

Meshfleet adds the missing layer: a fleet of agents that run in parallel, message each other, hand off work, and self-organize. As independent OS processes, not background tasks. No artificial ceiling.

const { fleet_id } = await callTool("spawn_fleet", {
  agents: [
    { role: "Explorer",   prompt: "Map the auth layer",    agent: "codebase-onboarding-engineer" },
    { role: "Analyst",    prompt: "Review the architecture", agent: "oracle" },
    { role: "Engineer",   prompt: "Implement JWT refresh",  agent: "backend-architect" },
  ],
});

Three specialists. Three independent processes. They hand off, ask questions, alert on problems. You read the result.

And when an agent's action matters, Meshfleet can prove what happened. Every message writes per-recipient receipts (delivered, seen, acked). Decisions can go through councils — quorum-based ratification with required sign-offs, recorded on the same ledger. The design is a port of a bus that ran a 10+ agent fleet in production for 40 days and 18,404 messages, including quorum-ratified decisions.

Install in 30 seconds

From npm (the package is meshfleet; the agent-mesh npm name is squatted by a placeholder):

npm install -g meshfleet

Or from source:

git clone https://github.com/johnmwhitman/agent-mesh.git \
  ~/.config/opencode/mcp-servers/agent-mesh
cd ~/.config/opencode/mcp-servers/agent-mesh
npm install && npm run build

Add to ~/.config/opencode/opencode.jsonc (npm install):

{
  "mcp": {
    "agent-mesh": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "meshfleet"]
    }
  }
}

or, if you built from source:

{
  "mcp": {
    "agent-mesh": {
      "type": "local",
      "enabled": true,
      "command": ["node", "~/.config/opencode/mcp-servers/agent-mesh/dist/index.js"]
    }
  }
}

Restart OpenCode. Spawn a fleet. Full install guide →

The CLI

Once Meshfleet is installed, the agent-mesh CLI gives you terminal visibility into your running fleets, and agent-mesh-dashboard gives you a live TUI.

$ npx agent-mesh inspect
3 fleets:

bc34d339-935c-4…  complete  3 agents, 3 done (34.8m)
37ae1cf2-5ce8-4…  complete  1 agents, 1 done (28.2m)
d648beb0-cfb2-4…  failed    2 agents, 2 done (27.3s)

$ npx agent-mesh inspect --metrics
Total fleets:       7
  completed:        3
  failed:           4
Total agents:       16
Success rate:       42.9%
Avg duration:       1.34s

$ npx agent-mesh inspect --events 5
TIMESTAMP            EVENT              DETAIL
──────────────────────────────────────────────────────────────────────
2026-07-02 12:40:12  agent_spawned       fleet=f-1 agent=a-1
2026-07-02 12:40:12  agent_spawned       fleet=f-1 agent=a-2
2026-07-02 12:40:12  fleet_created       fleet=f-1

25 MCP tools

Fleets

| Tool | What it does | |---|---| | spawn_fleet | Spawn N parallel agents as independent OS processes | | spawn_from_template | Spawn a fleet from a saved template | | save_fleet_template / list_fleet_templates | Reusable, versioned fleet configs | | list_fleets / fleet_status | All fleets, or one fleet's full state | | collect_results | Gather every agent's final output in one call | | set_fleet_timeout | Per-fleet timeout override (in ms) | | attach_agent | Dynamically attach a premade agent to a running fleet |

Messaging & receipts

| Tool | What it does | |---|---| | send_message | P2P message (5 types) — or to_agent_id: "*" to broadcast to the whole fleet | | get_inbox / ack_message | Poll and acknowledge; every ack writes a per-recipient receipt | | subscribe_inbox | Push delivery over SSE instead of polling | | receipt / get_receipts | Write and query the witnessed-delivery ledger: who saw what, when |

Councils (quorum ratification)

| Tool | What it does | |---|---| | open_ratification | Put a decision to the fleet: quorum size, deadline, required sign-offs | | cast_vote | An agent votes, on the record | | tally_ratification / sweep_ratifications | Resolve outcomes; expire past-deadline votes |

Routing & ops

| Tool | What it does | |---|---| | register_capability | Self-describe role + skills for routing | | route_work | Match a task to the best agent by keyword + role overlap | | record_routing_outcome | Feed results back to improve routing | | list_agents | Discover 100+ premade agent personalities | | get_health / ping | Fleet health and liveness |

That's 25. We counted twice this time.

Full API reference →

5 message types

| Type | Use it for | |---|---| | handoff | Passing context to the next agent in a pipeline | | question | Asking a clarifying question (with optional correlation_id) | | result | Reporting a final outcome | | alert | Broadcasting a problem to all fleet peers | | request_help | Escalating when stuck (target a specific peer with relevant skills) |

64 KB payload cap. The default encoding is JSON, but payloads are strings — send whatever you want. Broadcasts (to_agent_id: "*") fan out to every fleet peer, and each recipient acks independently — the receipts ledger shows exactly who saw it.

4 collaboration patterns

• Pipeline handoff: A → B → C. Each specialist hands context to the next. No orchestrator in the loop.
• Debate consensus: A and B review the same artifact, debate via questions, converge before reporting.
• Failure recovery: C hits a blocker, broadcasts alert, peers with relevant skills respond with fixes.
• Ratified decision: a council votes on a risky action — quorum, deadline, required sign-off — and the outcome (including who stayed silent) is on the ledger.

More use cases →

How it compares

| Tool | Best for | Tradeoffs | |---|---|---| | OpenCode task() | Single-task work | 30-min timeout, no P2P | | LangGraph | Python graph apps | Python-only, hosted-first | | CrewAI | Role-based Python agents | Python-only, hosted | | AutoGen | Research projects | Heavy, Python-only | | Hand-rolled cron | Specific one-off workflows | No shared abstractions | | Meshfleet | OpenCode + multi-agent, local-first, auditable | TypeScript-only (for now) |

None of them answer "who saw this, who approved it, prove it." That's the lane.

Full comparison →

Architecture

src/
├── db.ts                # The withLedger transaction seam over SQLite (the write boundary)
├── core.ts              # Data layer: ledger, messages, receipts, capabilities, events
├── migrate.ts           # One-shot JSON→SQLite migration (runs once at startup)
├── ratify.ts            # Councils: quorum ratification over the receipts substrate
├── templates.ts         # Versioned fleet templates
├── routing-feedback.ts  # Outcome-informed work routing
├── health.ts            # Fleet health scoring
├── realtime.ts          # SSE push delivery (subscribe_inbox)
├── inspector.ts         # Pure formatters for CLI output
├── index.ts             # MCP server: transport + tool handlers
└── bin/
    ├── inspect.ts       # CLI: npx agent-mesh inspect
    └── dashboard.ts     # Live TUI: npx agent-mesh-dashboard

Every write goes through one function — withLedger(mutator) in db.ts — which runs the mutation inside a single SQLite BEGIN IMMEDIATE transaction. Agents are real OS processes that each boot their own agent-mesh instance on the same ledger, so writes are genuinely concurrent; SQLite (WAL + busy_timeout) provides cross-process write exclusion, so this codebase owns no locking protocol and lost-update is impossible by construction. (An earlier JSON read-modify-write store silently lost 57 of 120 receipts under a two-process test; the SQLite seam passes the same test 200/200.) Readers use a lock-free readLedger(). Pure formatters live in inspector.ts — easy to test, no I/O.

The ledger lives at ~/.config/opencode/agent-mesh.db (SQLite); the event log at ~/.config/opencode/agent-mesh.events.log (NDJSON). Dump the ledger as human-readable JSON any time with npx agent-mesh inspect --export. On first run after upgrading from a JSON ledger, the server migrates it once (validated, with a .migrated.<ts> backup kept).

Full spec → · P2P messaging spec →

Requirements

• Node.js >= 20
• OpenCode CLI in $PATH (any model provider OpenCode supports)
• That's it

License

The core is MIT — use it, fork it, ship it in your product. No attribution beyond the license file. (A commercial assurance layer, Meshfleet Pro, lives in a separate repo and doesn't change what's here.)

Contributing

See CONTRIBUTING.md. Bugs → issues. Security → SECURITY.md. Roadmap → ROADMAP.md.