agent-bridge

Unified Python interface for AI coding agents. Send a message, get a response — regardless of whether the backend is Claude Code, Codex, or OpenCode.

Quick Start

from agent_bridge import send_message

output, session_id = send_message(
    "explain this codebase",
    workspace="/path/to/project",
    backend="claude",          # "claude", "codex", or "opencode"
    permission_allow_all=True, # auto-approve tool use
)
print(output)

# Resume conversation
output2, _ = send_message("now add tests", workspace="/path/to/project",
                          backend="claude", session_id=session_id)

CLI Demo

python demo.py --backend claude --workspace /tmp/test "hello"
python demo.py --backend codex --workspace . --allow-all "create hello.py"
python demo.py --backend opencode --workspace . "explain main.go"

Architecture

AgentBackend (base.py)              — ABC with single abstract method: run()
  ├── JsonRpcBackend (jsonrpc.py)   — owns JsonRpcTransport, notification drain loop
  │     ├── AcpBackend (acp.py)     — OpenCode (and any future ACP agent)
  │     └── McpBackend (mcp.py)     — Codex
  └── ClaudeCliBackend (claude.py)  — Claude Code (streaming JSON, not JSON-RPC)

All backends implement run(message, cwd, session_id, allow_all) → AgentResponse.

• JSON-RPC backends (ACP, MCP) inherit from JsonRpcBackend, which provides subprocess management via JsonRpcTransport and a concurrent notification processing loop. Subclasses only implement protocol-specific hooks: initialize, start_session, send_prompt, handle_notification, get_session_id.

• Non-JSON-RPC backends (Claude CLI) inherit from AgentBackend directly and manage their own subprocess lifecycle inside run().

File Structure

File	Purpose
__init__.py	Public API: send_message() + backend factory
base.py	AgentBackend ABC + _clean_env() helper
jsonrpc.py	JsonRpcTransport (JSON-RPC over stdio) + JsonRpcBackend (abstract)
acp.py	AcpBackend — ACP protocol (OpenCode, etc.)
mcp.py	McpBackend — MCP protocol (Codex)
claude.py	ClaudeCliBackend — Claude Code streaming JSON
config.py	AgentConfig dataclass + PRESETS dict
types.py	AgentResponse dataclass
demo.py	CLI demo script

Adding a New Agent

Standard ACP agent (e.g. Cursor)

Just add a config preset in config.py — zero new files, zero new classes:

"cursor": AgentConfig(
    name="cursor",
    spawn_cmd=("cursor-agent", "acp"),
    protocol="acp",
),

It will automatically use AcpBackend which handles the full ACP lifecycle.

Standard MCP agent

Same idea, set protocol="mcp":

"my-mcp-agent": AgentConfig(
    name="my-mcp-agent",
    spawn_cmd=("my-agent", "mcp-server"),
    protocol="mcp",
),

Custom protocol agent

1. Create a new file (e.g. my_agent.py)
2. Subclass AgentBackend and implement run()
3. Register the protocol in _create_backend() in __init__.py
4. Add a config preset

Debug

By default, agent-bridge produces no log output. Set AGENT_BRIDGE_DEBUG for diagnostics:

Level	Output
0 (default)	Silent
1	Key events: spawn, pid, session, request/response, errors
2	Verbose: every notification, raw I/O, subprocess stderr

AGENT_BRIDGE_DEBUG=1 python demo.py --backend codex --workspace . "hello"
AGENT_BRIDGE_DEBUG=2 python demo.py --backend codex --workspace . "hello"