AI Crew Bridge

Local task handoff bridge for MCP-capable AI tools. A leader agent creates a task, an executor agent receives it in another terminal, then the leader reviews the report.

No cloud service. No open port. Runtime state lives under a local bridge_root.

Components

| Command | Purpose | | --- | --- | | acb setup | Binds one leader host and one executor host for the current project. | | acb bind | Adds or changes leader/executor identity bindings. | | acb up | Starts the launcher and configured executor wrappers from .acb/config.json. | | acb doctor | Checks project binding, bridge root, and online members. | | acb logs | Reads local executor logs without sending them to AI context. | | acb clean | Clears task, log, or runtime state while preserving project bindings. | | acb <harness> --id <name> | Low-level executor wrapper command. | | acb monitor | Shows local bridge members, task states, and recent events. | | acb-launcher | Watches outbox files and delivers queued task prompts to wrappers. | | acb-mcp-server | stdio MCP server exposing bridge_* tools. |

Quick Start

npm install -g ai-crew-bridge
acb-mcp-server --version

Register MCP server in your AI tool. See templates/mcp-configs.md.

Install native project templates for your AI hosts:

acb install-hooks --target kiro
acb install-hooks --target codex

Bind the project once:

acb setup --leader kiro --executor codex --id codex_a -- --sandbox workspace-write

Start the local runtime each work session:

acb up

In headless executor mode, acb up claims the task, injects the spec into the executor prompt, and submits the final report after the executor process exits. The executor AI should focus on the task itself; it does not need to call bridge_claim, bridge_read_spec, or bridge_submit_report.

Executor stdout/stderr is written to local files under .acb/agent-bridge/logs/. These logs do not consume model tokens unless a human or AI explicitly reads them.

Now ask the leader AI:

Send this task to codex_a.

To change identities, re-run the binding command. The new role takes effect on the next acb up or AI session restart:

acb bind leader --target cursor
acb bind executor --target claude --id claude_a

For a manual interactive harness, opt into TUI mode:

acb bind executor --target codex --id codex_manual --mode tui
acb up

Inspect local logs from a normal terminal:

acb logs --agent codex_a --tail 120
acb logs --task TASK-20260509-000000-00000000-0000-4000-8000-000000000000 --tail 120

Clear local runtime state without deleting .acb/config.json bindings:

acb clean tasks
acb clean logs
acb clean runtime --yes

Each submitted task also gets compact structured memory at .acb/agent-bridge/memory/tasks/<TASK_ID>.facts.json. Facts summarize objective, context, decisions, files, commands, risks, and evidence paths so agents can recover useful context without reading full logs.

To work from a source checkout instead:

npm install
npm run build
npm link

For lower-friction agent setup, install the portable automation rule bundle:

acb install-hooks

This creates .ai-crew-bridge/automation/agent-rules.md and .ai-crew-bridge/automation/hooks.md. Copy/adapt them into any AI IDE/CLI project rules.

Install native host templates when needed:

acb install-hooks --target kiro
acb install-hooks --target cursor
acb install-hooks --target codex
acb install-hooks --target claude
acb install-hooks --target trae

Or stage every supported host template at once:

acb install-hooks --target all-hosts

Codex hookify is separate from Codex MCP/rules because it is a local hook runner convention:

acb install-hooks --target codex-hookify

Current Tool Set

• bridge_register
• bridge_heartbeat
• bridge_list_members
• bridge_create_task
• bridge_list_tasks
• bridge_get_status
• bridge_wait_for_update
• bridge_claim
• bridge_read_spec
• bridge_submit_report
• bridge_read_report
• bridge_review
• bridge_render_dashboard

For long-running tasks, leaders should call bridge_wait_for_update(task_id, since_seq, timeout_ms) instead of model-level polling. The tool long-polls local event files and returns new events plus next_seq.

Supported Hosts

See templates/hosts/README.md for the current host matrix. The built-in executor command profiles are:

• Codex: codex exec ...
• Claude Code: claude -p ...
• Cursor Agent: cursor-agent --prompt ...
• Kiro CLI: kiro-cli chat --no-interactive ...
• Trae: IDE/MCP template support only until a stable public headless CLI is available.

Troubleshooting

Executor not receiving tasks

Check all processes use the same bridge_root. Set ACB_BRIDGE_ROOT explicitly for every harness.

Check acb-launcher is running. Queued events stay in outbox/<agent>.ndjson until delivered.

MCP server prints logs into client output

Normal MCP mode keeps stdout for JSON-RPC only. Diagnostics go to stderr.

Name conflict

An online agent with the same id already exists. Start wrapper with another --id, or wait for stale registry cleanup.

Development

npm test
npm run build