agent-bus-setup

Agent Bus Setup

Help the user configure agent-bus for their current project by writing the appropriate .mcp.json entry.

The plugin is installed at: ${CLAUDE_PLUGIN_ROOT} Dependencies are at: ${CLAUDE_PLUGIN_DATA}/node_modules

Check for existing configuration first

Before asking the user anything, check if .mcp.json already exists in the project root and has an agent-bus entry.

If an entry exists, compare the server.ts path in args against the current ${CLAUDE_PLUGIN_ROOT}/server.ts:

• Paths match: the configuration is up to date. Tell the user and stop — no changes needed.
• Paths differ (e.g. old version in cache): update the args path to ${CLAUDE_PLUGIN_ROOT}/server.ts and the NODE_PATH to ${CLAUDE_PLUGIN_DATA}/node_modules. Preserve all other fields (AGENT_BUS_NAME, AGENT_BUS_DB, AGENT_BUS_TOPICS, other MCP servers). Tell the user what was updated and remind them to restart Claude Code.

Only proceed to the full setup flow below if there is no existing agent-bus entry.

Information to gather

Ask the user for the following. Suggest sensible defaults based on the project context:

1. Agent name (AGENT_BUS_NAME) — the identity this agent will use on the bus (e.g. "backend", "frontend", "infra"). Look at the project to suggest a name based on what it does.
2. Database path (AGENT_BUS_DB) — absolute path to the shared SQLite database. All agents that need to communicate must use the same file. Suggest ~/.claude/agent-bus/bus.db as a default.
3. Runtime — whether to use bun (recommended, runs TypeScript natively) or node via npx tsx. Check if bun is installed first.
4. Topics (AGENT_BUS_TOPICS, optional) — comma-separated topic filter if the agent should only receive certain message types. Default is all topics.

What to write

Add or merge an agent-bus entry into the project's .mcp.json. If the file already exists, preserve other entries.

Bun configuration

{
  "mcpServers": {
    "agent-bus": {
      "command": "bun",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.ts"],
      "env": {
        "AGENT_BUS_NAME": "<agent-name>",
        "AGENT_BUS_DB": "<db-path>",
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Node.js configuration

{
  "mcpServers": {
    "agent-bus": {
      "command": "npx",
      "args": ["tsx", "${CLAUDE_PLUGIN_ROOT}/server.ts"],
      "env": {
        "AGENT_BUS_NAME": "<agent-name>",
        "AGENT_BUS_DB": "<db-path>",
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Replace <agent-name> and <db-path> with the user's answers. The ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} paths above are already resolved — write them as-is into the .mcp.json.

If the user also wants topic filtering, add "AGENT_BUS_TOPICS": "<topics>" to the env block.

After writing

1. Tell the user to restart Claude Code with --dangerously-load-development-channels server:agent-bus for the channel to activate.
2. Remind them that all agents sharing the bus must point AGENT_BUS_DB to the same file.
3. If they have other projects that need to join the bus, they should run this setup skill in those projects too.