Agent Mesh

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 · Source version: 0.22.0 · npm · CI

*Maintained: current source and Git tags are visible in the repository; a tag is an intent to ship and the registry is the only record of what shipped · issues answered within 48h · no download-count theater.*

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, provider-neutral advisory interfaces, and the ability to *run*

verification are MIT, forever. Cryptographic signing and auditor-grade

attestation are a separate paid layer

(meshfleet-pro). Account-specific provider operations

and managed policy are also outside this core. No existing core mechanism moves

behind a paywall. The core neither owns nor independently controls provider-account

credentials, balances, reset policy, spend authority, or external publication.

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.

The following is a source/operator-configured example, not a claim that every runtime shown ships in the current npm package:

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", model: "opencode-go/minimax-m3" }, { role: "Reviewer", prompt: "Review the resulting diff", runtime: "claude-cli", workspace_binding: "review-worktree" }, ], });

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

Each OpenCode agent accepts an optional model (provider/model) selector. When set, Meshfleet persists it as the immutable request (Agent.requested_model) and launches opencode run --model for that agent; the observed runtime banner lands in Agent.runtime_model, and a complete agent whose banner is missing or contradicts the request fails closed. Omitting model keeps the old argv exactly. The selector is data, not shell text, and the banner is observed evidence — not authentication, billing, provider availability, or attestation.

spawn_fleet also accepts an optional per-agent runtime. The default remains opencode-cli; non-default runtimes are available only when the operator configures them. claude-cli requires an absolute command, a configured version label, and an operator-admitted opaque workspace binding. The caller must repeat that binding as workspace_binding, and must omit OpenCode-specific agent and model selectors. minimax-cli and grok-cli are separate explicit-only text lanes. Each requires its own absolute MESHFLEET_ _COMMAND plus configured MESHFLEET_ _VERSION; accepts no model/agent selector, workspace authority, or artifact expectation; declares its outcome through a structured final-text envelope; withholds raw diagnostics; and is never an automatic failover target. The Grok adapter additionally forces the configured wrapper's source-blind text-only boundary. Each wrapper owns its own authentication; Meshfleet passes a scrubbed environment, never reads or serializes credentials, and exposes no account, credential, effective-model, quota, or availability claim. This outbound worker adapter is separate from the offline static Grok configuration translation, which launches no runtime. See the adapter contract for exact permission and evidence limits. Local smoke tests for any account remain environment-local. The separate pure recommend_route advisory may opt in to a caller-evidenced near-reset tie-break, but it never polls an account, grants provider authority, or executes a paid service.

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": { "meshfleet": { "type": "local", "enabled": true, "command": ["npx", "-y", "meshfleet"] } } }

For noncanonical development-only source-checkout usage (not the recommended release config):

{

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

Restart OpenCode. Spawn a fleet. Wiring it into your client →

Start with the published package

The published meshfleet package's no-key walkthrough is a scripted ledger demonstration: it proves that the package and inspector run, not that a model-backed worker completed a real task.

npx -y --package=meshfleet -- agent-mesh demo

That published walkthrough runs entirely against a throwaway temp ledger (nothing under ~/.config/opencode is touched) and prints its demonstration audit, then a next-step inspector command. To inspect your own configured MCP ledger later, bind the package explicitly — running the agent-mesh bin through npx without --package=meshfleet resolves npm's unrelated reserved agent-mesh@0.0.1 package, not this one:

npx -y --package=meshfleet -- agent-mesh inspect --verify

If that (or the MCP server itself) exits with CRASH ... unsupported newer storage schema version, it found a pre-existing ledger at the default path (~/.config/opencode/agent-mesh.db) written by a newer meshfleet build than the one you're running — common on a dev machine that already ran OpenCode/meshfleet, not on a fresh install. Point at a different ledger file with MESHFLEET_DB_FILE=/path/to/other.db (same variable your MCP client config can set) and it will not touch the existing file.

Source-only deterministic runtime

The newer source checkout documented on this page includes a local-demo runtime — the current Node executable running a deterministic worker. It is not in the published package. After building this source checkout, ask your MCP host to spawn with it:

spawn_fleet with agents [{ role: "scout", prompt: "Count the receipts.", runtime: "local-demo" }]

The spawn, lifecycle events, receipts, and collect_results are all real; only the worker is synthetic, and it says so in its output ("model": null, no invented text). local-demo is never used for automatic failover — a real agent that fails is never silently replaced by an echo.

Try one real, read-only task

Prerequisite: OpenCode is already installed and configured for an account you are authorized to use. Meshfleet does not create credentials, choose billing scope, or make provider calls until you ask it to spawn a worker. Through your MCP host:

1. Call spawn_fleet with agents: [{ role: "explorer", prompt: "Read this repository's README and list its three main sections. Do not edit files." }]. Omit runtime so the published default opencode-cli adapter is used.
2. Pass the returned fleet_id to collect_results, then inspect the local evidence with npx -y --package=meshfleet -- agent-mesh inspect --verify.
3. Treat complete and the local consistency report as recorded claims, not proof that the answer or code is correct. Review the worker's result yourself.

Then share voluntary first-use feedback and say whether the path was useful, not useful, or blocked, plus the first step where you got stuck. Please do not upload source code, prompts, credentials, secrets, or raw ledger files. If it helped, try the same evidence check on a different meaningful task another day; rerunning the scripted demo is not return use.

---

Wiring it into your client

Meshfleet is a standard stdio MCP server. The invocation is always the same — npx -y meshfleet (the meshfleet bin in package.json points at the server, dist/index.js) — only the config file around it changes per client.

Honesty labels. "Tested" means verifiable from this repo itself. Client-specific shapes below follow each client's documented config format — we haven't wired CI to every editor, so those are marked "per \ docs — verification welcome."

Any MCP client (generic stdio) — tested: this exact shape ships in this repo as mcp.json

{

"mcpServers": { "meshfleet": { "command": "npx", "args": ["-y", "meshfleet"] } } }

OpenCode — primary host; canonical meshfleet server identity

~/.config/opencode/opencode.jsonc:

{

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

Claude Code — per Claude Code docs — verification welcome

CLI form:

claude mcp add meshfleet -- npx -y meshfleet

Or project-scoped .mcp.json at the repo root:

{

"mcpServers": { "meshfleet": { "command": "npx", "args": ["-y", "meshfleet"] } } }

Codex — same host-neutral stdio server

Configure Codex's MCP server entry with the same command and arguments:

{

"mcpServers": { "meshfleet": { "command": "npx", "args": ["-y", "meshfleet"] } } }

These Claude Code, Codex, OpenCode, and generic MCP configurations all call the same inbound stdio server. This proves client interoperability at the MCP boundary only. Workers default to OpenCode's opencode run; an operator may separately register a non-default runtime such as claude-cli. The subscribe_inbox SSE endpoint is optional acceleration; it is not required for compatibility, and clients can use get_inbox polling.

If any block above doesn't work in your client, open an issue —