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](https://meshfleet.app) · **Source version**: 0.22.0 · [npm](https://www.npmjs.com/package/meshfleet) · [CI](https://github.com/johnmwhitman/agent-mesh/actions)

*Maintained: current source and Git tags are visible in [the repository](https://github.com/johnmwhitman/agent-mesh); a tag is an intent to ship and [the registry](https://www.npmjs.com/package/meshfleet?activeTab=versions) 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](https://meshfleet.app/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:

```typescript
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 <value>` 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_<VENDOR>_COMMAND` plus configured `MESHFLEET_<VENDOR>_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](./docs/ADAPTER-CONTRACT.md) 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):

```bash
npm install -g meshfleet
```

Or from source:

```bash
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):

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

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

```jsonc
{
  "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 →](#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.

```bash
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:

```bash
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](https://github.com/johnmwhitman/agent-mesh/issues/new?template=usefulness.yml)
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