Quickstart

Clone the MCP server and build it. (Once published, this becomes npm install -g agent-mesh.)

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:

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

Quit and relaunch. You should see 15 new MCP tools appear in the tool list, starting with spawn_fleet, fleet_status, and route_work.

From any OpenCode session, call the MCP tool. Try the code-review-trio example:

{
  "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, and post findings back to the orchestrator.

In another terminal, while the fleet runs:

npx agent-mesh-dashboard

You'll see the fleets fill in, the agents transition from running to complete, and the event log scroll past. Press Ctrl+C to exit.

When the fleet finishes, collect_results returns each agent's output:

{
  "fleet_id": "abc-123",
  "results": [
    { "role": "Explorer", "status": "complete", "output": "Auth layer has 3 modules..." },
    { "role": "Analyst",  "status": "complete", "output": "Two risks: stale sessions, missing refresh..." },
    { "role": "Engineer", "status": "complete", "output": "Drafted fix in agents/engineer-001..." }
  ]
}

If this fleet config is useful, save it as a template you can re-spawn later:

{
  "name": "auth-review",
  "description": "3-agent auth review (v0.8.5 saves the version automatically)",
  "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" }
  ]
}

Then re-spawn with spawn_from_template. Subsequent saves create a new version (v0.8.5+); old versions are preserved.