agent-bridges

# agent-bridges A fixed-role delegation pipeline that pairs **Claude Code** with two delegation bridges, each with fixed jobs: | Role | Bridge | |---|---| | Document Analyzer, Coder/Executor, Release-Changelog Writer | **Antigravity** (`agy-mcp` MCP server — async jobs, not blocking calls) | | QA Engineer, Security Engineer | **Codex** (`codex-companion.mjs task` called directly via `Bash`, from the separately-installed [`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc) plugin — not its `codex:codex-rescue` subagent; see `docs/ARCHITECTURE.md`) | | Planner and Code Reviewer, final say on every bridge output | **Claude Code** | Claude Code is the only agent with tool access, repo/session state, and write permission — it plans, reviews first, and owns verification (a delegated finding is never the sole basis for an edit until checked; see "Parallelism, failures, and verification" in `templates/CLAUDE.md`). ## Why Routing everything through one model is wasteful when another provider fits a role better. Antigravity ingests specs, writes the code, then drafts release notes; Codex QA always tests the diff; Codex Security always reviews it for exploits; Claude Code always plans, reviews before either Codex role sees a diff, and has final say — including over the docs Antigravity drafts. Delegating also keeps Claude Code's own context free of work — reading a large file, diffing a big repo, running QA/ security — where only the *answer* is needed, not the investigation. For the full design rationale (topology, session continuity, memory sharing across harnesses, learning-curator internals), see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## Install No clone needed — Claude Code pulls this repo itself. Run these as two separate commands, not as one pasted block — pasting both lines at once can merge them into a single command and break the owner/repo argument: ``` /plugin marketplace add sanoval/agent-bridges ``` ``` /plugin install agent-bridges@agent-bridges ``` This registers the `antigravity` MCP server, the `delegation-pipeline` and `learning-curator` skills, and the Gate `PreToolUse` hook — and keeps them current (`/plugin install agent-bridges@agent-bridges --update` to force a check). **Upgrading from a pre-0.2.0 install (this plugin used to run its own Codex MCP server)?** Updating alone won't clear the old `codex-qa`/ `codex-security` entries cached in `~/.claude.json`, your stale `~/.agents/skills/` symlinks, or your own already-copied `CLAUDE.md` — see `docs/SETUP.md` step 0c. **Upgrading from a pre-0.3.0 install (the Antigravity bridge used to be `agy-bridge`, a blocking call with a timeout ceiling)?** You need the `agy-mcp` binary installed separately (it's not bundled — see `docs/SETUP.md` step 1), and updating the plugin alone may not be enough to pick up the new `antigravity` server command: Claude Code caches each project's *resolved* MCP server per name in `~/.claude.json` and doesn't always re-resolve it just because `.mcp.json` changed. If `claude mcp list` still shows `antigravity` running `npx ... agy-bridge` after updating, see `docs/MIGRATION.md` for the fix and the full behavior change (`agy_run` returns a `job_id` immediately instead of blocking — delegation calls no longer time out, they wake you when done). **Three-bridge mode (Codex QA/Security) is a separate install**, not part of this plugin: it's OpenAI's own [`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc) plugin — see `docs/SETUP.md` step 2. Not on a Codex subscription, or haven't installed that plugin? You're in two-bridge mode by default, harmless, see "Which mode do I need?" below. **Scope this to the projects that actually run the pipeline.** The Gate hook fires on every `Edit`/`Write`/`NotebookEdit` in any project where the plugin is enabled — enable it per-project (project `.claude/settings.json` `enabledPlugins`) rather than at user scope, or you'll get Gate prompts in unrelated repos. See [Configure team marketplaces](https://code.claude.com/docs/en/discover-plugins#configure-team-marketplaces). Installing the plugin covers Claude Code. Antigravity/Codex CLIs, model pins, and copying `CLAUDE.md`/`AGENTS.md` into your project are separate, still-manual steps — see **[docs/SETUP.md](docs/SETUP.md)** for the full walkthrough and **"Verifying it works"** in that doc once you're done. ## Usage Once setup is verified, see **[docs/USAGE.md](docs/USAGE.md)** for what a day-to-day session looks like: how to start a unit of work, what the Gate hook will ask you to approve, what happens automatically (checkpointing, learning), and a narrated end-to-end example. ## Which mode do I need? - **Have a Codex subscription too?** Install `openai/codex-plugin-cc` (`docs/SETUP.md` step 2) and use `templates/CLAUDE.md` as-is (three-bridge mode). QA and Security each get their own model pin, passed per call. - **Only Claude Code + Antigravity?** Copy `templates/CLAUDE.md` and append `templates/CLAUDE-two-bridge-overlay.md` (two-bridge mode). QA and Security fold into two separately-framed, separately-pinned Antigravity `agy_run` calls instead of dedicated bridges — the overlay explains what's still weaker than three-bridge mode (shared account/CLI infrastructure with the Coder role) even with independent model pins, and why your own Review step has to work harder. ## Acknowledgements This is an original configuration/template repository — not a fork, no source code from its MCP dependencies included. The Antigravity integration uses [agy-mcp](https://github.com/tphakala/agy-mcp) by tphakala as an external MCP dependency (registered locally as `antigravity`), distributed under the MIT License. Versions before 0.3.0 used [agy-bridge](https://github.com/sshahzaiib/agy-bridge) by Shahzaib Akram instead (same MIT license) — see `docs/MIGRATION.md` for why this project moved off it and how to roll back if needed. The Codex QA/Security integration (three-bridge mode) uses OpenAI's own [`codex-plugin-cc`](https://github.com/openai/codex-plugin-cc) plugin as an external dependency — installed separately, not bundled with this plugin. ## License Copyright (c) 2026 Sanovalaw. Licensed under the [MIT License](LICENSE).