The Problem
Working across two machines with Claude Code looks like this: you're on your MacBook writing application code and you need something from the dev server. You open another terminal, SSH in, find the file, copy it, paste it back. Or worse, you're describing what you're looking at in one window to the AI in another window. It works, but it's slow and it breaks your flow.
The real cost isn't the time spent switching contexts. It's the mental overhead of being the human relay between two AI agents that could just talk to each other directly.
The Idea
A dead simple message bridge. No fancy protocols, no MCP overhead. Just a lightweight API with a SQLite database running in Docker. One Claude Code posts a question, the other one picks it up, answers it, and the first one keeps working.
Built as a CLI plugin because that's faster and gives you more control than MCP. Slash commands on both machines, a shared message channel, and nothing else getting in the way.
Architecture
MacBook
Claude Code + CLI Plugin
Sends questions, receives answers
API + SQLite
Docker container
Dev Server
Claude Code + CLI Plugin
Picks up tasks, executes work
The Build
The whole thing came together fast. The simplicity of the architecture meant there were very few moving parts to wire up: an API server, a CLI tool, a Docker deployment, and slash commands for both machines.
API Server
Lightweight Express API handling message routing between agents.
SQLite Database
Simple persistent storage for message queue. No external database needed.
Docker Deployment
Single container deployment on the dev server. Portable and self-contained.
CLI Plugin
Slash commands for Claude Code on both machines. Fast and scriptable.
# Send a message to the dev server
$ cc-bridge ask --channel dev-server "Send me the docker-compose.yml for media-orchestrator"
Posted to channel "dev-server"
ID: 44e2626d-0efa-4c77-9097-f3c3cc43795b
# Check for pending messages (on the dev server)
$ cc-bridge check --channel dev-server
1 pending message(s) on channel "dev-server"
# Reply to a message
$ cc-bridge reply --id 44e2626d "Here is the compose file contents..."
Reply sent.
The First Test
This is where it got interesting. The first real test was simple: ask the MacBook Claude Code to pull the Docker Compose file from the dev server. A basic file retrieval task to make sure the bridge worked.
But what happened next wasn't planned. The MacBook Claude Code received the compose file, reviewed it, found a configuration problem that wasn't even part of the original task, sent a fix instruction back to the dev server, and the dev server Claude Code made the edit and rebuilt the container. A task that was sitting on the to-do list for later got done as a side effect of testing the bridge.
MacBook sends request
"Pull the docker-compose.yml from the dev server"
Dev Server receives and responds
Reads the compose file and sends it back through the bridge
MacBook reviews the file
Claude Code spots a configuration issue, unprompted
MacBook sends fix instruction
Sends a targeted edit command back to the dev server
Dev Server applies fix and rebuilds
Edits the compose file and rebuilds the container
Unplanned Bug Fix in First Test
A to-do list item got resolved as a side effect of testing the bridge
$ cc-bridge ask --channel dev-server \
"Send me the docker-compose.yml for media-orchestrator"
Posted to channel "dev-server"
ID: 44e2626d-0efa-4c77-9097-f3c3cc43795b
Waiting for reply...............
Reply received.
Claude Code reviews the file and finds:
FEED_BASE_URL is not set.
The rss-feed service defaults to
https://feeds.production-app.com
but the dev server needs:
https://feeds.yourdomain.dev
# Sends fix instruction back through the bridge
$ cc-bridge ask --channel dev-server \
"Add FEED_BASE_URL=https://feeds.yourdomain.dev
to the rss-feed service environment and rebuild"
$ cc-bridge check --channel dev-server
1 pending message(s) on channel "dev-server"
# Reads the compose file and replies
Reply sent.
# Receives fix instruction, applies it
Update(docker-compose.yml)
312 - PORT=3003
313 - NODE_ENV=production
314 - API_BASE_URL=http://api:3010/api/v1
315 + - FEED_BASE_URL=https://feeds.yourdomain.dev
316 depends_on:
317 - api
$ docker compose up -d --build rss-feed
Building media-orchestrator-rss-feed...
Container mo-rss-feed Started
What This Actually Means
This isn't just two terminals talking to each other. It's a pattern where one AI agent can direct work on another machine. The MacBook becomes a reviewer and the dev server becomes the executor. The human stays in the loop on intent but doesn't have to be the relay.
Stacked messages mean you can batch up multiple tasks and let the dev server work through them while you move on to something else. The bridge turns two isolated Claude Code sessions into a coordinated system.
Agent-to-Agent Communication
One Claude Code instance can ask questions, request files, and send instructions to another. No human copy-paste required.
Reviewer + Executor Pattern
The MacBook acts as reviewer and architect. The dev server acts as executor. Each plays to its strengths.
Stacked Task Queuing
Batch multiple messages into the channel and let the remote agent work through them sequentially while you focus elsewhere.
What's Next
The pattern scales because the bridge is just an API that anything can talk to. The current implementation proves the concept. The roadmap is about making it more capable and expanding its reach.
Batch Message Support
Send multiple tasks in a single command and let the remote agent process them as a queue, reporting back on each as it completes.
Persistent Monitoring
Have the dev server continuously watch the message channel, picking up and executing tasks as they arrive without manual prompting.
Multi-Machine Expansion
Extend beyond two machines. Any environment with Claude Code and the CLI plugin can join the bridge: staging servers, cloud instances, additional dev machines.
Autonomous Workflows
Chain multi-step operations where one agent's output triggers the next agent's input, creating automated cross-machine workflows.
Why This Approach Works
The best infrastructure tools are the ones that get out of your way. cc-bridge works because it's minimal. No complex protocols, no heavy dependencies, no configuration sprawl. It's a message queue with an opinion about who's talking.
And sometimes the best features are the ones you didn't plan. The accidental infrastructure fix during the first test wasn't a fluke. It's what happens when you give AI agents the ability to see across machine boundaries. They find things you weren't looking for.
- Dead simple architecture: Express API, SQLite, Docker. Nothing exotic, nothing fragile.
- CLI-first design: Slash commands are faster than MCP for this use case and give full control over message flow.
- Emergent capability: The bridge enables behaviors neither agent could do alone: cross-machine review, remote execution, autonomous fixes.
- Pattern, not product: The value is the communication pattern. Any API-capable tool can plug into the same bridge.
