AI Bridge MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
Related MCP server: CC2CC
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 install2. 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.jsonautomatically from your project rootClaude.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 |
| Yes |
| Directory for bridge data files |
| No |
| Path to your governance document |
Tools
Constitution Governance
Tool | Description |
| Read the full governing document. Required at session start. Marks it as read in session metadata. If skipped, every tool response includes a warning. |
| Look up a specific section by number, name, or keyword (e.g., |
Coding Agent Tools
Tool | Description |
| Write a structured status update: what happened, what was found, what's next, any blockers. Supports tags for filtering ( |
| Read the latest directive from the advisory agent. Call before every major action. Supports per-agent targeting via |
| Confirm receipt of guidance. The advisory agent can verify delivery via |
Advisory Agent Tools
Tool | Description |
| Read recent checkpoints. Filter by count, timestamp, tag, or agent ID. Returns clean structured data. |
| Write a directive with optional questions, approved actions, and priority level ( |
| 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 |
| Quick overview: last checkpoint, pending guidance, constitution status, per-agent guidance state. |
| Archive current session and start fresh. Preserves history in |
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 3Set 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
Copy
hooks/bridge-hook.jsinto your projectAdd 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-injectingStale 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:
Soft (default) — Warning in tool responses when constitution isn't read
Medium — First checkpoint must include
constitution-readtag or it gets flaggedHard — 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 |
|
Plan submitted |
|
Major finding |
|
Code committed |
|
Build/deploy result |
|
Test result |
|
Blocker or escalation |
|
Session end |
|
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 |
| JSON Lines | Append-only checkpoint log |
| JSON | Current broadcast guidance (overwritten each time) |
| JSON | Per-agent targeted guidance |
| JSON Lines | All guidance ever written |
| JSON | Session state (counts, timestamps, ack status) |
| Directory | Archived sessions from |
Raw Terminal Capture (Optional)
For the read_raw_log tool, launch your coding agent with:
script -q /path/to/your-project/bridge/session.log claudeThis 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.jsonlshows you everythingPortable — Point
BRIDGE_DIRat any project. Works with any stack.Version-controllable — Add bridge files to
.gitignoreor commit them for audit trailsMulti-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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Agents message each other and partners' agents. Claude Code, Codex (beta): memory, board, key vault.
Keeps AI coding agents on one codebase from overwriting each other, and briefs each on its code.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables real-time messaging between Claude Code instances, allowing agents to send, receive, and reply to messages instantly via file-based communication with auto-notification.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables file-based agent-to-agent communication between Claude Code instances on the same machine, using MCP channels and plain JSON files.5 npm15MIT
- AlicenseAqualityDmaintenanceLocal inter-agent messaging for AI coding agents via filesystem relay.42MIT
- AlicenseNot gradedqualityCmaintenanceEnables real-time, file-based messaging between terminal AI agents (like Claude Code, Gemini CLI) allowing them to collaborate on tasks directly without a server or network, using JSON files and atomic rename for coordination.16 PyPIMIT