Antigravity Gemini Delegate

A CLI-first Gemini delegation router for Codex, with a portable local-STDIO MCP compatibility entrypoint. The shared runtime is policy-neutral; each project owns its routing guidance and enforceable policy.

Version 0.5 makes the bundled direct CLI the primary path when Codex has terminal access. The MCP remains available for hosts that cannot launch local processes. Both paths share the same validation, output contract, project policy, timeouts, and environment isolation.

Version 0.5.1 removes the discontinued Gemini CLI path. Python remains a thin dependency-free orchestrator, while every model task runs through Antigravity CLI (agy) headless JSON mode. Readiness exposes missing installation, authentication, model mappings, project policy, routing, and workspace permissions instead of hiding them.

Install the Codex Plugin from GitHub

After this version is merged to the repository's default branch:

codex plugin marketplace add silennsong/Antigravity-MCP-Tool
codex plugin add antigravity-mcp@antigravity-tools

Start a new Codex task after installation so the bundled Skill and compatibility MCP tools are loaded. A natural-language trigger is enough:

完成这个任务，过程中可以调用 Gemini MCP。

Explicit invocation is the most deterministic option:

使用 $gemini-delegation-router 完成这个任务。

The Plugin bundles its dependency-free Python runtime, direct Skill launcher, and MCP adapter, so it does not depend on the repository checkout path or a globally installed Python package. It needs Python 3.10+ and Antigravity CLI. Interactive Google consent and project trust remain user-controlled.

For local development of this branch:

codex plugin marketplace add /absolute/path/to/Antigravity-MCP-Tool
codex plugin add antigravity-mcp@antigravity-tools

The marketplace definition is stored in .agents/plugins/marketplace.json; the installable package is under plugins/antigravity-mcp.

Related MCP server: Grok Plugin Codex

Install from a release package

Clone the public repository:

git clone --depth 1 https://github.com/silennsong/Antigravity-MCP-Tool.git
cd Antigravity-MCP-Tool
python3 bootstrap.py --install-agy

Or download and extract the source archive from the latest GitHub Release, inspect bootstrap.py, then run:

python3 bootstrap.py --install-agy

The bootstrapper:

1. Creates an isolated venv under ~/.local/share/antigravity-delegate-mcp/venv.

2. Installs this package without modifying the system Python environment.

3. Optionally installs agy from Google's official installer.

4. Registers antigravity_delegate globally through codex mcp add.

5. Preserves unrelated Codex configuration and adds MCP timeout/tool settings.

6. Runs doctor.

For interactive onboarding as part of setup:

python3 bootstrap.py --install-agy --auth --configure-models

Google OAuth, terms, data-use choices, and workspace trust require the user to interact with Antigravity. The installer does not silently accept them.

See AGENT_INSTALL.md for a prompt that can be copied to a local coding agent.

Project homepage: https://github.com/silennsong/Antigravity-MCP-Tool

First project connection

Restart Codex after installation, open the target project, and ask the Agent:

Use the gemini-delegation-router Skill. Prefer its bundled direct CLI readiness check; use the MCP readiness tool only if local process execution is unavailable.
Report every failed or missing check and the exact suggested commands.
Do not change global permissions or project files unless I explicitly approve the relevant command.

The readiness tool is read-only. It reports two independent states:

• ready_to_delegate: Antigravity CLI, authentication, and the requested model tier work.

• safe_project_ready: the project also has policy, AGENTS routing, and a read/deny-write permission pair.

For a complete explicit first-run setup from the terminal:

antigravity-delegate-mcp setup \
  --workspace /path/to/project \
  --auth \
  --configure-models \
  --init-project \
  --profile read-only \
  --deep

If the project already has AGENTS.md, inspect it first. Add --force only when you want the installer to append its clearly marked Antigravity routing block; existing content is preserved.

Commands

antigravity-delegate-mcp install --replace
antigravity-delegate-mcp auth --workspace /path/to/project
antigravity-delegate-mcp configure-models
antigravity-delegate-mcp readiness --workspace /path/to/project
antigravity-delegate-mcp delegate --workspace /path/to/project \
  --task-kind repository_exploration --task-file /path/to/task.txt \
  --model-tier flash --mode read_only
antigravity-delegate-mcp init-project --workspace /path/to/project --profile read-only
antigravity-delegate-mcp validate-policy --workspace /path/to/project
antigravity-delegate-mcp permissions audit --workspace /path/to/project
antigravity-delegate-mcp permissions sync --workspace /path/to/project
antigravity-delegate-mcp permissions prune --stale
antigravity-delegate-mcp doctor --workspace /path/to/project
antigravity-delegate-mcp doctor --deep --workspace /path/to/project

init-project offers two profiles:

• read-only: generates routing rules, a restrictive project policy, a local JSON Schema, and maps the mode to agy --mode plan --sandbox --disable-slash-commands.

• open: creates a minimal project policy without global task/model/mode restrictions.

Existing AGENTS.md files are not overwritten. Use --force to append a marked Antigravity section after reviewing the file.

The read-only profile also adds scoped Antigravity CLI grants in ~/.gemini/antigravity-cli/settings.json: recursive read_file(<project>) is allowed and write_file(<project>) is denied. Use --no-agy-permissions to skip that explicit initialization change.

Absolute-path permissions are global Antigravity CLI state. Renaming or moving a project can leave a stale historical rule. The lifecycle is deliberately explicit:

1. permissions audit reads current coverage and stale paths without changing anything.

2. permissions sync adds only the supplied workspace's read/deny-write pair.

3. permissions prune --stale is preview-only.

4. Rerun the prune command with --yes only after reviewing every listed rule.

Delegation never edits this permission file automatically. Permission or authentication failures return structured onboarding_required, code, and actions fields so an Agent can explain exactly what is missing.

Responsibility split

Shared runtime layer:

• Exposes structured readiness and delegate CLI commands.

• Registers delegate_to_antigravity plus the read-only check_antigravity_readiness MCP fallback.

• Resolves stored or environment-provided Antigravity model names.

• Adapts to verified agy headless JSON flags and response metadata.

• Applies process timeout/output handling and returns structured metadata.

• Does not globally hard-code task categories, model routing, or read/write behavior.

Project layer:

• AGENTS.md tells Codex when delegation is useful.

• .codex/antigravity-policy.json defines enforceable task, model, mode, prompt, CLI-argument, output, and environment rules.

• .codex/antigravity-policy.schema.json gives editors a local policy schema.

• The closest policy found while walking upward from workspace is used.

Without a project policy, the global MCP applies no semantic task restriction.

Readiness may therefore report ready_to_delegate: true and safe_project_ready: false. This distinction preserves a policy-neutral global entrypoint while making incomplete project onboarding visible.

Authentication and model configuration

The official Antigravity CLI installer for macOS/Linux is:

curl -fsSL https://antigravity.google/cli/install.sh | bash

This project downloads the installer before executing it instead of piping it blindly. To complete Google OAuth and project trust:

antigravity-delegate-mcp auth --workspace /path/to/project

Then configure exact model IDs returned by agy models:

antigravity-delegate-mcp configure-models \
  --flash gemini-3.6-flash-low \
  --pro gemini-3.1-pro-high \
  --non-interactive

Mappings are stored with mode 0600 in:

~/.config/antigravity-delegate/config.json

Environment variables such as ANTIGRAVITY_FLASH_MODEL override stored mappings. Exact model input is also supported when project policy permits it.

Why Headless CLI instead of the Python SDK?

The public Antigravity Python SDK is useful for long-lived conversations, custom in-process Python tools, lifecycle hooks, triggers, and token streaming. This project performs bounded, usually one-shot delegation from another Agent. For that workload, agy --print --output-format json is the smaller and more reliable boundary:

• it reuses the user's existing Antigravity login, model access, settings, plugins, and permissions;

• subprocess isolation prevents the worker runtime from sharing the host Agent's Python process;

• exit codes, wall-clock timeout, stdout JSON, and environment forwarding are explicit;

• the Plugin stays dependency-free instead of adding a platform-specific SDK wheel and async runtime;

• process startup cost is negligible compared with a model task that runs for seconds or minutes.

Choose the SDK in a different product when it needs a persistent multi-turn Agent, custom Python tools, hooks, or high-frequency streaming. The decision here is intentionally Headless CLI, not a claim that the SDK is generally inferior.

Headless permissions

Antigravity print mode cannot display interactive tool-approval cards. A project that needs file access must first complete workspace trust or configure appropriately scoped Antigravity permission grants. init-project --profile read-only handles the scoped read/deny-write grant automatically. Do not solve this with --dangerously-skip-permissions unless the project explicitly chooses that risk.

The MCP treats exit code 0 with empty stdout as an error and returns Antigravity's permission explanation instead of reporting false success.

It classifies common missing prerequisites for Agents:

• antigravity_cli_missing

• model_mapping_missing

• authentication_required

• workspace_read_permission_missing

Each classified failure includes copy-paste remediation commands and confirms that no configuration change was made.

Tool input

{
  "task": "Inspect the repository entry points and map the main modules.",
  "task_kind": "repository_exploration",
  "workspace": "/absolute/path/to/current/project",
  "model_tier": "flash",
  "mode": "read_only",
  "max_output_chars": 12000,
  "timeout_seconds": 600
}

Globally, task_kind, model_tier, and mode accept project-defined strings. Project policy may restrict them. Passing model uses an exact Antigravity model name instead of tier lookup.

Project policy fields

• version

• allowed_task_kinds

• allowed_model_tiers

• allow_explicit_model

• allowed_modes

• model_tier_task_kinds

• mode_cli_args

• min_task_chars, max_task_chars

• max_output_chars, max_timeout_seconds

• forbidden_task_patterns

• worker_instructions

• required_output_sections

• forward_env

Use validate-policy or doctor before relying on a new policy.

Each forbidden-pattern entry may set ignore_negated: true when phrases such as “do not delete files” should not be treated as a request to perform the forbidden action.

Build distributable artifacts

python3 scripts/build_plugin_bundle.py
python3 -m build

Outputs:

dist/antigravity_delegate_mcp-<version>-py3-none-any.whl
dist/antigravity_delegate_mcp-<version>.tar.gz

Verification

python3 -m unittest discover -s tests -v
antigravity-delegate-mcp doctor --deep --workspace /path/to/project
codex mcp get antigravity_delegate

Runtime Python dependencies are intentionally empty. Python 3.10 or newer is required.

Plugin-specific validation:

python3 scripts/build_plugin_bundle.py
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  plugins/antigravity-mcp/skills/gemini-delegation-router
python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  plugins/antigravity-mcp