antigravity-workers
This server exposes a local MCP interface that lets Codex delegate bounded Antigravity worker jobs (analysis, review, isolated edits, media tasks, and multi-agent teams) while Codex keeps control over review, validation, and integration.
Run diagnostics:
doctor,list_models,get_account.Start asynchronous code workers:
start_analysis,start_review,start_editin isolated Git worktrees.Manage runs:
get_run,list_runs,continue_run,cancel_run,apply_run(apply reviewed patches only).Launch multi-agent teams:
start_team,get_team,list_teams,team_dashboard,message_agent,cancel_team,resume_team.Perform multimodal media analysis and image generation/editing:
start_media_analysis,start_image_generation,start_image_edit,get_media_run,list_artifacts.Inspect generated artifacts and media run results through the persistent ledger.
Provides integration with Google Antigravity workers to delegate code analysis, review, isolated edits, multimodal research, and native image generation tasks, returning reports and patches for inspection.
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., "@antigravity-workers Review the parser in this repo and report issues with file references."
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.
Antigravity Workers
Supervised Google Antigravity workers for Codex, exposed through a local Model Context Protocol (MCP) server.
Delegate bounded code analysis, review, isolated edits, multimodal research, and native image generation. Codex owns requirements, review, validation, and integration. Workers return reports and patches for inspection.
Features
Individual analysis, review, and edit workers with queued execution and retries.
Read-only teams with distinct roles, reviewer and coordinator stages, correction rounds, messaging, and live dashboards.
Isolated Git worktrees for edit jobs, with patch inspection before
apply_run.Explicitly scoped media inputs copied into per-run workspaces; native image generation and editing.
Persistent run and team ledgers, cancellation, continuation, and recovery after interruption.
One scheduler per state directory, shared across multiple MCP clients.
Optional per-worker live Command Prompt windows on Windows.
No npm runtime dependencies.
Related MCP server: agy-mcp
Requirements
Node.js 20 or newer and Git on
PATH.A separately installed and authenticated Antigravity CLI (
agy) for real worker jobs. CLI access, model availability, provider terms, and usage limits are separate from this project.Codex or another MCP client supporting local standard-input/output servers.
Windows and Linux are the supported targets for this release. macOS is not currently supported: an interrupted scheduler can leave a stale local socket that prevents restart.
The test suites use a mock CLI and require no provider account. This repository contains the integration; it does not redistribute the Antigravity CLI or grant access to Google services.
Quick start
git clone https://github.com/McDuckVc/antigravity-workers.git
cd antigravity-workers
npm testRegister the MCP server using your checkout's absolute path:
codex mcp add antigravity-workers -- node "/absolute/path/antigravity-workers/server/index.mjs"If agy is installed somewhere other than its default location:
codex mcp add antigravity-workers --env ANTIGRAVITY_AGY_PATH="/absolute/path/to/agy" -- node "/absolute/path/antigravity-workers/server/index.mjs"On Windows, quote paths containing spaces and use your actual executable paths. The default CLI location on Windows is %LOCALAPPDATA%/agy/bin/agy.exe; on other platforms the server resolves agy from PATH.
Restart your Codex session after registering the server. Ask it to run doctor and list_models, then give a bounded assignment, for example:
Use Antigravity Workers to review the parser in this repository. Report issues with file references. Do not modify files.
Live worker Command Prompt windows (Windows)
Set ANTIGRAVITY_WORKER_TERMINALS=on in the MCP server environment to open one read-only Command Prompt window for each running worker, including team members, coordinators, continuations, and retry attempts. Each viewer renders Antigravity's structured response deltas, tool and subagent activity, and incoming coordinator or peer messages as they arrive. Completed windows use a black-and-green color 0A theme with a framed agent-information header, the response text, and a separate run-metadata frame containing status, token usage, duration, and identifiers. Team windows continue to receive relevant messages after their worker finishes, and the scheduler continues to parse and persist the original streams normally.
Closing a viewer window does not cancel its worker. Use cancel_run or cancel_team for cancellation. After the response and metadata are displayed, completed viewers start a two-minute auto-close timer. Press any key during that timer to cancel it and keep the window open until you close it; relevant team messages continue streaming while it remains open. The feature is Windows-only and opt-in so headless sessions, CI, and automations do not open desktop windows.
For a direct MCP registration, add the environment variable when registering the server:
codex mcp add antigravity-workers --env ANTIGRAVITY_WORKER_TERMINALS=on -- node "C:\absolute\path\antigravity-workers\server\index.mjs"Run doctor after restarting Codex and check worker_terminals.enabled to confirm the setting reached the scheduler owner.
For the orchestration guidance, copy skills/antigravity-orchestrator to your personal Codex skills directory (~/.codex/skills/) or use this repository as a plugin through your configured marketplace. Direct MCP registration installs the tools; adding the skill supplies the workflow instructions.
Plugin packaging
The repository includes a portable plugin.json and mcp.json, plus .codex-plugin/plugin.json and .mcp.json compatibility files. The portable MCP configuration uses ${PLUGIN_ROOT} to resolve the installed server location. A marketplace host must support local stdio servers. See the official plugin packaging documentation for marketplace setup. Publication on GitHub does not install the plugin into the official directory.
Tools
Purpose | Tools |
Diagnostics |
|
Code workers |
|
Run lifecycle |
|
Teams |
|
Media |
|
Read the tool schemas exposed by the server for complete inputs. Prefer model_policy (quality, balanced, or fast) and check list_models for account availability.
Configuration
Set these variables in the MCP client's server environment:
Variable | Default / purpose |
| Override the CLI executable path. |
| Windows: |
|
|
| Server default 32; bundled plugin configuration 64. |
|
|
|
|
|
|
|
|
| 250 MB per input file. |
| 1024 MB across a request's inputs. |
| 12 MB for inline artifacts. |
|
|
Model IDs are configurable defaults, not guarantees of provider availability. Matching model suffixes determine compatible effort.
Data and execution boundaries
This is a local orchestration tool, not a security sandbox. Workers run with the permissions enforced by Antigravity and the host. Give them only authorized projects and inputs. Code and media jobs may send selected content to the configured provider.
The state directory can contain prompts, responses, logs, worktrees, artifacts, and local runtime authentication material. Keep it outside public repositories. get_account returns the active account identifier only when explicitly requested; it does not expose OAuth tokens.
Edit workers require a Git repository. A CLI success result is accepted only when patch capture also produces code changes; denied actions or an empty patch are reported as a failed run and are not automatically retried. Inspect the patch and relevant tests before calling apply_run; read-only teams never apply edits. See SECURITY.md.
Development and validation
npm testThe mock suites exercise the MCP protocol, queuing and retries, worker lifecycles, teams, scoped media, image artifacts, patch handling, shared runtime ownership, and restart behavior. CI runs these tests on Windows and Linux with Node.js 22 and 24.
The optional npm run test:live invokes your authenticated Antigravity CLI and consumes provider usage. It is excluded from CI. Additional media/image smoke checks are opt-in through ANTIGRAVITY_MEDIA_SMOKE_FILE and ANTIGRAVITY_IMAGE_SMOKE=1.
Contributing and license
See CONTRIBUTING.md. Licensed under MIT.
Independent community project; not affiliated with or endorsed by Google or OpenAI. Product names belong to their respective owners.
Available Tools
23 toolsapply_runA
Apply a successful edit worker's reviewed patch to its original Git checkout. Run only after Codex has inspected the patch and validation evidence.
Inputs: run_id (required).
cancel_runADestructive
Request cancellation of an active Antigravity worker process.
Inputs: run_id (required).
cancel_teamADestructive
Cancel all queued or running workers in a multi-agent team.
Inputs: team_id (required).
continue_runB
Continue a completed Antigravity conversation as a new asynchronous run in the same workspace or isolated worktree.
Inputs: prompt (required), run_id (required), model, effort, +3 more.
doctorBRead-only
Check the Antigravity CLI, global worker state, and configured defaults.
Inputs: no named parameters.
get_accountARead-only
Report the active Antigravity account identifier without reading or returning OAuth credentials or tokens.
Inputs: no named parameters.
get_media_runARead-only
Read a multimodal run, optionally wait up to 30 seconds, and inline completed image or audio artifacts when small enough.
Inputs: run_id (required), wait_ms, include_media, include_prompt.
get_runARead-only
Read a worker run and optionally wait up to 30 seconds for progress or completion.
Inputs: run_id (required), wait_ms, include_prompt.
get_teamARead-only
Read a multi-agent team, optionally wait for progress, and optionally include its agent-to-agent transcript.
Inputs: team_id (required), wait_ms, include_transcript.
list_artifactsARead-only
List generated media artifacts and their absolute paths, hashes, MIME types, and sizes from the global ledger.
Inputs: kind, limit, run_id.
list_modelsARead-only
List models currently available to the active Antigravity account and show the configured quality, balanced, and fast routes.
Inputs: no named parameters.
list_runsBRead-only
List recent Antigravity worker runs from the global operational ledger.
Inputs: cwd, limit.
list_teamsARead-only
List recent multi-agent teams from the persistent operational ledger.
Inputs: cwd, limit.
message_agentA
Send a persisted message from Codex or one team member to another. Delivery continues the recipient's Antigravity conversation and records the reply.
Inputs: message (required), team_id (required), to_agent_id (required), from_agent_id.
resume_teamA
Restart an interrupted or failed team from its original assignments, preserving a link to the prior team ledger.
Inputs: team_id (required).
start_analysisBRead-only
Start an asynchronous read-only Antigravity worker for bounded investigation or planning.
Inputs: cwd (required), task (required), model, effort, +5 more.
start_editA
Start an asynchronous Antigravity implementation worker in an isolated Git worktree. It cannot directly alter the active checkout.
Inputs: cwd (required), task (required), acceptance_criteria (required), model, +5 more.
start_image_editA
Edit or transform one to five explicitly supplied reference images with Antigravity's native generate_image tool and capture the result.
Inputs: prompt (required), image_paths (required), model, effort, +5 more.
start_image_generationB
Generate one image with Antigravity's native generate_image tool and capture it in the persistent artifact ledger.
Inputs: prompt (required), model, effort, max_retries, +4 more.
start_media_analysisARead-only
Analyze explicitly supplied images, PDFs, audio, video, documents, datasets, or other files with Antigravity's native multimodal capabilities. Inputs are copied into a per-run isolated Git workspace.
Inputs: task (required), file_paths (required), model, effort, +4 more.
start_reviewARead-only
Start an asynchronous read-only Antigravity worker to critically review code or a proposed change.
Inputs: cwd (required), task (required), model, effort, +5 more.
start_teamCRead-only
Start a queued multi-agent Antigravity team. Workers investigate in parallel, exchange reports through a lead coordinator, perform correction rounds, and finish awaiting independent Codex review.
Inputs: cwd (required), agents (required), objective (required), name, +10 more.
team_dashboardBRead-only
Return a compact live dashboard snapshot with team progress, agent states, recent events, messages, and result preview.
Inputs: team_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools are clearly separated by domain (account, models, media, runs, teams), but start_media_analysis vs start_analysis vs start_review vs start_edit could cause some confusion since all are 'start' actions on different worker types. The descriptions help distinguish them, though the media vs analysis boundary is slightly less obvious.
The naming is mostly consistent with verb_noun patterns: get_account, list_models, start_analysis, get_run, cancel_run, apply_run. Minor deviations exist: 'doctor' is a noun-only command, and 'team_dashboard' is noun-first rather than verb_noun, but the overall pattern is predictable.
23 tools is on the higher end but appropriate for a server covering account info, model listing, media generation/analysis, async runs, and multi-agent teams. Each tool serves a distinct operational purpose, though a few could be consolidated (e.g., team_dashboard vs get_team).
The surface covers the main lifecycle: starting runs, reading runs, continuing, cancelling, and applying edits; teams can be started, read, messaged, cancelled, and resumed. Minor gaps include no explicit tool for listing models' details beyond routes, no media cancellation, and no direct team result artifact listing, but core workflows are covered.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Reliable async execution for agent tool calls: schema gating, retries, idempotency, audit trail.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude to delegate tasks to external coding agents (Codex or Antigravity) for independent reviews, separate quota usage, and async processing.6MIT
- AlicenseAqualityBmaintenanceEnables Claude Code and Claude Desktop to delegate token-heavy tasks to Antigravity headless subagents, offloading file edits, test runs, and exploration while preserving Claude's context window.1225 npm1MIT
- FlicenseNot gradedqualityCmaintenanceEnables Codex to delegate bounded tasks to multiple AI model workers through a persistent OpenCode 2 service, with isolated Git worktrees and safe patch review and application.-
- AlicenseNot gradedqualityBmaintenanceEnables delegating bounded tasks from Codex to Claude Code, including read-only reviews, isolated branch edits, long-running background work, and approval handling.455 npmMIT