AgentBridge
Decouple AI reasoning from code execution.
Use one AI as the Brain and another as the Executor.
AgentBridge connects web-based AI assistants such as Gemini, ChatGPT, and Claude to local coding agents such as OpenCode through MCP, allowing them to collaborate on the same local workspace.
Let the AI with the best reasoning access think. Let the coding agent you already pay for execute.
Why AgentBridge?
Modern AI coding tools often combine two very different jobs:
- Reasoning — understanding the codebase, investigating problems, designing an implementation, reviewing changes.
- Execution — editing files, running commands, running tests, and applying the implementation.
But the AI product that is best for reasoning is not necessarily the AI product you want to spend your coding-agent quota on.
For example, you may have:
- a web AI account with a generous usage allowance and excellent reasoning;
- a coding CLI subscription with more limited agent usage;
- a local coding workspace where the actual implementation needs to happen.
Without a bridge, you have to choose one AI and use its quota for everything.
AgentBridge separates these responsibilities.
REASONING
┌─────────────────┐
│ Web AI │
│ Gemini / Claude │
│ ChatGPT / ... │
└────────┬────────┘
│
│ MCP
▼
┌─────────────────┐
│ AgentBridge │
│ │
│ Read workspace │
│ Create PLAN │
│ Review result │
└────────┬────────┘
│
C2C PLAN
│
▼
┌─────────────────┐
│ Executor │
│ OpenCode │
│ / ... │
└────────┬────────┘
│
edit / test / run
│
▼
┌─────────────────┐
│ Local Workspace │
└─────────────────┘
The important idea is simple:
Don't make one AI do everything. Let each AI do the job it is best suited for.
The Core Concept
AgentBridge introduces two explicit roles.
🧠 Brain
The Brain is the AI you use for reasoning.
It can:
- inspect your project;
- search the codebase;
- understand architecture;
- investigate bugs;
- design implementation strategies;
- create implementation plans;
- review the changes made by the Executor.
The Brain does not modify your files.
It only sees the workspace through AgentBridge's read-only MCP interface.
🛠️ Executor
The Executor is the coding agent responsible for execution.
It can:
- modify files;
- run commands;
- run tests;
- implement the Brain's plan;
- report the execution result.
In the current version, AgentBridge uses OpenCode as the Executor.
The architecture is intentionally designed around an Executor interface so additional coding agents can be integrated later.
🌉 AgentBridge
AgentBridge is the layer between them.
It provides:
- MCP access to the local workspace;
- read-only project inspection;
- structured task delegation;
- task lifecycle management;
- execution status;
- Git diff inspection;
- test status;
- result reporting.
The Brain never needs to receive your entire repository in its prompt.
Instead, it explores the real workspace through MCP.
The Workflow
A typical AgentBridge workflow looks like this:
1. User gives a coding task
│
▼
2. Brain inspects the workspace
│
▼
3. Brain reasons about the problem
│
▼
4. Brain creates a compact PLAN
│
▼
5. AgentBridge sends the PLAN to Executor
│
▼
6. Executor edits files and runs tests
│
▼
7. AgentBridge records the result
│
▼
8. Brain inspects git diff + test status
│
▼
9. Brain reviews the implementation
│
┌──┴───────────────┐
│ │
DONE PLAN AGAIN
│
▼
another iteration
This creates a simple feedback loop:
PLAN → EXECUTE → REVIEW → DONE
↑ │
└── PLAN ────┘
The Brain can therefore remain focused on high-value reasoning while the Executor handles the mechanical work of changing the codebase.
Why This Can Save AI Coding Quota
AI coding subscriptions are often metered differently from normal chat or web usage.
A coding agent may consume quota while:
- reading files;
- exploring the repository;
- searching for definitions;
- reasoning about architecture;
- generating an implementation;
- editing files;
- running tests;
- retrying failed implementations.
This means a single coding agent can spend a significant amount of its allowance before it even starts writing useful code.
AgentBridge allows you to move the exploratory and reasoning-heavy part to another AI interface.
For example:
Gemini Web
│
│ reasoning / architecture / planning
▼
AgentBridge
│
│ compact implementation plan
▼
OpenCode CLI
│
│ implementation / tests
▼
Your repository
Instead of spending your coding-agent quota on the entire conversation, you can reserve it primarily for the part that actually requires local execution.
The goal is not to bypass quotas.
AgentBridge does not provide additional model credits, circumvent provider limits, or access paid models without authorization.
It simply lets you route work between the AI services and coding agents you already use.
A Different Way to Think About AI Coding
Most AI coding workflows look like this:
User
│
▼
One AI
│
├── understand project
├── reason
├── plan
├── edit files
├── run tests
└── review
AgentBridge turns it into:
User
│
▼
Brain
│
├── understand
├── reason
├── plan
└── review
│
▼
AgentBridge
│
▼
Executor
│
├── edit
├── run
└── test
This is the fundamental design principle behind AgentBridge:
Reasoning and execution are separate resources.
You can choose the best AI for each one.
MCP as the Bridge
AgentBridge uses the Model Context Protocol (MCP) to connect the Brain to your local workspace.
The Brain gets structured tools for inspecting the project:
| Tool | Purpose |
|---|---|
workspace_info |
Project information and Git status |
list_directory |
Explore the workspace |
read_file |
Read a file |
search_workspace |
Search source code |
git_status |
Inspect repository state |
git_diff |
Review Executor changes |
test_status |
Read the latest recorded test result |
execution_summary |
Read the Executor result |
The Brain does not receive a generic shell interface.
It also cannot directly write files.
This separation is intentional.
C2C: Brain-to-Executor Protocol
AgentBridge uses a small structured protocol called C2C (Context-to-Context) to communicate between the Brain and Executor.
Instead of sending source code or a huge conversation to the coding agent, the Brain produces a compact implementation plan:
[C2C]
STATE: PLAN
TASK_ID: c2c_12345
ITERATION: 1
GOAL:
Add URL inspection to the GSC client.
ACTIONS:
1. Inspect the current GSC client.
2. Add URL inspection support.
3. Add tests for indexed and non-indexed URLs.
TESTS:
cargo test
SUCCESS_CRITERIA:
Tests pass and the API correctly reports indexed / not-indexed.
The source code stays in the local workspace.
Only the intent and implementation contract cross the Brain → Executor boundary.
This has two important benefits:
- Lower context overhead
- Clear separation of responsibility
The Brain does not need to paste your repository into the Executor's prompt.
The Executor works directly against the same local workspace.
Read-Only Brain, Write-Capable Executor
One of the most important design decisions in AgentBridge is the trust boundary.
The Brain can inspect:
workspace
├── source files
├── project structure
├── Git status
├── Git diff
└── test results
But it cannot:
✗ write files
✗ delete files
✗ execute shell commands
✗ commit
✗ push
The Executor is the component that performs those actions.
This gives the architecture a clear separation:
Read-only
│
▼
┌───────────┐
│ Brain │
└─────┬─────┘
│
PLAN
│
▼
┌───────────┐
│ Executor │
└─────┬─────┘
│
Write / Execute
│
▼
Local Project
The Brain decides what should happen.
The Executor decides how to execute the supplied plan inside the coding environment.
Quick Start
1. Install
Requirements:
- Rust 1.88+
- Git
- OpenCode
- An MCP-capable AI client
Clone and install AgentBridge:
2. Initialize a Workspace
Point AgentBridge at the project you want the Brain to inspect:
This creates the AgentBridge configuration and associates the MCP server with that workspace.
3. Start the MCP Server
By default, AgentBridge listens on:
http://127.0.0.1:8787/mcp
The default configuration is intentionally localhost-only.
4. Connect Your Brain
Connect a compatible MCP client such as Gemini, Claude, ChatGPT, or another MCP-capable AI client to AgentBridge.
Then provide the Brain instructions from:
skill/SKILL.md
The skill teaches the AI how to:
- inspect the workspace;
- create a C2C PLAN;
- delegate the task;
- monitor execution;
- inspect the result;
- review the changes;
- finish or create another iteration.
5. Give the Brain a Task
For example:
Add Google Search Console URL inspection support to this project.
First understand the existing architecture.
Then create an implementation plan and delegate it to the Executor.
After implementation, review the diff and test results.
The Brain can inspect the actual repository rather than relying on files pasted into the conversation.
Exposing AgentBridge to a Web AI
If your Brain runs in a web environment and cannot access localhost directly, you can expose AgentBridge through a tunnel.
For example, with Cloudflare Tunnel:
Then:
Your MCP endpoint will be available at:
https://<your-tunnel-id>.trycloudflare.com/mcp
Cloudflare Tunnel is optional.
AgentBridge itself works entirely locally.
Security: If you expose AgentBridge outside localhost, use authentication and understand that the remote Brain can read the workspace exposed by the server. Never point AgentBridge at your entire home directory.
See Security for details.
CLI
Use:
to check:
- workspace configuration;
- Git availability;
- MCP configuration;
- server port;
- optional Cloudflare Tunnel configuration;
- Executor availability.
Configuration
AgentBridge stores global configuration in:
~/.agentbridge/config.toml
and workspace-specific configuration in:
<workspace>/.agentbridge.toml
Example:
= "/absolute/path/to/project"
= "127.0.0.1"
= 8787
[]
= 1048576
= true
Security
AgentBridge is designed around a simple security model:
The remote Brain receives a read-only view of the configured workspace.
Path traversal and sensitive files are explicitly restricted.
Examples of blocked paths include:
../
/etc/passwd
C:\Users\...
~/.ssh
.env
*.pem
*.key
id_rsa
Important recommendations:
- Point AgentBridge at a single project.
- Do not expose your home directory.
- Keep the default localhost binding whenever possible.
- If you expose the server remotely, configure authentication.
- Treat the Brain as an external service with access to the workspace you explicitly expose.
AgentBridge is a local developer tool, not a multi-tenant security boundary.
See docs/security.md.
Architecture
The project is intentionally small and has clear boundaries:
AgentBridge
│
├── MCP Server
│ └── Exposes workspace inspection tools
│
├── Workspace
│ └── Filesystem access with security restrictions
│
├── Task Runtime
│ └── PLAN → EXECUTE → RESULT lifecycle
│
├── C2C Protocol
│ └── Compact Brain → Executor communication
│
├── Executor
│ └── Runs the local coding agent
│
└── Git / State
└── Tracks changes and execution results
The important boundary is:
Remote Brain
│
MCP API
│
┌───────▼───────┐
│ AgentBridge │
└───────┬───────┘
│
C2C PLAN
│
┌───────▼───────┐
│ Executor │
└───────┬───────┘
│
Local process
│
┌───────▼───────┐
│ Workspace │
└────────────────┘
What AgentBridge Is Not
AgentBridge is not another AI coding agent.
It does not attempt to replace:
- Gemini
- ChatGPT
- Claude
- OpenCode
- Codex
- your editor
- your existing development workflow
Instead, it connects them.
AgentBridge also does not:
- provide AI models;
- provide additional model credits;
- bypass subscription limits;
- proxy model APIs;
- upload your repository to a hosted service.
It is a local bridge between AI reasoning and local code execution.
Current Status
AgentBridge is currently focused on the Brain / Executor workflow.
Current implementation:
- Rust-based local MCP server
- workspace inspection
- secure path handling
- Git status and diff inspection
- structured C2C task protocol
- task lifecycle management
- OpenCode Executor integration
- execution status and result reporting
- Brain skill instructions
- local-first architecture
The Executor abstraction is designed to support additional coding agents as the project evolves.
Roadmap
Potential future directions include:
- More Executor backends
- Better task orchestration
- Executor selection and routing
- Parallel task execution
- Improved context optimization
- Persistent task history
- More Brain integrations
- Better IDE integration
- Richer review workflows
The goal is not to build another monolithic AI coding product.
The goal is to make the AI coding stack composable.
Development
Requires:
Rust 1.88+
Git
Philosophy
AI coding does not have to be a single-agent problem.
Different AI products have different strengths, interfaces, context windows, pricing models, and usage limits.
Instead of forcing one agent to handle everything, AgentBridge treats AI coding as a distributed workflow:
THINK
│
▼
PLAN
│
▼
EXECUTE
│
▼
REVIEW
│
▼
DONE
Use the AI that is best at thinking.
Use the coding agent that is best at doing.
Use AgentBridge to connect them.
License
MIT