AgentBridge

AgentBridge

Status: mid-migration, and this README describes the older shape.

AgentBridge started as a Claude-Code-to-Codex/Antigravity bridge, andeverything documented below works today. It is being generalised so that anysupported CLI can be the orchestrator and any other can be a worker, withrouting driven by a per-user profile instead of hardcoded model names.

For where it is going, read docs/architecture.md anddocs/roles.md. In-flight: a provider adapter layer(src/providers/), a routing profile (src/profile/), and anagentbridge init setup flow. The Cursor adapter is present butunverified — its flags were written from prior knowledge rather than readoff an installed CLI, and it says so at the top of the file.

Until the migration lands, treat the sections below as accurate forCodex and Antigravity workers, and the docs as accurate for the design.

Orchestrators

AgentBridge serves its /agentbridge … command surface as MCP prompts, soany MCP client that supports prompts/list gets the same commands from theserver itself — no per-host command files to install or keep in sync.

The doctrine behind those commands lives in doctrine/ and names nomodels — it routes by role, and .agentbridge/profile.json mapsroles onto whatever the user actually has installed.

A small local stdio MCP server that lets Claude Code delegate work to theCodex CLI and the Antigravity CLI (agy) as external workers — usingthe CLI sessions you are already logged into, with no API keys.

Claude stays the orchestrator. AgentBridge is deliberately dumb plumbing: itturns Claude's structured request into a worker prompt, runs the CLI, and handsback a compact structured result.

User
 └─> Claude Code                      (orchestrator — decides what to delegate)
      └─> AgentBridge MCP tool        (codex_run / antigravity_run)
           └─> codex exec  |  agy --print
                └─> result
           <─ structured MCP result
      <─ Claude inspects the work and continues

What it is not

No cloud service, web UI, database, daemon, dashboard, job queue, accountsystem, or API-key management. It is one Node process that Claude Code startsover stdio and stops when it exits.

How it works

1. Claude calls codex_run or antigravity_run with a structured request(goal, mode, model, effort, paths, contract, acceptance criteria…).
2. AgentBridge assembles a worker prompt from exactly those fields. It runs nomodel of its own — this is string assembly, not inference.
3. It reserves write scopes, snapshots the git working tree, and spawns the CLIwith an argument array (shell: false).
4. It parses the CLI's machine-readable output, extracts the worker's finalresult (never its internal reasoning), diffs the git tree to determine whatactually changed, and returns a compact JSON result.

One MCP call = one worker attempt. AgentBridge never retries. Whetheranother attempt is worthwhile is Claude's decision.

Requirements

AgentBridge never reads, copies, exports, or modifies your Codex or Antigravitycredentials. It invokes the CLIs exactly as a logged-in human would.

Install and build

npm install

npm run build

npm test

The test suite uses mocked processes throughout, so a normal npm test consumesno model quota.

Register with Claude Code

Register once at user scope so every project can use it:

claude mcp add --transport stdio --scope user agentbridge -- node D:\Code\Agentbridge\dist\index.js

Verify from a terminal:

claude mcp list

claude mcp get agentbridge

Then verify from inside Claude Code by running /mcp. You should seeagentbridge listed as connected, with three tools: codex_run,antigravity_run, bridge_status. Ask Claude to call bridge_status for afull health report.

If you rebuild AgentBridge, restart Claude Code (or reconnect the server from/mcp) so it picks up the new dist/.

Project directory

Workers run in, and are scoped to, a single project directory, resolved in thisorder:

1. AGENTBRIDGE_PROJECT_DIR, then the legacy CLAUDE_PROJECT_DIR (which Claude Code exports).
2. The first file:// root the MCP client advertises.
3. The server process's working directory.

bridge_status reports which one was used.

Tools

codex_run

Models. Three slugs are addressable, and each is passed to the CLI verbatim:

Effort mapping (orchestrator label → Codex model_reasoning_effort):

The mapping is total and deterministic. Codex's ultra tier is deliberately notexposed: only some models offer it, and a sixth label that works for two of threemodels would make routing model-dependent.

Availability. Before launching, AgentBridge checks the requested model andeffort against the Codex CLI's own model catalogue (models_cache.json inCODEX_HOME) — a file read, no inference.

• model listed, effort listed → the job runs
• model listed, effort not → invalid_effort, with details.supported_efforts
• model not listed → requested_model_unavailable, with details.available_models
• no readable catalogue → the job runs anyway, with a warning that availabilitywas unverified

Nothing is ever substituted for anything else. A routing decision that cannot behonoured comes back as a structured error carrying enough metadata to reroute inone step, rather than as a quietly weaker model.

The invocation built is:

codex exec --json --skip-git-repo-check -m <MODEL> -c model_reasoning_effort="<EFFORT>" \
           -s <read-only|workspace-write> -C <PROJECT> -o <tmpfile> --color never

with the prompt streamed over stdin. Model, effort and sandbox are passed onevery call, so a run never inherits whatever happens to be set in~/.codex/config.toml.

analyze and review use Codex's real read-only sandbox — writes aregenuinely prevented, not merely discouraged.

antigravity_run

Same schema, with:

Logical names are resolved at run time against the live agy models list:

Antigravity encodes the reasoning tier in the model id, so model + effortresolve to a single id and no separate --effort flag is sent — the two cannever disagree. Flash has only these three tiers: extra high and max returninvalid_effort rather than quietly running a weaker tier than you asked for.

Antigravity is intentionally scoped to the cheap Gemini tier. The Claude modelsthat agy also offers are not exposed as routable labels — for Claude-classreasoning, use Claude Code itself or Codex, which have real sandboxing and(for Codex) selectable effort.

The label has an ordered candidate list of ids for the same model. If noneof them are offered by the installed CLI, the call fails withrequested_model_unavailable and the full available-model list. It neversilently falls back to a different model. The resolved id is echoed back inwarnings on every run.

The invocation built is:

agy --print <PROMPT> --model <RESOLVED_ID> --output-format json \
    --mode <plan|accept-edits> --add-dir <PROJECT> \
    --dangerously-skip-permissions --print-timeout <N>s

--disable-slash-commands is added only for implement runs: the CLI ignores--mode plan whenever slash-command expansion is disabled, so sending both wouldsilently discard the only no-write behaviour Antigravity offers.

bridge_status

No arguments. Consumes no model inference — it only runs --version probes,agy models, one git rev-parse, and a read of the Codex CLI's model cache.

Returns:

• AgentBridge version, project directory (and how it was resolved), node/platform
• git_verification — whether git-based files_changed / scope_violations willwork here at all. When it will not, an empty scope_violations is silence, nota clean bill of health, and the warnings say so
• codex.installed / version / path / auth
• codex.model_status — per model: available | unavailable | unverified,the AgentBridge effort labels it accepts, and the CLI's raw reasoning levels
• codex.model_source — where availability came from and how fresh it is
• antigravity.installed / version / path / auth, detected models, how eachlogical label + tier resolved, and model_status in the same three-state shape
• antigravity.unsupported_efforts — the orchestrator labels Flash cannot take
• active jobs and their write scopes
• warnings

Availability is never guessed. When the installed CLI offers no cheap proof, thestatus is unverified rather than a claim in either direction.

It never returns credentials or environment variables.

Result format

{
  "status": "success",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "effort": "high",
  "mode": "implement",
  "duration_ms": 12345,
  "exit_code": 0,
  "summary": "...",
  "files_changed": ["src/upload.ts"],
  "scope_violations": [],
  "tests_or_checks_run": ["npm test -- upload"],
  "test_results": "12 passed",
  "concerns_or_blockers": [],
  "stderr_tail": "",
  "warnings": []
}

effort is present for both providers — the Codex reasoning level, or the Flash tier the model id encodes. files_changed and scope_violations arecomputed by AgentBridge from git, not taken from the worker's word. Internalreasoning is dropped. summary is capped at 16 000 characters, keeping the headand tail and setting summary_truncated: true when it clips.

Errors

Failures return the same envelope shape with status: "failed", an errorcategory, an actionable message, and — where available — exit_code,stderr_tail, and a details object.

Examples of Claude calling the workers

Cheap, fast analysis:

{ "tool": "codex_run",
  "goal": "Explain how session refresh works and where it can race.",
  "mode": "analyze", "model": "gpt-5.6-luna", "effort": "light",
  "relevant_files": ["src/auth/session.ts"] }

Hard implementation, maximum reasoning, tightly scoped:

{ "tool": "codex_run",
  "goal": "Make the uploader retry 502s with exponential backoff.",
  "mode": "implement", "model": "gpt-5.6-sol", "effort": "max",
  "allowed_paths": ["src/upload.ts", "tests/upload.test.ts"],
  "no_touch": ["src/auth"],
  "contract": "export function upload(f: File): Promise<Result>",
  "acceptance_criteria": ["Retries up to 3 times", "Existing callers unchanged"],
  "tests": ["npm test -- upload"] }

Two Codex workers on disjoint scopes — these run concurrently:

{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-sol",
  "effort": "high", "allowed_paths": ["src/api"], "goal": "..." }
{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-luna",
  "effort": "medium", "allowed_paths": ["src/ui"], "goal": "..." }

Antigravity for cheap mechanical work:

{ "tool": "antigravity_run", "goal": "Summarise every exported symbol in src/lib.",
  "mode": "analyze", "model": "Gemini Flash 3.7", "effort": "light" }

{ "tool": "antigravity_run", "goal": "Build the settings page from design.png.",
  "mode": "implement", "model": "Gemini Flash 3.7", "effort": "high",
  "allowed_paths": ["src/pages/settings"] }

Concurrency and file scope

• implement requires allowed_paths. Paths are normalised against theproject root; anything escaping it (.., other drives, absolute pathselsewhere) is rejected before a process starts.
• Active implement jobs hold their write scopes in memory. A new job whosescopes overlap an active one is refused with scope_conflict. Disjointscopes run in parallel — unrelated work is never serialised.
• analyze and review reserve nothing: they never block, and are neverblocked.

V1 limitation: detection, not isolation

File-scope protection detects and reports violations; it does not sandboxeach worker into its own tree. A Codex implement worker runs withworkspace-write across the project, so it can write outside itsallowed_paths — AgentBridge will list every such file in scope_violations,downgrade the status from success, and tell you plainly.

Nothing is ever reverted automatically. Reverting a file that was alreadymodified before the worker started would destroy your (or Claude's) existingwork. Detection plus honest reporting is the V1 contract; git-worktree isolationis deliberately out of scope.

Attribution is careful about pre-existing state: files that were already dirtybefore a run and are byte-identical afterwards are never blamed on the worker.Comparison uses porcelain status plus content hashing, and committed files arepicked up via a HEAD-move diff.

Security

• Processes are spawned with argument arrays and shell: false — never aninterpolated command string. Shell metacharacters in arguments stay literal.
• Windows .cmd/.ps1 launchers (which Node refuses to spawn without a shell)are resolved to their real Node entry script and run as node <script>, soshell: true is never needed.
• Prompts go to Codex over stdin; oversized Antigravity prompts are writtento a temp file and referenced by path. Neither can hit the Windows32 767-character command-line limit.
• tests is context for the worker. AgentBridge never executes it, and thereis no MCP argument anywhere that becomes a command AgentBridge runs.
• Path traversal outside the project root is rejected.
• Timeouts kill the whole process tree: taskkill /T /F on Windows, and onPOSIX a SIGTERM to the process group escalating to SIGKILL after a 3-secondgrace period. The escalation deliberately survives the direct child's exit,since that is exactly when descendants may still be running. This isbest-effort — Node exposes no Windows Job Object, so if taskkill itselfcannot start, only the direct child can be reached.
• Output buffers are bounded (8 MB per stream) and UTF-8 is decoded only afterreassembly, so multi-byte characters are never split.
• Logs record job metadata only. Never tokens, never the environment, andprompts/outputs only when AGENTBRIDGE_DEBUG=1.
• What AgentBridge does not protect you from: the worker is a real codingagent running with your permissions. In implement mode it can run repositorycommands through its own tooling. Scope your allowed_paths accordingly.

Verification

AgentBridge runs the project's own checks itself after a worker exits, outsideany sandbox, and returns the real output in verification:

"verification": [
  { "command": "npm run typecheck", "ok": true,  "exit_code": 0, "timed_out": false, "duration_ms": 4120, "output_tail": "..." },
  { "command": "npm run test",      "ok": false, "exit_code": 1, "timed_out": false, "duration_ms": 8830, "output_tail": "..." }
]

• verify_commands — run exactly these, in any mode.
• Omitted in implement mode — AgentBridge reads package.json and runs thetypecheck and test scripts if they exist. It never runs build, dev, orstart on its own initiative; ask for those explicitly.
• skip_verification: true — run nothing, and rely on the worker's account.

Commands run without a shell, so |, &&, ;, > and backticks outsidequotes are refused rather than half-executed. A failing check setserror: "verification_failed" and downgrades a success to partial, so aworker claiming green tests cannot outrank the tests themselves.

tests_or_checks_run and test_results report what AgentBridge actually ranwhenever verification happened; they fall back to the worker's own claims onlywhen it did not.

Because the commands come from the repository, a brief that names the wrongrunner cannot make AgentBridge run it: a repo whose test script isnode --import tsx --test is checked with that, whatever the brief said.

Environment variables

AGENTBRIDGE_CODEX_SANDBOX=auto uses read-only for analyze/review andworkspace-write for implement — except that on Windows a sandboxed Codexworker cannot capture a subprocess's output (spawn EPERM on piped stdio),which is what npm scripts, test runners, and bundlers all do — so it can readand edit but can never run a test runner, type checker, or build. That is a Codexlimitation with no configuration knob, so implement jobs fall back todanger-full-access once a one-shot probe confirms it, and say so inwarnings. Analyze and review keep their enforced read-only boundary. On Windows, if a run fails with the brokensandbox helper (helper_unknown_error: apply deny-read ACLs), AgentBridgeretries that job once with danger-full-access, remembers the verdict for therest of the process, and attaches a warning to every affected result saying theboundary was not enforced. Nothing else triggers that fallback, and restartingAgentBridge re-tries the real sandbox — so a fixed Codex release restores itautomatically. macOS and Linux never probe, retry, or fall back.

Logs are one JSON line per job: timestamp, job id, provider, model, effort,mode, project, duration, exit code, error category.

Troubleshooting

executable_not_found — the CLI is not on the PATH that Claude Codeexports to child processes. Confirm with codex --version / agy --version inthe same shell, or set AGENTBRIDGE_CODEX_BIN / AGENTBRIDGE_AGY_BIN.

authentication_required — your CLI session lapsed. Fix it in a terminal:codex login for Codex, or sign in again with agy. AgentBridge deliberatelyhas no way to repair this: it does not touch credentials.

requested_model_unavailable — the model list changed, or the installed CLInever offered that model. Run bridge_status (or agy models) to see what isactually offered; the error's details already carry it. AgentBridge fails here onpurpose rather than quietly running a different model. If a provider renamed amodel id, add the new id to that label's candidate list insrc/models/antigravity.ts (or to CODEX_MODELS in src/models/codex.ts),then rebuild.

output_parse_failed — the CLI changed its machine-readable output shape.Check details.stdout_head in the result, then compare againstparseCodexEvents / parseAgyOutput.

After a CLI update — re-run the tests, then the live smoke check:

SMOKE_LIVE=1 node scripts/smoke.mjs

That drives a real MCP session and runs the cheapest configuration of eachworker. Without SMOKE_LIVE=1 it only performs the handshake andbridge_status, consuming nothing.

files_changed is always empty — the project directory is not inside a gitworking tree. The warning in the result says so. Change verification needs git.

Nothing appears under /mcp — check the registered path points atdist/index.js (built, not src/), and restart Claude Code after a rebuild.

Layout

src/
  index.ts               stdio entry point
  server.ts              MCP server, tool schemas, dispatch
  config.ts              project-dir resolution, timeout clamping
  logging.ts             JSONL job log (stderr only, never stdout)
  parse.ts               worker-envelope parsing, summary capping
  types.ts
  cli/
    resolve.ts           PATH lookup + Windows shim unwrapping
    detect.ts            version probes, agy model listing, auth heuristics
    codex-catalogue.ts   zero-inference Codex model availability + effort capability
    codex-sandbox.ts     sandbox policy decision and helper-failure detection
  models/
    codex.ts             effort map, argv construction
    antigravity.ts       logical→real model resolution, argv construction
  process/
    runner.ts            shell-free spawn, bounded output, tree kill
  prompts/
    worker-prompt.ts     structured request → worker prompt
  scope/
    paths.ts             normalisation, traversal rejection, overlap
    locks.ts             in-memory write-scope registry
    git-state.ts         snapshot/diff file attribution
  tools/
    codex.ts  antigravity.ts  status.ts  common.ts
tests/                   252 tests, mocked processes, no quota used
scripts/smoke.mjs        real MCP end-to-end check