# AI Bridge MCP

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**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

```bash
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`

```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:

```bash
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](https://docs.anthropic.com/en/docs/claude-code/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`:

```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`](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:

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

See [AXIS PRAXIS](https://github.com/robertjorndorff-collab/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:

```json
{
  "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:

```bash
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*