agy_subagents
Integrates with Google Antigravity CLI (agy) as a subagent execution backend, enabling Codex to spawn, wait on, continue, inspect, and close agy agents with model routing, worktree isolation, concurrency queues, and rate-limit handling.
Integrates with OpenAI Codex as an MCP server that adds a primary/overflow agy subagent pool, letting Codex delegate parallel research, triage, and coding tasks with native-like subagent lifecycle tools and routing policy.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agy_subagents spawn a subagent to research best practices for Python async"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
codex-agy-subagents
Turn Google Antigravity CLI (agy) into a native-feeling primary/overflow subagent pool for OpenAI Codex — zero third-party dependencies.
English | 简体中文 | Architecture
Why This Project Exists (The Pain Points)
If you do most of your daily engineering inside OpenAI Codex, migrating away is painful — your conversation history, project memories, skills, and workflow live in Codex. Yet relying exclusively on Codex's built-in subagents quickly hits four real-world bottlenecks:
Hard 6-subagent concurrency ceiling: Codex limits concurrent native subagent threads (default 6), forcing large multi-module tasks to serialize.
Slow & expensive native loops: Over-defensive native execution and high per-token cost make heavy parallel research, log triage, and multi-file edits noticeably slow and pricey.
External MCP tools get silently ignored by Codex: Modern Codex builds enable
tool_search_always_defer_mcp_tools = true, hiding external MCP tool schemas from initial context. Even after registering a normal MCP server, Codex'sultramode keeps reflexively calling nativespawn_agentand ignores external agents unless you manually remind it every turn.Naive CLI bridges feel nothing like native subagents (and risk rate-limit bans): Synchronous wrappers block the main loop and hit 60s MCP timeouts; lack multi-turn follow-up (
send_input); leave orphan processes/worktrees on Windows; or blast dozens of concurrent requests into a single account at once, triggering 429 storms.
Related MCP server: antigravity-subagent-sidecar
What codex-agy-subagents Does
Keep Codex as your primary brain (retaining all your conversations, memories, planning, and final code review) while transparently delegating parallel subagent work to your locally authenticated Antigravity CLI (agy) — with an experience virtually identical to Codex's own built-in subagents:
1:1 Native Subagent Lifecycle Symmetry (6 Focused Tools):
Codex Native
agy_subagentsMCP ToolCapability
spawn_agentmcp__agy_subagents__agy_spawn_agentNon-blocking async spawn; immediately returns
agent_idwait/wait_agentmcp__agy_subagents__agy_wait_agentEvent-driven batch wait on
agent_ids(wait_for="any"or"all")send_inputmcp__agy_subagents__agy_send_inputTrue multi-turn continuation via
agy --conversation <id>+ live mailbox queueingthread status
mcp__agy_subagents__agy_statusNon-blocking pool, queue, live step progress, and cooldown inspection
close_agentmcp__agy_subagents__agy_close_agentKills full OS process tree (Windows
taskkill /T /F/ POSIX process group) & cleans Git worktree—
mcp__agy_subagents__agy_healthZero-quota readiness check (binary, proxy, available
agy models, pool status)Automatic Invocation Without Manual Reminders:
Injects an AGY-FIRST (or AGY-OVERFLOW) routing policy into Codex's top-level
developer_instructions(which lands as the very firstrole: "developer"message in both Codex Desktop and Codex CLI — zero hook-trust popups required), reinforced byAGENTS.md, a bundledagy-subagentsSkill, and optional Codex lifecycle hooks (UserPromptSubmit/PreToolUse/SubagentStart/SubagentStop).Automatic native fallback: if
agy_subagentsenters a 429/auth cooldown, Codex seamlessly falls back to nativespawn_agent.
Smart Tiered Model Routing:
Light tasks (
tier="light"/explorer/researcher) →gemini-4-hydrogen-xhigh(fast, read-only sandboxed).Heavy tasks (
tier="heavy"/worker/reviewer) →gemini-4-neon-xhigh(deep implementation, debugging, review).Fully configurable via environment variables or per-call overrides.
Safe Parallel Writes with Git Worktree Isolation & Scope Auditing:
Read-only agents share
cwdwith--sandbox(zero disk copy overhead).Concurrent write agents run in isolated Git worktrees (
agy-sub/<agent_id>) outside the repo, audit every changed file againstowned_paths(scope_status/scope_violations), returndiff_stat, and never auto-merge.
Account-Safe Concurrency & Rate-Limit Guardrails:
Strictly executes the official local
agybinary — never reads, stores, intercepts, or forwards OAuth tokens.Queue vs. concurrency decoupling: Codex can fan out up to 32 queued subagents in one burst while active
agyprocesses stay smoothly throttled (default 5 concurrent).Staggered launch jitter (
1.5s) prevents sudden QPS spikes.Exponential-backoff circuit breaker pauses new launches on
429/ quota / auth errors instead of hammering retries.No nested recursion: explicitly blocks
agyworkers from spawning nested subagents (preventing both concurrency explosions andagy -pstdout result loss).
Zero Dependencies & First-Class Windows Support:
Pure Python 3.10+ standard library — boots in
<100ms, zeropippackages needed,CREATE_NO_WINDOW(no flashing terminal popups), closedstdin(preventsagy -phangs), disk-persisted run records (meta.json,output.txt,events.jsonl).
Prerequisites
Python 3.10+
Git (for optional
isolation="worktree"concurrent writes)OpenAI Codex Desktop or Codex CLI with MCP support
Google Antigravity CLI (
agyv1.1.15+, tested on v1.5.9) installed and logged in locally:agy --version agy models
Quick Start
Option 1: One-Command Installer (Recommended)
git clone https://github.com/Sereneoned/codex-agy-subagents.git
cd codex-agy-subagents
# Preview changes first (makes no edits)
python scripts/install_codex.py --dry-run
# Install in AGY-FIRST mode (prefer agy, keep Codex native subagents as fallback)
python scripts/install_codex.py --mode agy-first
# Optional: pass a local proxy and custom models/concurrency
python scripts/install_codex.py \
--mode agy-first \
--light-model gemini-4-hydrogen-xhigh \
--heavy-model gemini-4-neon-xhigh \
--max-concurrent 5 \
--proxy-url http://127.0.0.1:7890Prefer overflow-only mode (fill Codex's 6 native slots first, overflow #7+ to
agy)? Pass--mode overflow.
Want optional Codex CLI lifecycle hooks (~/.codex/hooks.json) too? Add--with-hooks.
Then restart Codex Desktop / CLI and start a new conversation.
Option 2: Manual Setup
Copy the templates from
examples/config.toml.exampleinto~/.codex/config.toml(be sure to keeptool_timeout_sec = 900soagy_wait_agentnever trips Codex's 60s default timeout).Append
examples/AGENTS.md.exampleto~/.codex/AGENTS.md.Copy
skills/agy-subagents/SKILL.mdto~/.codex/skills/agy-subagents/SKILL.md.Restart Codex and verify with
codex mcp get agy_subagents.
Verify It Works
In a fresh Codex chat, try a multi-part task (or run a quick check):
"Check
agy_health, then spawn two parallelagysubagents — one light and one heavy — to inspect two different modules and summarize both."
Active run logs and transcripts are persisted under:
Windows:
%LOCALAPPDATA%\codex-agy-subagents\runs\macOS/Linux:
~/.local/share/codex-agy-subagents/runs/
Configuration Reference
All settings live under [mcp_servers.agy_subagents.env] in ~/.codex/config.toml:
Env Variable | Default | Description |
| auto-detected ( | Explicit path to the |
|
| Default model for |
|
| Default model for |
|
| Max live concurrent |
|
| Max queued + active subagents accepted per burst ( |
|
| Minimum delay between consecutive launches (seconds) |
|
| Base exponential-backoff pause on |
|
| Max circuit-breaker cooldown duration |
|
| Default per-turn timeout passed to |
|
| Max chars returned inline (full output always saved to |
| (inherits | Optional proxy URL forwarded to |
|
| Directory for persisted run state, transcripts, and worktrees |
Safety & Account Hygiene Notes
This project only calls the official
agyCLI through documented headless flags (-p,--output-format stream-json,--conversation,--model,--sandbox). It does not reverse-engineer private APIs, scrape or forward OAuth tokens, or rotate credentials.If you manage multiple Antigravity accounts with external tools (such as Cockpit Tools), avoid switching accounts mid-flight while
agysubagents are actively running, as overwriting the shared CLI token file can interrupt in-progress turns or--conversationcontinuations.Keep
AGY_MAX_CONCURRENTmoderate (4–6) and let the queue (32) + stagger (1.5s) smooth out large parallel bursts.
Development & Tests
python -m unittest discover -s tests -vTests run completely offline using a deterministic mock runner plus real local Git worktrees, MCP JSON-RPC protocol checks, circuit-breaker verification, and Codex hook tests.
See docs/architecture.md for full technical internals.
License
Available Tools
6 toolsagy_close_agentAIdempotent
Cancel/close an Antigravity subagent (mirrors native Codex close_agent). Terminates any running process tree and optionally removes its isolated Git worktree.
Inputs: agent_id (required), delete_branch, cleanup_worktree.
agy_healthARead-only
Check Antigravity CLI readiness, proxy configuration, available model IDs, and current concurrency/cooldown pool status without consuming model quota.
Inputs: refresh_models.
agy_send_inputA
Send follow-up instructions or review feedback to an existing Antigravity subagent (mirrors native Codex send_input). Preserves full conversation context via --conversation; if the agent is still running, queues the message in its mailbox for the next turn.
Inputs: message (required), agent_id (required).
agy_spawn_agentA
PRIMARY asynchronous subagent launcher powered by Antigravity (agy). Non-blocking: immediately returns agent_id. Prefer this FIRST over native Codex spawn_agent for parallel fan-out, exploration, research, code review, and independent coding tracks (keep native spawn_agent as fallback). Default tier routing: tier='light' -> gemini-4-hydrogen-xhigh (exploration, codebase search, log/doc reading); tier='heavy' -> gemini-4-neon-xhigh (implementation, debugging, code review). Always fan out multiple agy_spawn_agent calls in one turn, then collect via agy_wait_agent.
Inputs: cwd (required), prompt (required), role, tier, +8 more.
agy_statusARead-only
Non-blocking status inspection for one agent or the entire Antigravity subagent pool (active count, queue length, live step progress, circuit-breaker cooldown status).
Inputs: agent_id, include_output.
agy_wait_agentARead-only
Wait for one or more Antigravity subagents to finish (mirrors native Codex wait). Pass wait_for='any' to stream results as each agent finishes, or 'all' to wait for the full batch. Returns completed results, conversation_id, changed_files, scope_violations, branch, and still_running.
Inputs: agent_ids (required), wait_for, timeout_sec.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct phase of the subagent lifecycle: spawn, wait, send_input, status, close, health. Descriptions explicitly delineate blocking vs non-blocking and clarify that agy_status is read-only inspection while agy_wait_agent blocks for results, so there is no realistic misselection.
All tools share a uniform agy_ snake_case prefix and readable names. The only inconsistency is style: most use verbs (spawn, wait, send, close) while agy_status and agy_health are noun-style inspection tools, a minor but noticeable deviation.
Six tools cover the complete subagent lifecycle without redundancy, matching the mirrored native Codex primitives almost one-to-one. Nothing feels padded or missing at this scope.
Spawn, wait, follow-up input, status, close, and health give full lifecycle coverage including worktree cleanup and pool diagnostics. Minor gaps: no explicit enumeration of individual agent IDs or metadata beyond the pool aggregate, and no dedicated result-retrieval tool once an agent has already been collected.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal MCP server that exposes delegation tools for Codex, Claude, and Antigravity CLI, enabling an orchestrator agent to assign tasks to these sub-agents via non-interactive CLI commands.3MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that uses Google Antigravity subagents as parallel workers for coding agents, enabling efficient task delegation with compact results.MIT
- AlicenseNot gradedqualityCmaintenanceA local-first MCP orchestration server that uses Codex as lead planner and Antigravity as host to delegate and review bounded tasks with Git integration and persistent SQLite state.Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that lets OpenAI Codex delegate tasks to Google Gemini agents as isolated background workers, with Git worktree isolation, loop detection, and security boundary enforcement.72MIT