agent-bridge

agent-bridge is a local-first coordination tool for multiple coding agents working in the same repository.

It uses a documented .agent-bridge/ directory as a shared mailbox and cooperative locking protocol. The goal is not to make agents smarter. The goal is to keep them from stepping on each other while making their state, requests, and ownership visible to humans.

Why it exists

Modern coding work is increasingly multi-agent. A single project may involve:

• Codex
• Claude Code
• Gemini CLI
• Cline
• OpenCode
• OpenClaw
• custom internal agents

Those agents usually share a filesystem but not a coordination layer. agent-bridge gives them one.

What v0.1 does

• initializes a .agent-bridge/ workspace inside any project
• stores messages, status, and claims as plain JSON files
• generates prompt files for configured agents
• keeps agent identities data-driven through .agent-bridge/config.json
• supports cooperative claims and basic overlap protection
• stays dependency-free and local-first

Design choices

• file-based rather than daemon-based
• agent-agnostic rather than provider-specific
• JSON records for machine writes and automation
• Markdown guidance for humans and prompt templates
• no sockets, web server, or cloud dependency in v1

Scope

Goals:

• coordinate multiple coding agents in one project
• keep ownership and asks visible to humans
• stay simple enough for non-Python clients to interoperate later
• preserve local auditability through plain files

Non-goals:

• real-time delivery
• authentication and identity management
• distributed consensus
• semantic merge-conflict prevention
• provider-specific orchestration logic

Install

From the repo root:

python3 -m pip install -e .

Quick start

Initialize a project bridge:

agent-bridge init /path/to/project

List configured agents:

agent-bridge agents --root /path/to/project

Runtime commands still accept arbitrary agent names, even if they are not listed in config. Config controls the generated prompt set and shared metadata.

Get a specific prompt path:

agent-bridge prompt-path --root /path/to/project --agent claude

Send and receive work:

agent-bridge send --root /path/to/project --from codex --to claude --subject "Need review" --body "Please inspect src/auth/login.ts."
agent-bridge inbox --root /path/to/project --agent claude
agent-bridge show --root /path/to/project MESSAGE_ID
agent-bridge ack --root /path/to/project MESSAGE_ID --by claude

Coordinate edits:

agent-bridge status-set --root /path/to/project --agent codex --text "Refactoring login validation"
agent-bridge claim --root /path/to/project --agent codex --scope "src/auth/*" --note "Updating login flow"
agent-bridge claims --root /path/to/project
agent-bridge release --root /path/to/project CLAIM_ID

Commands

• init
• agents
• prompt-path
• send
• inbox
• show
• ack
• status-set
• status-show
• claim
• claims
• release

Run agent-bridge <command> --help for details.

On-disk layout

.agent-bridge/
  config.json
  README.md
  .gitignore
  messages/
  status/
  claims/
  prompts/

The protocol details live in docs/protocol.md.

Prototype note: earlier local experiments in this repo used Markdown files for bridge runtime records. The standalone agent-bridge tool standardizes runtime records on JSON.

Examples

See examples/multi-agent-workflow.md.

Contributing and testing

Run the test suite:

python3 -m unittest discover -s tests -v

Bytecode sanity check:

python3 -m compileall src tests

Compatibility guidance:

• prefer additive JSON fields over breaking record changes
• tolerate unknown fields when reading records
• keep CLI verbs stable when possible
• treat prompt templates as optional convenience, not protocol requirements

Limits

• cooperative locking only
• best on one local filesystem
• no real-time delivery
• no cross-machine identity or auth model
• no semantic overlap detection between glob scopes

Publishing notes

This repo is licensed under the MIT License.