Pi Antigravity Bridge

A Gemini model provider and the AskAntigravity delegation tool for pi, built on Google's official Antigravity binaries: the agy CLI by default, or Google's official ACP server (opt-in). It registers antigravity/gemini-* models in pi's /model picker (streaming), and provides the AskAntigravity tool for one-shot delegation - the same combined shape as pi-claude-bridge.

If you also have @estebanforge/pi-ask-antigravity installed, this bridge takes over: pi-ask-antigravity detects the bridge and registers nothing, so the AskAntigravity tool is never duplicated.

What it does

You pick a Gemini model in pi's /model picker. pi routes each turn through this provider. A single persistent agy process runs in your workspace; pi feeds it each turn, parses its stream-json events, and streams the agent text back into pi token by token. Token usage is live.

Multi-turn works. The provider binds a pi session to an agy conversation id (persisted under ~/.pi/agent/antigravity-bridge/sessions.json) and resumes it on the next turn via --conversation <id>. agy keeps its own history, so only the latest user message is sent each turn.

Two engines

Turns run through one of two engines behind the same provider surface (config.engine, default stream-json):

• stream-json (default): the persistent agy CLI process. The tested default; live token usage; conversation resume via --conversation.
• acp (beta): Google's official ACP server (agy_acp_server.par), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via session/load, bridge tools, effort switching, serialization, abort recovery (see scripts/parity-live.mjs). Two known RC01 gaps remain: no usage fields (token display shows client-side ESTIMATES until Google ships usage; acp.usageEstimate off to keep zeros) and no cancel (abort tears the server down and reloads it next turn).

The choice of engine is left to the user, with the trade-offs explained in the tool: a first-run picker modal asks once on a fresh install (stream-json preselected; esc defers, and the modal reappears next start), and /agy engine with no arguments reopens it anytime. An acp pick downloads the ~1.5 GB server binary and starts the Google sign-in immediately; a restart applies the engine. With stream-json active and the agy binary missing, pi warns on every start until the binary is found.

Full capability comparison, switching, and setup/auth details: docs/ENGINES.md.

Switch and setup details live in docs/ENGINES.md: switching to acp self-installs Google's official server binary from the antigravity-acp registry entry and prepares the login (your Antigravity subscription, same account as the agy CLI; the extension never sees your credentials). /agy auth signs in explicitly, /agy doctor diagnoses, and a session start self-heals silently when everything is ready. Sessions are engine-scoped, so switching engines never crosses conversations.

What it cannot do

agy runs its own closed tool loop (read_file, write_file, edit_file, run_command) against --add-dir. Its read-only steps (view_file, list_dir, grep_search, find_by_name) re-run as real pi builtins (read, ls, grep, find) so their cards render natively; mutating steps never execute in pi - they replay through a display-only antigravity wrapper tool. What used to be a hard wall for pi's other tools is bridgeable; see MCP tool bridge below.

Residual limits (with or without the bridge):

• agy's own edits still land directly on disk; pi's inline diff review does not engage for them.
• agy commands run without per-action approval by default, same as every other tool in pi. The Approval gate can put pi-side review in front of agy's mutating native tools (off by default; auto enables it only when a pi permission extension is installed). See also Permissions below.
• No cost accounting: cost stays zero because agy runs on your subscription quota. Token usage is live.

MCP tool bridge (agy uses pi's tools)

While agy is the active model it normally cannot see pi's universe of extensions: agentmemory, codegraph, web search, slack/asana, the Ask* delegations, and any other installed pi tool. This extension optionally bridges that gap.

The bridge starts a localhost MCP server inside pi's process. tools/list returns pi's registered tools (built-in file/shell tools and AskAntigravity are filtered out), and a tools/call routes into pi's own tool loop via the round-trip described below. Discovery has two layers. The provider's agy gets a per-invocation config: the bridge writes .agents/mcp_config.json into a bridge-controlled dir (~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/) and the driver passes that dir as an extra --add-dir when it spawns agy. A per-pid entry (pi-bridge-<pid>) is also registered in the user's global agy config (~/.gemini/config/mcp_config.json; foreign servers preserved, stale entries swept at start), so agy builds that read only the global config still find the bridge.

No patch required. Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a toolUse stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.

Long calls don't die. agy's MCP client abandons a tools/call request at a flat ~180s, which used to kill any pi tool that ran longer (a long peer review, a build, a commit preview waiting for you). A call still running after ~20 seconds now settles its HTTP request with a STILL RUNNING answer carrying a callId while pi keeps executing; agy fetches the result through the bridge-local bridge_poll_result tool and polls until it lands. Escalated calls get their own 30-minute budget, so human-gated tools can take as long as the human takes. Fast calls stay fully synchronous and never see any of this. If a park does fail (abort, timeout, recycle), the late result is re-routed to agy as a follow-up prompt in the same conversation instead of being lost.

Recursion safety. Only the provider's agy receives the extra --add-dir. AskAntigravity is also filtered from the exposed tool list. Its delegated agy -p spawns with just the workspace, and for the whole delegated run the bridge hides its global per-pid entries: disabled before the spawn, released only on process close or error - agy watches the config and hot-reloads MCP servers on file changes, so a mid-run re-enable would poke the live delegation back into pi. A cross-process marker (suppression.json in the bridge's extensions-data dir) coordinates concurrent delegations: entries come back only when no live delegation remains, a session starting mid-delegation registers its own entry disabled, and the session-start heal re-enables only once the last delegator is gone (dead entries pruned by pid liveness with a 24h age bound). The inner agy therefore sees no bridge and cannot re-enter pi. Foreign servers in the global config are never touched.

Cost / fan-out. Every registered pi tool except builtins (and AskAntigravity) is exposed, including other delegation tools like AskClaude/AskCodex. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.

Security. The MCP server binds to 127.0.0.1 only and requires a per-session shared-secret header (x-bridge-token) that agy sends from the bridge config; browsers cannot set custom headers on a simple cross-origin POST, so this blocks web CSRF against the loopback server. Request bodies are size-capped. This is intended for single-user developer machines: any local process running as the same user can read the token from the per-pid config and call the exposed tools, so do not run it on a shared host where you do not trust other same-user processes.

Native cards, wrapper replay, and skills

Read-only agy steps (view_file, list_dir, grep_search, find_by_name) re-run as real pi builtins (read, ls, grep, find) when those builtins are active, so their cards render with pi's own renderers. Mutating and agy-specialty steps render through a display-only antigravity wrapper tool: its execute() replays the output agy already recorded, so the transcript gets proper toolCall/toolResult pairs without any double execution. Neither path re-runs anything with side effects.

When the bridge is on, agy also gets one activate_skill tool whose enum is your pi Agent Skills catalog; calling it returns the SKILL.md body. The bridge answers it directly, no pi round-trip. /agy doctor prints driver counters, bridge port, and the last lifecycle events without spending tokens.

Approval gate (agy native tools)

agy runs its own agent loop with native tools (run_command, create_file, edit_file, ...), which pi's permission extensions never saw. The optional approval gate routes those calls through a pi-side approval: a staged PreToolUse hook parks the call, the provider surfaces it as a shadow bash/write/edit toolUse, and your permission extension (or the built-in ask/allow/deny fallback) decides before agy executes it. Off by default (approvals.gateMode: auto enables it only when a pi permission extension is detected); denials fail closed; read-only agy tools stay ungated.

Full mechanics, configuration, and a sample gate extension: docs/APPROVAL-GATE.md.

Install

No patch required. The bridge runs on pi's public APIs only; the extension never edits your pi install. If an older version of this extension patched your pi (adding pi.invokeTool()), the leftover is inert and a pi update removes it. The extension detects it once and offers /agy patch-cleanup to restore the original files from the backup immediately.

Install with pi's package manager:

pi install npm:@estebanforge/pi-antigravity-bridge

Requires the agy CLI installed and authenticated. If you don't have it, follow Google's official install guide for your platform, then run agy once to complete Google OAuth. The extension resolves agy on $PATH, or via the AGY_BIN environment variable. While the stream-json engine is active and the binary cannot be found, pi warns on every start (toast in the TUI, stderr headless) pointing at the install guide; the warning stops once the binary is detected.

Usage

Pick a model and talk to pi as usual:

/model

Look for the models namespaced as: antigravity

Or specify a model directly:

/model antigravity/gemini-3-6-flash-medium

Model ids are slugified from the agy models output (Gemini 3.6 Flash (Medium) becomes gemini-3-6-flash-medium). Discovery runs once at extension load. Run /reload after an agy update to refresh the list.

If agy models fails at load (binary missing, auth not done, network stall), a fallback catalog still populates the picker so you get a clear runtime error instead of an empty list.

Bridge surface

config.json selects the bridge surface:

Key	Values	Default
askTool	on (register the AskAntigravity delegation tool), off (no delegation tool; provider and models only)	on
bridgeTools	none (bridge off), all (every non-builtin tool, incl. other Ask* delegations), mcp (pi-mcp-adapter tools + skills bridge only)	all
digest	off (stable prompts; agy's prompt cache hits) or on (inject a delta of pi-side context - compaction summaries, other-provider turns - into each agy prompt; the delta changes every turn, so agy re-bills the full context). Enable for mixed-provider sessions where agy must see pi-side context	off
systemPrompt	on (prepend pi's system prompt - operating instructions plus the global agent-dir AGENTS.md and ancestor AGENTS.md/CLAUDE.md - to the first prompt of each new agy conversation, plus a tool-priority note: Pi Bridge tools win over agy's native interactive ones, which never reach the user) or off (agy-native behavior)	on

Env overrides: AGY_BRIDGE_TOOLS, AGY_ASK_TOOL, AGY_DIGEST, AGY_SYSTEM_PROMPT. Env wins over the file, so while AGY_DIGEST or AGY_SYSTEM_PROMPT is set, the matching /agy digest or /agy system-prompt toggle persists a value that never takes effect.

The activate_skill catalog mirrors pi's directory-based skill discovery: the two global dirs plus project dirs, the latter only when pi has trusted the project (same gate pi itself applies). Pi's other skill sources - the skills settings array, package.json entries, and --skill CLI paths - are not mirrored and won't appear in the catalog.

The /agy command

/agy configures the provider at runtime. Settings persist to ~/.pi/agent/antigravity-bridge/config.json and take effect on the next turn.

/agy                      status, or open the full settings picker (TUI)
/agy status               print current settings + session counts
/agy doctor               bridge state, driver counters, bridge port, last lifecycle events, log dir
/agy auth                 run the antigravity-acp sign-in now (engine acp): opens the Google login in your browser, shows the URL when no browser opens
/agy mode plan            review-only: agy plans but writes nothing
/agy mode accept-edits    agy applies edits directly (default)
/agy permissions on|off   auto-approve / prompt for tool calls (see warning)
/agy ask on|off           register the AskAntigravity delegation tool (default on; off keeps only the provider and models, even with pi-ask-antigravity installed)
/agy model flash|pro|gemini   fallback model for the AskAntigravity tool; callers may override per call
/agy thinking low|medium|high fallback thinking tier for the AskAntigravity tool; callers may override per call
/agy digest on|off        inject pi-side context into agy prompts (default off; see table above)
/agy system-prompt on|off send pi's system prompt + AGENTS.md + the Pi Bridge tool-priority note to new agy conversations (default on)
/agy bridge all|mcp|none  which pi tools the MCP bridge exposes to agy (default all; none = bridge off)
/agy acp-bin <path|auto>  point the ACP engine at a specific server binary (auto = setup installs, or AGY_ACP_BIN; applies on the next ACP turn)
/agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp is beta and runs self-service setup: binary install + auth bootstrap). No arguments opens the engine picker modal (TUI)
/agy auth-manual             manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
/agy patch-cleanup        restore the original pi files if an older version patched them
/agy clear                drop all session bindings (force fresh conversations)

Permissions

pi itself has no built-in approval gate. Unlike codex, claude, or agy running interactively, pi does not prompt you to confirm each tool action before it runs. That is the host environment this extension lives in.

Because agy runs non-interactively under this provider (nothing can answer a y/n prompt), this extension passes --dangerously-skip-permissions by default. It is technically necessary: accept-edits auto-approves file edits but not shell commands, so a run_command would otherwise hang forever waiting for a prompt nothing can answer (upstream google-antigravity/antigravity-cli#318). The net effect is that agy executes commands the same way pi already executes your other tools: without per-action review.

If you want agy to execute nothing, use /agy mode plan. Do not combine --sandbox with skip-permissions (#36).

For per-action review of agy's mutating native tools (run_command, create_file, edit_file, ...), see the Approval gate: with it on, the call must pass a pi-side approval (your permission extension, or the built-in ask/allow/deny fallback) before agy executes it.

Run pi inside a sandbox

For isolation when running any agent that executes commands without a confirmation gate, run pi inside construct-cli - EstebanForge's sandbox for AI agents. Isolated container, no path escape, ephemeral filesystem, strict / offline network modes, secret redaction. The blast radius of a bad command stays in the container, not your host. Install and usage instructions are in that repo.

Environment variables

Variable	Purpose
AGY_BIN	Path to the agy binary. Defaults to agy on PATH.
AGY_ENGINE	Engine: stream-json (default) or acp. Wins over the config file.
AGY_ACP_BIN	Path to the ACP server binary (agy_acp_server.par). Defaults to agy_acp_server.par on PATH. Wins over config.acp.bin. When neither points at a binary, auto-setup installs one.
AGY_EXTRA_ARGS	Extra args appended to every invocation. Whitespace-split.
AGY_CONVERSATIONS_DIR	Override the conversations DB directory.
AGY_MODE	Override execution mode: plan (review-only) or accept-edits (default). Wins over the config file.
AGY_SKIP_PERMISSIONS	1/true (default) to pass --dangerously-skip-permissions so commands don't hang on an unanswerable prompt in -p mode. 0/false to prompt (hangs any run_command non-interactively). Wins over the config file.
AGY_DEFAULT_MODEL	Default model alias for the AskAntigravity tool (flash/pro/gemini, or a tier/version qualifier). Wins over the config file.
AGY_DEFAULT_THINKING	Default thinking tier for the AskAntigravity tool: low/medium/high. Anything else falls back to medium. Wins over the config file.
AGY_DEBUG	1/true/on writes the full trail to the daily log (driver lifecycle, raw bridge traffic). Default off: only error records land on disk - routine disk writes are zero for regular users, and warnings surface as UI toasts instead.

Debug logs

The extension keeps a daily log on your machine, sorted by day:

~/.pi/extensions-data/estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson

One JSON record per line. Two verbosity tiers keep the disk cost at zero for regular users: by default only error records land on disk - everything routine (turn starts, tool calls, escalations, commands, driver failures) is withheld. Warnings are not lost: the extension toasts each one in the pi UI (bridge tool failures, stalls, timeouts, process exits), so users see them and can report them; deliberate aborts and failures pi already renders as the turn's own error block stay silent. Set AGY_DEBUG=1 before reproducing a problem for the full trail: per-event driver lifecycle (spawn, exit, session load/new, unparks), turn starts and outcomes, bridge tool calls, escalations and poll traffic, late deliveries, list-tools traffic, recycle causes, and the raw bridge chatter. /agy doctor prints the log directory.

Notes:

• Retention: 14 days. Older files are pruned automatically.
• Privacy: prompt text, tool arguments, and tool output never land in the log. Secret-shaped values (tokens, API keys, credentials, header blocks) are redacted, and long strings are truncated. The auth-url record strips the login URL's query string.
• Logging never throws: an unwritable directory is skipped silently and retried on the next record.
• SSD wear: default volume is effectively zero until something actually errors. Verbose mode (AGY_DEBUG=1) writes more; turn it off after reproducing.

When you report an issue, attach the last day or two of files from that directory. For anything that needs reproduction, run with AGY_DEBUG=1 once and attach that day's file. They usually contain the exact failure sequence (engine, session, bridge call, error) with no need to guess.

Development

Build, test, and debug instructions live in docs/DEVELOPMENT.md. For the internal architecture (engines, bridge round-trips, conversation discovery) see docs/ARCHITECTURE.md.

Terms of Service notice

Google's Antigravity ToS (Section 6) prohibits accessing the service "in connection with products not provided by us", and names as its example using tools like Hermes/OpenClaw with Antigravity OAuth. That targets reusing your credentials in a non-Google harness that calls Google's backend directly.

This extension does not do that. It spawns official, unmodified Google binaries as subprocesses - the agy CLI, or the official ACP server when enabled - which perform their own OAuth and make their own calls to Google. This code never sees, extracts, or reuses your token, and never contacts Antigravity's backend. It only reads what the binary itself produces locally: its stream-json output, or its ACP JSON-RPC messages. From Google's server-side view there is no signal that distinguishes "agy launched by pi" from "agy launched by a terminal, an IDE task runner, or cron": same signed binaries, same authenticated calls.

Google's reported enforcement to date (the February 2026 suspensions) targeted token-reuse tools, not spawning the official CLI.

pi-antigravity-bridge practical risk is low, near zero. But not zero: the "in connection with" wording is broad, and Google can suspend accounts at its discretion regardless of whether a breach is provable. Grey area. Safe for now. You should read "news" about this online from time to time.

This is engineering analysis, not legal advice. Use against your own Antigravity account at your own risk; I am not responsible for any consequence to your account.

License

MIT.