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