Codex-Antigravity Bridge

This bridge allows Codex (or other MCP-compatible clients) to delegate tasks to the Google Antigravity CLI and receive responses back.

On Windows, agy --print may exit successfully but return empty stdout when executed from a non-interactive subprocess. agy_pty.py bypasses this limitation using ConPTY (pywinpty). It spawns agy inside a pseudo-terminal (PTY), captures the terminal output, and returns the cleaned text to the caller.

Workflow

Codex -> MCP server -> agy_pty.py -> ConPTY -> agy.exe -> Antigravity

The bridge detects the capabilities of the installed agy CLI using a capability probe. On Windows, the PTY backend is used by default because direct stdout capture for agy -p can return empty output even if the model responds successfully.

Installation

python -m pip install --user -r requirements.txt

Additionally, ensure you have the Antigravity CLI installed:

where.exe agy
agy --version
agy update

Quick Verification

To verify the low-level wrapper:

python agy_pty.py "What is 2+2? Answer with one digit only." --timeout=60s --json

Expected output:

"4"

To verify the MCP server via stdio:

python mcp_server.py

When run in a standard console, this command will wait for an MCP client. For actual validation, register it in your Codex MCP config or run a test MCP client.

Model Selection

Antigravity CLI 1.0.5+ supports the official --model flag:

agy --model "Gemini 3.5 Flash (High)" -p "Reply with exactly: OK"

The bridge uses this flag automatically if the capability probe detects support for --model (default for agy 1.0.6+).

For older CLI versions, the bridge falls back to temporarily modifying:

%USERPROFILE%\.gemini\antigravity-cli\settings.json

The fallback sequence is:

1. The bridge acquires a lock file near settings.json.
2. It backs up original settings.
3. Temporarily sets "model": "<label>".
4. Runs agy.
5. Restores original configuration (reverting only the model field without overwriting other settings).

If the process is hard-killed during fallback model override, the next bridge invocation will detect the crash marker near settings.json and restore the original model value (if the current setting still matches the left override).

On agy 1.0.6+, settings.json is not modified for model selection.

Diagnostic example:

python agy_pty.py "Reply with exactly: OK" --model "Gemini 3.5 Flash (High)"

The bridge fetches the list of models by running agy models via PTY. If the CLI is unavailable, it falls back to:

models.json

MCP Server

Codex config:

[mcp_servers.antigravity]
command = "python"
args = ["C:\\path\\to\\codex-antigravity-bridge\\mcp_server.py"]
enabled = true
required = false
startup_timeout_sec = 60
tool_timeout_sec = 600

Tools:

• antigravity_delegate: Sends a prompt to Antigravity and returns the response.
• antigravity_delegate_async: Starts delegation in the background and returns a job_id.
• antigravity_run_status: Checks the status of an async job.
• antigravity_get_summary: Gets the summary of an async job.
• antigravity_get_result_path: Gets the file path to the full result of an async job.
• antigravity_smoke_test: Verifies the installation path, expects MCP_OK.
• antigravity_capabilities: Displays agy version, flags/subcommands, and recommended backend.
• antigravity_current_settings: Displays non-sensitive bridge settings and trusted roots.
• antigravity_list_models: Lists model labels retrieved from agy models with fallback to models.json.

antigravity_delegate supports return_mode:

Value	Returned to Codex
full	Complete response inline + writes result.md
file_summary	Brief summary, metadata, and path to result.md (full response is kept in the file)

To save Codex tokens, use file_summary:

{
  "return_mode": "file_summary",
  "summary_max_bullets": 5
}

Run artifacts are written to:

<cwd>/.agentboard/antigravity/runs/

This directory should not be committed. The bridge automatically retains only the last 50 runs in each workspace.

Capability probe:

{
  "include_live_probe": false
}

include_live_probe: false does not consume LLM quota (the bridge only reads agy --version and agy --help). include_live_probe: true sends a small smoke prompt and verifies direct stdout against the PTY backend.

Prompt guardrails:

• Hard limit: 12,000 characters (after adding mode: "advise" wrapper text).
• Warning: triggered after 8,000 characters.
• If the hard limit is exceeded, the request is not sent to Antigravity, and only a truncated preview is written to the run directory.

Migration to Another Project

There are two migration modes: project-local and global.

Project-Local

In this mode, the bridge resides within each project.

1. Copy the repository files into your project folder, e.g.:

tools/antigravity-bridge/

2. Install dependencies in the new project:

python -m pip install --user -r tools\antigravity-bridge\requirements.txt

3. Verify Antigravity CLI:

where.exe agy
agy --version

4. Add local run folders to .gitignore of the new project:

.antigravitycli/
.agentboard/
__pycache__/

5. Run a smoke-test once from the root of the new project:

python tools\antigravity-bridge\agy_pty.py "Reply with exactly: OK" --add-dir "<ABSOLUTE_PROJECT_PATH>" --timeout=60s

6. Add the MCP server to %USERPROFILE%\.codex\config.toml, substituting the project path:

[mcp_servers.antigravity]
command = "python"
args = ["<ABSOLUTE_PROJECT_PATH>\\tools\\antigravity-bridge\\mcp_server.py"]
enabled = true
required = false
startup_timeout_sec = 60
tool_timeout_sec = 600

7. Restart Codex to reload the MCP config.

8. Call antigravity_smoke_test in the new project.

Global MCP

In this mode, the bridge is placed in a single global location, e.g.:

C:\Users\username\.codex\tools\codex-antigravity-bridge\

The active project path is passed via cwd/add_dirs in each MCP tool call. To let the bridge know which workspaces are trusted, add environment variables to the MCP config:

[mcp_servers.antigravity]
command = "python"
args = ["C:\\Users\\username\\.codex\\tools\\codex-antigravity-bridge\\mcp_server.py"]
enabled = true
required = false
startup_timeout_sec = 60
tool_timeout_sec = 600

[mcp_servers.antigravity.env]
ANTIGRAVITY_BRIDGE_WORKSPACE_ROOT = "C:\\path\\to\\your\\project"
ANTIGRAVITY_BRIDGE_TRUSTED_ROOTS = "C:\\path\\to\\your\\project"

ANTIGRAVITY_BRIDGE_WORKSPACE_ROOT defines the default cwd if the tool call doesn't specify one. ANTIGRAVITY_BRIDGE_TRUSTED_ROOTS defines additional allowed roots; multiple paths are separated by the OS path separator (; on Windows).

If environment variables are not set, the fallback remains project-local:

BRIDGE_DIR.parent.parent

Run artifacts are always written to the active workspace (i.e. <resolved_cwd>/.agentboard/), not next to the global bridge scripts.

Troubleshooting

If agy throws a symlink error:

A required privilege is not held by the client

Enable Windows Developer Mode and restart your terminal/Codex. Antigravity uses .antigravitycli/ as a local project link to its settings in %USERPROFILE%\.gemini\config\projects.

If antigravity_delegate returns an empty response:

• Do not call agy --print directly;
• Run agy_pty.py smoke-test;
• Verify pywinpty is installed;
• Verify the Antigravity CLI is authenticated.
• If pywinpty is broken or missing, the bridge returns a diagnostic warning and falls back to standard subprocess execution (which may not capture stdout on Windows).

If the prompt is rejected due to size:

• Do not paste entire files;
• Pass file paths;
• Instruct Antigravity to read only specific files or sections.

If you need a different model:

• Call antigravity_list_models;
• Pass the exact label in model;
• If agy models fails, update the fallback models.json.