Frequently asked questions

A peer-to-peer agent mesh for OpenCode. Spawn fleets of independent AI agents that can hand off work to each other without a 30-minute timeout and without losing context.

Three differences. (1) The MCP server keeps the agents running as independent OS processes, so they aren't subject to OpenCode's 30-minute background-task timeout. (2) Agents can send P2P messages to each other — an Explorer agent hands findings to an Analyst agent without you orchestrating the handoff. (3) The mesh survives crashes: if the MCP server dies, the next start recovers the fleet state and you can resume.

No. Meshfleet runs entirely on your machine as an MCP server. No cloud, no telemetry, no accounts. The only outbound network call is the model provider you already configured (Anthropic, OpenAI, etc.) when you set up OpenCode.

Any model OpenCode supports. The mesh doesn't care which provider or model an agent uses — it just spawns `opencode run` with the right prompt and agent definition. We test mostly with Claude, but GPT-4, Gemini, and local models (via Ollama) all work.

The mesh has no hard limit. The practical limit is your machine's resources: each agent is a Node process, so 10 agents ≈ 500MB of RAM, 100 agents ≈ 5GB. The dashboard TUI shows you what's running. The retry logic and watchdog work the same whether you spawn 3 or 300.

Yes, via two mechanisms. (1) The JSON ledger at `~/.config/opencode/agent-mesh.json` is shared between all agents and the MCP server — agents can see each other's outputs. (2) The P2P message bus (`send_message`, `get_inbox`, `ack_message`) lets agents send typed messages to each other: handoffs, questions, results, alerts, requests for help. Since v0.9.0, `send_message` also accepts `to_agent_id: '*'` to broadcast to the whole fleet.

Yes — that's witnessed messaging, added in v0.9.0. Every ack writes a timestamped receipt keyed (message, agent, action). The `receipt` tool adds non-consuming annotations (`seen`, `r-ack`, `retracted`) without removing the message from the inbox, and `get_receipts(message_id)` returns the full trail: who saw it, who acted on it, when. A broadcast counts as acknowledged only when every recipient has acked. The design is ported from a bus that ran a 10+ agent fleet in production for 40 days (18,404 messages).

`route_work(description, top_n?)` matches a description against registered capabilities. v0.8.0 added `top_n` for fan-out. v0.8.1 added hierarchical skill taxonomy (a `react` skill matches a `nextjs`-only agent at lower weight via the taxonomy tree). v0.8.3 added synonym expansion (`ui` matches a `frontend` agent). v0.8.2 added a feedback loop: after a task, call `record_routing_outcome(agent_id, capability_key, success)` and future `route_work` calls weight accordingly.

Three things, depending on the failure type. (1) Non-zero exit, watchdog timeout, or spawn error → automatic retry with exponential backoff (1s, 2s, 4s + jitter, up to 3 attempts). After 3 failures the agent is marked permanently failed with the error in the ledger. (2) MCP server crash → on next start, `recoverInterruptedAgents()` flips agents stuck in `running` to `interrupted` so you know what was lost. (3) Genuine bugs → check the event log at `~/.config/opencode/agent-mesh.events.log`.

Three ways. (1) `npx agent-mesh-dashboard` (or `npx agent-mesh dashboard`) shows live fleets, recent agents, and recent events in a TUI that refreshes every second. (2) `get_health` returns a one-shot health report. (3) `npx agent-mesh inspect` shows a one-shot view of all fleets or one specific fleet. (4) The event log at `~/.config/opencode/agent-mesh.events.log` has every spawn, message, retry, and completion.

Yes. `save_fleet_template(name, agents, description?)` stores a fleet config. v0.8.5 added versioning: each save creates a new version (auto-increment), and `listFleetTemplateVersions(name)` returns all of them. v0.8.6 added sharing: `exportFleetTemplate` writes portable JSON, `importFleetTemplate` reads it. Templates survive in the same JSON ledger as everything else.

v0.8.x was the hardening series: retry, crash recovery, schema versioning, and a benchmark suite that verifies the v1.0 perf gates (spawn bookkeeping <100ms p50, 10k messages with no drops). v0.9.0 added witnessed messaging (receipts + broadcast) with 192 tests green. The remaining v0.9.x work fixes the sendMessage bottleneck (3.8ms/msg at 10k scale), then v1.0 freezes the API. If you're risk-tolerant, use it. If you're risk-averse, wait for v1.0.

The core is MIT because it's shorter, simpler, and more permissive. You can do anything with the code (commercial, modify, distribute, sublicense, private use) with attribution. No patent grant, no trademark grant, no contributor agreement. For a small, focused project like this, MIT is the right fit. If you need patent protection, the code is dual-licenseable — open an issue and we'll discuss.

Open a GitHub issue. For security issues, see /security — do not open a public issue. For questions, the GitHub Discussions tab works (or open an issue with the `question` label).