{"id":"b8929e63-f942-40d5-8317-1ec9822cf383","slug":"codex-antigravity-collaboration","kind":"mcp","name":"codex-antigravity-collaboration","summary":"Reference architecture and working case study for Codex × Antigravity agent-runtime collaboration.","owner":"a275618631","repoUrl":"https://github.com/a275618631/codex-antigravity-collaboration","license":"MIT","licenseTier":"permissive","trust":"community","stars":11,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-08-21T04:34:32.000Z","addedAt":"2026-10-14T06:09:25.686Z","logoUrl":"https://avatars.githubusercontent.com/u/103240550?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":["agent-architecture","ai-agents","antigravity","codex","multi-agent"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T07:33:18.018Z","sample":false,"url":"https://conduits.dev/tools/codex-antigravity-collaboration","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Codex × Antigravity Collaboration\n\n> A practical reference architecture for coordinating native agent runtimes without introducing another orchestration framework.\n\n[Architecture website](https://a275618631.github.io/codex-antigravity-collaboration/) · [Traditional Chinese README](README.zh-TW.md)\n\nThis repository documents a **working collaboration pattern** built around Codex and Google Antigravity, with a path toward local models, privacy-aware routing, and multi-host execution.\n\nIt is intentionally **not** a new agent framework, scheduler, message bus, or enterprise security product.\n\n> **Repository type:** documentation-first reference architecture and case study. It captures architecture patterns, operational contracts, status, and design decisions from a working private reference setup. It is **not an installable package** and does not currently ship a standalone runtime.\n\nThe central idea is simple:\n\n> **Use native agent capabilities first. Add coordination infrastructure only when the workload proves that it is needed.**\n\n## Why this exists\n\nModern agent platforms are becoming capable in different ways:\n\n- Codex provides strong coding workflows, parallel agents, worktrees, Skills, and engineering-oriented execution.\n- Antigravity provides its own parallel subagents, custom agents, browser/Google integrations, Projects, Skills, MCPs, and hooks.\n- Local models can cover private, offline, or network-restricted tasks.\n- GitHub and Drive already provide durable shared workspaces for many asynchronous workflows.\n\nThe question is therefore less “which framework should coordinate everything?” and more:\n\n> **How can existing runtimes cooperate while preserving their native strengths, limiting duplicated context, and keeping unnecessary infrastructure out of the critical path?**\n\n## Design principles\n\n1. **Native capabilities first**  \n   Do not rebuild parallel-agent or subagent features that the platforms already provide.\n\n2. **Capability-aware routing**  \n   Route work to the runtime best suited to the task instead of sending every task to every model.\n\n3. **Bounded delegation**  \n   A runtime may fan out internally, but cross-runtime delegation is hop-limited to prevent recursive agent chains.\n\n4. **Shared skills, thin adapters**  \n   Reuse portable skills where possible. Keep platform-specific behavior in small adapters rather than duplicating the core method.\n\n5. **Progressive coordination**  \n   Start with GitHub/Drive as a shared workspace. Add MCP/A2A-style explicit coordination only when needed. Add a broker only when retries, leases, heartbeats, or real-time state become actual requirements.\n\n6. **Distributed write ownership**  \n   Many agents may read, analyze, and review. Conflicting write-sets should have one active owner at a time. **Today this is a coordination policy, not a distributed-lock service:** isolation relies on Git branches/worktrees and optimistic concurrency, with PR/review/merge as the conflict-resolution gate.\n\n7. **Privacy-aware routing**  \n   Keep restricted data local. Where cloud use is appropriate, minimize and pseudonymize context before it crosses the trust boundary.\n\n8. **Roadmap is not implementation**  \n   Every capability in this repository is labeled **Implemented**, **Partial**, **Planned**, or **Exploratory**.\n\n## Reference topology\n\n```mermaid\nflowchart TB\n    H[Human / Coordinator]\n\n    subgraph A[\"Codex environment\"]\n        C[Codex runtime]\n        CP[Native parallel agents]\n        CV[Role-based workers]\n        C --> CP\n        C --> CV\n    end\n\n    subgraph B[\"Antigravity environment\"]\n        AG[Antigravity runtime]\n        AP[Native subagents]\n        AR[Custom / role agents]\n        AG --> AP\n        AG --> AR\n    end\n\n    subgraph L[\"Local environment / restricted lane\"]\n        LM[Local model runtime]\n        LT[Private or offline tasks]\n        LM --> LT\n    end\n\n    H --> C\n    H --> AG\n    H --> LM\n\n    C <-->|bounded external delegation| AG\n    C -.->|optional local delegation| LM\n    AG -.->|optional local delegation| LM\n\n    G[(GitHub)]\n    D[(Drive / shared documents)]\n\n    C --- G\n    AG --- G\n    C --- D\n    AG --- D\n```\n\nA key distinction is that **a host or platform is not a single agent**. Each runtime can already contain its own coordinator, role-based workers, and parallel agents. Cross-platform coordination therefore happens **between agent runtimes**, not merely between individual prompts.\n\nSee [Architecture](docs/ARCHITECTURE.md).\n\n## Current status\n\n| Capability | Status | Notes |\n|---|---|---|\n| Codex ↔ Antigravity bridge / smoke path | **Implemented** | Core bridge path has passed a read-only smoke test. |\n| Task / Result collaboration packet | **Implemented** | Used as the common request/result contract. |\n| Bounded external delegation | **Implemented** | One-hop guard is part of the current collaboration protocol. |\n| Read-only bounded debate | **Implemented** | Maximum two rounds in the current reference workflow. |\n| Platform-native parallel agents | **Implemented / Native** | Delegated to Codex and Antigravity rather than reimplemented here. |\n| Shared skills model | **Partial** | Direction is implemented, but canonical-source convergence is not yet fully verified. |\n| Local-model bridge | **Experimental** | Existing local-model communication has been exercised separately; it is not yet the trust-routing layer described below. |\n| Privacy-aware routing | **Planned** | Architecture defined; production-grade privacy gateway is not claimed. |\n| Multi-host coordination | **Exploratory** | Shared-workspace approach is the starting point; protocol/broker evolution remains future work. |\n| Broker, leases, heartbeat, retry | **Exploratory** | Explicitly deferred until scale requires them. |\n\nThe status table is intentionally conservative. See [Status and Roadmap](docs/STATUS_AND_ROADMAP.md).\n\n## Collaboration model\n\nThe architecture distinguishes four forms of collaboration:\n\n1. **Intra-runtime parallelism** — platform-native parallel agents or subagents.\n2. **Vertical delegation** — coordinator → specialized worker roles inside one runtime.\n3. **Inter-runtime delegation** — Codex ↔ Antigravity, or another external runtime.\n4. **Inter-host delegation** — the same pattern extended across machines.\n\nInternal fan-out can be rich. External delegation is deliberately narrower.\n\n```text\nRuntime A\n├─ internal agent\n├─ internal agent\n└─ external delegation ──> Runtime B\n                           ├─ internal agent\n                           └─ internal agent\n\nExternal delegation does not recursively bounce across runtimes without an explicit new decision.\n```\n\n## Privacy-aware extension\n\nThe proposed trust model uses four data classes:\n\n| Class | Default route |\n|---|---|\n| **Public** | Cloud direct |\n| **Internal** | Local redaction/minimization → cloud if policy allows |\n| **Sensitive** | Reversible pseudonymization → cloud if policy allows → local restore |\n| **Restricted** | Local only |\n\nThis is **risk reduction, not risk elimination**. Pseudonymization is not encryption-in-use, and remaining context may still support semantic re-identification.\n\nMature projects such as [Presidio](https://github.com/data-privacy-stack/presidio) can supply sensitive-data detection primitives. A local model can optionally supplement deterministic rules by identifying organization-specific concepts that conventional PII detectors may not recognize. The local model should **not** be the sole policy authority.\n\nSee [Privacy and Trust](docs/PRIVACY_AND_TRUST.md).\n\n## Coordination should evolve only when necessary\n\n```text\nStage 1 — Shared workspace\nGitHub / Drive\n        ↓\nStage 2 — Explicit coordination\nMCP bridge / A2A-style agent communication\n        ↓\nStage 3 — Brokered coordination\nqueue / state / lease / heartbeat / retry / timeout\n```\n\nThe default is **Stage 1** for low-frequency asynchronous work. Stage 2 and Stage 3 are upgrades, not prerequisites.\n\n## What this project deliberately does not build\n\n- another multi-agent runtime;\n- a universal scheduler;\n- a custom distributed database;\n- a vector database just for coordination;\n- a new gateway when an existing bridge is sufficient;\n- unrestricted recursive agent delegation;\n- a claim of “fully autonomous” operation;\n- a claim that pseudonymization makes cloud processing safe or compliant by itself.\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md)\n- [Design Principles](docs/DESIGN_PRINCIPLES.md)\n- [Privacy and Trust](docs/PRIVACY_AND_TRUST.md)\n- [Status and Roadmap](docs/STATUS_AND_ROADMAP.md)\n- [References](docs/REFERENCES.md)\n\nTraditional Chinese overview: [README.zh-TW.md](README.zh-TW.md)\n\n## Project maturity\n\nThis repository is best read as a **reference architecture plus a working two-runtime case study**.\n\nThe currently implemented core is Codex + Antigravity collaboration. Local privacy routing and distributed multi-host coordination are documented as future directions because the architecture should remain understandable before it becomes distributed.\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n"}