Codex Antigravity Subagent MCP

This local stdio MCP server lets Codex delegate tasks to Google Antigravity CLI (agy).

• Default model: gemini-3.8-flash-high

• User prompts and leading system slash commands are retained, with absolute workspace context appended for delegation.

• /teamwork-preview <task> is supported; include a concrete task after the command.

• Long-running calls can be started in the background and polled by job ID.

• Conversation IDs can be passed back to continue an earlier Gemini session.

• Failed runs include structured error_details and the exact per-job diagnostic_log path. Model backend codes such as FAILED_PRECONDITION (400) are surfaced instead of AGY's generic termination message.

• By default, permission mode is set to auto-approve (injecting --dangerously-skip-permissions) to prevent headless print mode from soft-denying tool confirmation. This default can be configured via the ANTIGRAVITY_PERMISSION_MODE environment variable.

• If explicit confirmation is required, caller can pass permission_mode: "default" or "sandbox". When a tool needs unprompted confirmation in default mode, such empty SUCCESS responses are normalized to TOOL_CONFIRMATION_DENIED.

The bridge never invokes --disable-slash-commands. It uses AGY's required --print=<prompt> form so later CLI options are not accidentally consumed as the prompt. Per-job AGY logs are stored under logs/ so a bridge response can be matched to the original backend error without scanning unrelated global CLI logs.

Version 1.3.0 changes:

• Standalone Real-time Visual Monitor Dashboard: Built an elegant, dark cyberpunk-themed Web dashboard (src/web/index.html) using zero external dependencies (pure native Node.js http and HTML5/CSS3/ES6).

  • God's-eye View Grid: Renders individual subagent cards for all Teamwork roles (Orchestrator, Workers, Auditor) with live pulse status indicators, step counters, and highlighted active tool tags ([run_command], [write_to_file]).

  • Micro-Activity Timeline: Clicking any agent card seamlessly reveals its deep, step-by-step activity stream (recent_activities), demystifying internal execution.

  • Zero-Polling SSE Push: Uses Server-Sent Events (/api/stream) for sub-second, live real-time state streaming directly to browsers.

  • One-Click Controls & Log Streaming: Supports remote one-click cancellation for running/queued tasks and live diagnostic log tails.

• New MCP Tool open_dashboard: Codex can directly trigger open_dashboard to automatically pop up the monitor dashboard in the user's default browser (http://localhost:3721).

• Standalone CLI & Concurrent Integration: Launchable independently via npm run dashboard (node src/dashboard.mjs [--open]) or concurrently with MCP when ANTIGRAVITY_ENABLE_DASHBOARD=1.

Version 1.2.2 changes:

• Complete Negation & In-progress Defense: Hardened evaluateSubagentStatus to eliminate completion false-positives. Replaced isolated keyword matching (e.g. standalone handoff.md or VICTORY) with strict affirmation patterns. Messages containing negative or in-progress modifiers (e.g. "尚未生成，继续修复", "No VICTORY yet; still working") are categorically barred from being marked completed.

• Comprehensive Multi-tool Step Scanning: Inspects the entirety of lastEntry.tool_calls rather than solely the first element. Any step containing active filesystem/terminal tools alongside send_message strictly remains running.

• Queued Task Cancellation: cancel_gemini_task now supports immediately canceling queued tasks awaiting directory concurrency locks, transitioning their state directly to cancelled and short-circuiting execution when the lock becomes free.

• Restart Convergence for Queued Jobs: restorePersistedJobs now converges orphaned queued jobs into interrupted upon server reboot, completely preventing zombie waiting states.

• Handshake Version Parity: Synchronized server handshake version to 1.2.2.

Version 1.2.1 changes:

• Strict Evidence-Based Lifecycle Evaluation: Completely eliminated heuristic step count thresholds (e.g. step >= 30) and naive tool-name assumptions. Agents performing active tools (commands, edits) or asking questions remain strictly running; only explicit completion evidence (finished handoffs/verdicts or parent kills) marks completed. Inconclusive evidence defaults to running/unknown.

• Working MCP Progress Notification Stream: Fixed progress notification delivery by resolving progressToken from both _meta and params._meta, and invoking SDK-standard ctx.mcpReq.notify rather than unreachable methods.

• Accurate Action Tracking & Stale Text Invalidation: Tool activities now prioritize detailed parameters from tc.args (e.g. toolSummary, command lines, filenames) over bare tool names. Consecutive tool executions reliably invalidate and overwrite prior text reflections in current_action.

• Deep Hierarchy Traversal (Depth >= 8): Expanded subagent cascade recursion depth to 8 with generalized conversation ID resolution and cycle protection, preventing truncation on 5+ tier agent chains.

• Atomic Persistence & Consistent Restart State: Jobs are written atomically via temporary files (.tmp -> rename) with automated quarantine for corrupted JSON records. Interrupted tasks post-restart consistently report state: interrupted, isError: true, and progress.phase: interrupted.

• Directory Concurrency Lock: Added asynchronous per-workspace serialization lock to prevent conflicting concurrent Antigravity executions in the same working directory.

• Handshake Version Parity: Synchronized server handshake version to 1.2.1.

Version 1.2.0 changes:

• Deep Cascade Subagent Inspection (God's-eye View): Recursively penetrates and parses independent subagent conversation transcripts for all spawned Workers (e.g. Worker A, Worker B, Victory Auditor). Exposes fine-grained execution steps (step), live micro-actions (current_action), active tools (last_tool), lifecycle statuses, and individual activity trails directly in the subagents list.

• Robust Subagent Parsing & Full-transcript Affinity: Automatically prefers un-truncated transcript_full.jsonl and adds tolerant parser fallbacks for models producing raw unescaped newlines within JSON string arguments.

Version 1.1.0 changes:

• Real-time Progress & Activity Tracking: get_gemini_task poll responses now include a structured progress object detailing the current step number, active tool call, action summary, spawned subagents list, and recent activity stream, eliminating the "blind running" limitation.

• MCP Progress Notification Stream: delegate_to_gemini pushes live progress notifications every 2 seconds when caller provides a progressToken.

• Lightweight Job Persistence: Jobs are continuously snapshot-persisted under data/jobs/. Server restarts automatically restore historical task records and mark uncompleted sessions as interrupted.

• Multi-path AGY Detection: Enhances Windows binary detection across common installation roots before falling back to system PATH.

Version 1.0.3 reliability changes:

• Final CLI success takes precedence over recovered model errors, which appear as diagnostic_warning. Full logs are searched before display truncation.

• Diagnostic output redacts Bearer/Basic credentials and quoted token fields. Original AGY log files remain local raw diagnostics; do not share them unredacted.

• Automatic retry is limited to temporary OS spawn errors (EAGAIN, EBUSY) before any child PID exists. Missing or zero token usage is not proof that no tools ran. Model errors, including region errors, are returned without replay.

• Cancellation, timeout and output limits terminate the spawned process tree on Windows using its PID. Failure to terminate is reported explicitly. Synchronous MCP request cancellation, disconnects and normal termination signals also request task cleanup. This does not cancel independently hosted remote agents or survive a hard crash.

• Each attempt has a unique log file. Timeout/cancellation status overrides partial CLI output; an abnormal process exit cannot report success.

• The task cwd is explicitly added with --add-dir and appended as absolute delegation context (keeping the leading slash command intact), so agents can resolve project inputs instead of substituting the default scratch workspace. This supplies workspace context, not a filesystem sandbox.

Offline validation: npm run test:diagnostics and npm run test:lifecycle. Live validation (uses Gemini quota, writes only its temporary fixture workspace): npm run test:live. The live report checks exact file contents; file output alone does not prove that Teamwork launched multiple agents.