pi-agy-bridge

Use Antigravity models in Pi without changing how Pi works.

The bridge connects Antigravity models to Pi Coding Agent. Pi manages the conversation and executes registered tools.

The bridge supports two drivers:

• Antigravity ACP (acp): Connects to the standalone Antigravity ACP server managed by the bridge.
• Antigravity CLI (cli): Connects to the user-installed Antigravity CLI through agy acp --stdio.

Both drivers communicate over the Agent Client Protocol (ACP). Each driver uses its own runtime, model catalog, and capabilities.

Architecture

Pi runs the agent. Antigravity provides the models.

Pi Coding Agent
  |  Prompts and session context
  v
pi-agy-bridge
  |  ACP protocol
  +-- acp: Antigravity ACP (managed ACP server)
  |
  +-- cli: Antigravity CLI (installed `agy` CLI)
  |
  v
Antigravity models
  |
  |  Tool requests
  v
Local MCP bridge
  |
  v
Pi tools -> Results return to the model

Features

• Native Pi Experience — Keep Pi tools, extensions, skills, and session history. Tool requests run through Pi with its applicable permissions.
• Native Tool Limits — Limit Antigravity's native tool capabilities so supported tool requests run through Pi.
• Two Drivers, One Protocol — Choose Antigravity ACP or Antigravity CLI. Both drivers communicate over the ACP protocol.
• Session Continuity — Reuse compatible sessions. Restore context from Pi history when needed.
• Image Support — Read images through Pi tools. The ACP driver also supports automatic image loading and uses an observer for offloaded images.
• Automatic ACP Setup — Download and verify the pinned ACP server.
• Diagnostics — Check your setup with /agy-bridge:doctor. The CLI driver also reports account quotas.

Requirements

Quick Start

1. Install the Extension

Install the extension with Pi:

pi install npm:@ackneal/pi-agy-bridge

Or install it from GitHub:

pi install git:github.com/ackneal/pi-agy-bridge

2. Sign In

1. Run:

   /login

2. Select Antigravity [pi-agy-bridge] from the provider list.
3. Complete sign-in in your browser.

Startup checks and diagnostics do not open a sign-in browser. Use /login to sign in.

3. Select a Model

1. Open the model selector:

   /model

2. Type agy to find Antigravity models. Available models depend on the selected driver.
3. Select a model and start using Pi.

Command Reference

Driver and doctor results are user-only notifications, not model conversation messages. Without a UI, results are written to stderr.

How It Works

Choose a Driver

Choose Antigravity ACP (acp) for automatic setup and automatic image loading. Choose Antigravity CLI (cli) if you use the installed agy CLI or need its third-party model catalog.

Use /agy-bridge:driver to switch drivers and /model to see available models. On startup, the bridge uses the driver recorded in its saved authentication. If no saved authentication or valid driver is present, it defaults to ACP.

Images: ACP uses an additional observer for offloaded images, which may add latency and model usage. Tool-based reads remain available for images in history and other locations.

Usage: Pi's standard usage display shows token usage and costs estimated from configured model prices, including overrides in models.json. Estimates do not represent AGY billing or quota consumption. For CLI account quotas, use /agy-bridge:doctor.

Sessions

The bridge reuses a native session when it matches Pi's history. If Pi branches or compacts a conversation, the bridge can rebuild the model context from Pi's saved messages.

Configuration

Environment Variables

For a custom ACP distribution, keep both files in the same directory and set:

export AGY_ACP_DIR="$HOME/path/to/agy-acp-server"

Managed ACP Server Details

• Version: Antigravity ACP Server 1.4.5 (macOS and Linux, x64 and ARM64).
• Registry: src/extension/drivers/acp/registry.json.
• Storage: <Pi Agent Home>/pi-agy-bridge/acp/<archive-name>/ (typically ~/.pi/agent/pi-agy-bridge/acp/).
• Verification: SHA-256 checksums are verified before extraction.

Troubleshooting

Run /agy-bridge:doctor to check the installation, connection, and sign-in status.

Common Problems

• ACP download or extraction fails: Check your network, disk space, and permissions under ~/.pi/agent/. Downloads are about 93–307 MiB. Linux extraction can require about 1 GiB.
• Signed out: Run /login and select Antigravity [pi-agy-bridge].
• No models appear: Sign in and run /agy-bridge:doctor. When offline, the bridge can use a cached model catalog.
• CLI driver unavailable: Install agy at ~/.local/bin/agy or add it to your PATH, then run /agy-bridge:doctor.
• Custom ACP server fails: Check that AGY_ACP_DIR is an absolute directory path containing executable agy_acp_server.par and localharness_external files. Unset AGY_ACP_DIR to use the managed server.
• Enable debug logs:

  export AGY_BRIDGE_DEBUG=1
  pi

Development

Use Bun to install dependencies. Use Node.js to run tests:

# Install dependencies
bun install

# Verify version alignment
bun run check:version

# Run TypeScript type check
bun run typecheck

# Run test suite
bun run test