AI Bridge MCP

AI Bridge MCP


Multi-agent coordination for Claude Code. File-based. No database. No WebSocket. Just structured JSON on disk.

---

The Problem

You're running Claude Code in a terminal. You have Claude.ai open for strategy. Maybe a second Claude Code instance for parallel work. And you — the human — become the bottleneck:

• Copy-pasting terminal output into Claude.ai
• Relaying directives back: "Claude.ai says to try X"
• Losing context when you forget to forward a message
• No shared record of what was decided or why

Your job should be strategic oversight, not message relay.

The Solution

A shared MCP server that both agents connect to. The coding agent writes structured checkpoints. The advisory agent reads them and writes guidance back. Everything goes through files on disk — no servers, no databases, no infrastructure.

┌─────────────────────┐                          ┌─────────────────────┐
│   Advisory Agent     │                          │    Coding Agent     │
│  (Claude.ai / chat)  │                          │  (Claude Code / CLI)│
└──────────┬──────────┘                          └──────────┬──────────┘
           │                                                │
           │  write_guidance()                              │  write_checkpoint()
           │  read_checkpoints()                            │  read_guidance()
           │  read_raw_log()                                │  ack_guidance()
           ▼                                                ▼
     ┌─────────────────────────────────────────────────────────┐
     │                    BRIDGE_DIR (on disk)                  │
     │                                                         │
     │  bridge-checkpoints.jsonl    ← append-only status log   │
     │  bridge-guidance.json        ← current directive        │
     │  bridge-guidance-agent1.json ← per-agent targeting      │
     │  bridge-meta.json            ← session state            │
     │  CONSTITUTION.md             ← governance rules         │
     └─────────────────────────────────────────────────────────┘
                              ▲
                              │
                     ┌────────┴────────┐
                     │     Human       │
                     │   (overseer)    │
                     └─────────────────┘

Quick Start

1. Clone and install

git clone https://github.com/robertjorndorff-collab/ai-bridge-mcp.git
cd ai-bridge-mcp
npm install

2. Add to your project's .mcp.json

{
  "mcpServers": {
    "ai-bridge": {
      "command": "node",
      "args": ["/path/to/ai-bridge-mcp/src/index.js"],
      "env": {
        "BRIDGE_DIR": "/path/to/your-project/bridge"
      }
    }
  }
}

BRIDGE_DIR is where checkpoint and guidance files are stored. Both agents must point to the same directory.

3. Connect both agents

• Claude Code: Picks up .mcp.json automatically from your project root
• Claude.ai: Add as an MCP integration in settings (same server, same BRIDGE_DIR)

That's it. Both agents can now communicate through the bridge.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BRIDGE_DIR | Yes | . (cwd) | Directory for bridge data files | | CONSTITUTION_FILE | No | ../CONSTITUTION.md (relative to BRIDGE_DIR) | Path to your governance document |

Tools

Constitution Governance

| Tool | Description | |------|-------------| | read_constitution | Read the full governing document. Required at session start. Marks it as read in session metadata. If skipped, every tool response includes a warning. | | check_section | Look up a specific section by number, name, or keyword (e.g., §7.7, Red X, deploy). More efficient than re-reading the entire document. |

Coding Agent Tools

| Tool | Description | |------|-------------| | write_checkpoint | Write a structured status update: what happened, what was found, what's next, any blockers. Supports tags for filtering (deploy, test, blocker, etc.). | | read_guidance | Read the latest directive from the advisory agent. Call before every major action. Supports per-agent targeting via agent_id. | | ack_guidance | Confirm receipt of guidance. The advisory agent can verify delivery via get_bridge_status. |

Advisory Agent Tools

| Tool | Description | |------|-------------| | read_checkpoints | Read recent checkpoints. Filter by count, timestamp, tag, or agent ID. Returns clean structured data. | | write_guidance | Write a directive with optional questions, approved actions, and priority level (normal, urgent, blocker). Supports per-agent targeting. | | read_raw_log | Read the raw terminal session log with ANSI codes stripped and noise filtered. For deep investigation when checkpoints aren't enough. |

Shared Tools

| Tool | Description | |------|-------------| | get_bridge_status | Quick overview: last checkpoint, pending guidance, constitution status, per-agent guidance state. | | reset_bridge | Archive current session and start fresh. Preserves history in bridge-archive/. |

Multi-Agent Setup

Running multiple coding agents? Each one needs a unique ID so guidance can be targeted:

AGENT_ID=agent1 claude   # Terminal 1
AGENT_ID=agent2 claude   # Terminal 2
AGENT_ID=agent3 claude   # Terminal 3

Set CLODE_AGENT_ID (or any env var your hooks use) so the bridge can route per-agent guidance to the right terminal. The advisory agent targets specific agents with:

write_guidance(target_agent: "agent1", directive: "Focus on the API refactor")
write_guidance(target_agent: "agent2", directive: "Run the test suite")

Each agent reads only its own guidance (or broadcast guidance targeted to "all").

Auto-Read Hooks

Claude Code supports hooks — shell commands that fire on specific events. Use the included hooks/bridge-hook.js to auto-inject guidance whenever the user sends a message:

Setup

1. Copy hooks/bridge-hook.js into your project
2. Add to .claude/settings.local.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node path/to/bridge-hook.js"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "mcp__ai-bridge__write_checkpoint",
        "hooks": [
          {
            "type": "command",
            "command": "node path/to/bridge-hook.js"
          }
        ]
      }
    ]
  }
}

See examples/settings.local.json for a complete example.

How it works

• UserPromptSubmit: Every time the human sends a message, the hook reads the bridge for new guidance and injects it into context
• PreToolUse: Before writing a checkpoint, the hook checks for guidance first (so the agent can incorporate it)
• Deduplication: The hook tracks the last-seen guidance timestamp in .bridge-last-seen-{agentId} to avoid re-injecting
• Stale detection: If the last-seen file is >1 hour old (session restart), it clears automatically

Important limitation

Hooks only fire on user action (message sent, tool called). There is no push mechanism — if the advisory agent writes guidance while the coding agent is idle, it won't be seen until the user next interacts. Mitigate this by having agents poll read_guidance() before going idle.

Constitution Enforcement

The bridge optionally enforces a governance document (any markdown file). Three levels:

1. Soft (default) — Warning in tool responses when constitution isn't read
2. Medium — First checkpoint must include constitution-read tag or it gets flagged
3. Hard — Tools refuse to execute until read_constitution() is called

The constitution file is referenced by path, never copied into the bridge directory. Use check_section() to look up specific rules mid-session without re-reading the whole document.

Writing a constitution

Any markdown file works. The check_section tool searches by ## Article and ### § headers. Structure your rules with headers like:

## Article I — Chain of Command
### §1.1 Role Boundaries
...
## Article II — Code Quality
### §2.1 Error Handling
...

See AXIS PRAXIS for a real-world example used in production.

Checkpoint Protocol

The coding agent should write checkpoints at natural milestones:

| Trigger | Example Tags | |---------|-------------| | Session start | session-start, constitution-read | | Plan submitted | plan, needs-approval | | Major finding | diagnosis, evidence | | Code committed | commit, deploy | | Build/deploy result | build, deploy, success / failure | | Test result | test, pass / fail | | Blocker or escalation | blocker, needs-guidance | | Session end | session-end, handoff |

Guidance Protocol

The advisory agent writes structured directives:

{
  "from": "Advisory Agent",
  "directive": "Refactor the auth module to use JWT instead of sessions",
  "questions": ["What's the current session storage mechanism?"],
  "approvals": ["Modify auth middleware", "Add jsonwebtoken dependency"],
  "priority": "urgent",
  "target_agent": "agent1"
}

The coding agent reads guidance before major actions, acknowledges receipt, and answers questions in its next checkpoint. The advisory agent verifies delivery via get_bridge_status.

Data Files

All stored in BRIDGE_DIR:

| File | Format | Purpose | |------|--------|---------| | bridge-checkpoints.jsonl | JSON Lines | Append-only checkpoint log | | bridge-guidance.json | JSON | Current broadcast guidance (overwritten each time) | | bridge-guidance-{agent}.json | JSON | Per-agent targeted guidance | | bridge-guidance-history.jsonl | JSON Lines | All guidance ever written | | bridge-meta.json | JSON | Session state (counts, timestamps, ack status) | | bridge-archive/ | Directory | Archived sessions from reset_bridge |

Raw Terminal Capture (Optional)

For the read_raw_log tool, launch your coding agent with:

script -q /path/to/your-project/bridge/session.log claude

This records the full terminal session. The advisory agent can search it with grep filters, ANSI codes auto-stripped.

Why File-Based?

• Zero infrastructure — No database, no Redis, no WebSocket server
• Works offline — Just files on disk
• Inspectable — cat bridge-checkpoints.jsonl shows you everything
• Portable — Point BRIDGE_DIR at any project. Works with any stack.
• Version-controllable — Add bridge files to .gitignore or commit them for audit trails
• Multi-agent native — Per-agent guidance files scale to any number of agents

Origin

Built at 3 AM during a session where the human spent two hours copy-pasting terminal output between Claude Code and Claude.ai. The human should oversee. The machines should talk to each other.

License

MIT

---

R.J. Orndorff LLC · 2026