Overview

Refined Antigravity ACP is a proxy wrapper around Google's official Antigravity ACP binary (agy_acp_server.par).

Google's binary executes models, agent loops, and tool calls. This proxy intercepts the ACP stream between editor and server to fix upstream crashes and deadlocks, normalize MCP traffic, and integrate with Paseo, Zed, and other ACP clients.

flowchart LR
    subgraph Editors["Supported ACP Clients"]
        PaseoUI["Paseo<br>(ACP Agent Provider)"]
        ZedUI["Zed Editor<br>(Stdio Agent)"]
        OtherUI["Neovim / JetBrains / Custom<br>(Standard ACP)"]
    end

    subgraph Wrapper["Refined Antigravity ACP (Proxy & Hardening Layer)"]
        direction TB

        Supervisor["Process Supervisor<br>• Subprocess Lifecycle & Health<br>• Transparent Crash Recovery<br>• Multi-Session State Cache"]

        subgraph Pipeline["Bidirectional ACP Pipeline"]
            direction TB
            Outbound["Outbound Stream<br>• Request & Option Normalization<br>• Workspace Context Injection<br>• MCP Port & URL Rewriting"]
            Inbound["Inbound Stream<br>• Output & Stream Sanitization<br>• Progress & Plan Synthesis<br>• Interruption Leak Cleanup"]
            Telemetry["Telemetry & Diagnostics<br>• Real-time Stderr Event Tracking<br>• SQLite Checkpoint & History Repair<br>• Token Usage Extraction"]
        end

        McpProxy["Loopback MCP Proxy Pool<br>• Dynamic Endpoint Remapping<br>• Protocol Version Adaptation"]

        Supervisor <--> Pipeline
        Supervisor <--> McpProxy
    end

    subgraph Upstream["Google Official Backend"]
        Kernel["agy_acp_server.par<br>(Google Subprocess)"]
        LocalDb[(Local SQLite Store<br>Conversations & Steps)]
        GeminiCloud["Google DeepMind / Gemini Cloud"]

        Kernel <-->|gRPC / HTTPS| GeminiCloud
        Kernel <-->|WAL Journal| LocalDb
    end

    Editors <-->|Stdio NDJSON CLI| Supervisor
    Supervisor <-->|Standard ACP NDJSON| Kernel
    Pipeline -.->|Direct Read / Heal| LocalDb
    McpProxy <-->|HTTP Rewriting| Kernel

    classDef editor fill:#20744A,stroke:#10B981,color:#fff,stroke-width:2px
    classDef wrapper fill:#0F172A,stroke:#3B82F6,color:#fff,stroke-width:2px
    classDef component fill:#1E293B,stroke:#60A5FA,color:#fff,stroke-width:1px
    classDef google fill:#18181B,stroke:#71717A,color:#fff,stroke-width:2px
    classDef db fill:#312E81,stroke:#818CF8,color:#fff,stroke-width:2px

    class PaseoUI,ZedUI,OtherUI editor
    class Supervisor,Pipeline,McpProxy,Outbound,Inbound,Telemetry component
    class Kernel,GeminiCloud google
    class LocalDb db

The matrix below documents upstream defects across process startup, turn execution, cancellation, and session replay. Each entry links directly to tests demonstrating the defect (Problem) and the fix (Solution).

[!TIP]

⭐️ Help Retire These Patches

Refined Antigravity ACP is a transitional hardening layer. When Google resolves a defect in an official release, the corresponding problem test verifies the fix and the wrapper retires the patch.

To help prioritize upstream fixes:

• Star the repository: Community visibility signals to the Google Antigravity team which upstream defects impact real users.
• Report new issues: If you encounter an unhandled crash, deadlock, or protocol edge case, open an issue. Every report includes a reproducible problem test and a solution test.

| Defect | Upstream Problem | Solution | | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Missing Localharness Binary | Problem: agy_acp_server invokes sibling ./localharness_external. When relocated or spawned in an isolated directory without $ANTIGRAVITY_HARNESS_PATH, it crashes on session/new.🔗 problem: startup crash | Searches standard install paths, downloads the official package if missing, and exports the resolved $ANTIGRAVITY_HARNESS_PATH.🔗 solution: harness resolution | | Missing Custom System Prompt | Problem: Stock ACP protocol does not support injecting custom workspace rules, agent personas, or profile system prompts.🔗 problem: missing system prompt context | Injects client-configured systemPrompt (via _meta.systemPrompt or nested _meta.<client>.systemPrompt) and tool visibility guidance into prompt turns without polluting saved history.🔗 solution: prompt injection | | Unadvertised Workspace Slash Skills | Problem: Raw ACP only advertises built-in model commands and ignores custom workspace skills defined in .agents/skills or .gemini/skills.🔗 problem: missing slash skills | Discovers SKILL.md files across all configured workspace directories and dynamically augments available_commands_update.🔗 solution: skill augmentation | | Subagent Deadlock & Hang | Problem: Subprocesses can enter unmonitored hangs or panic (could not find doneCh for checkpoint) during background task execution.🔗 problem: unmonitored hang | Monitors telemetry activity and stderr panics to trigger process recycling without mutating upstream Python bytecode.🔗 solution: hang telemetry recycling | | Malformed Stream Syntax & LaTeX | Problem: LLM outputs unquoted node labels with parentheses (id[Label (Prod)]) and raw LaTeX math (\\le), crashing frontend Mermaid and markdown parsers.🔗 problem: syntax normalization | Wraps parenthetical labels in quotes ["..."] and converts LaTeX escapes to clean Unicode characters (≤, →, ≠) across streaming chunks.🔗 solution: stream sanitizer | | Active Foreground Turn Collision | Problem: Sending a prompt while the model is executing tool calls either crashes or is rejected with "A foreground turn is already active".🔗 problem: foreground active collision | Categorizes mid-turn inputs (side questions, course corrections, or stop requests) with non-destructive steering directives and prompt retries.🔗 solution: user steering | | Interruption Cancellation Leak | Problem: Interrupted turns leak raw internal Go/Python cancellation exception strings ("context canceledThe request was cancelled by the client.") directly into assistant message chunks.🔗 problem: raw cancellation leak | Drops raw upstream cancellation error chunks so editor chat feeds remain clean on interruption.🔗 solution: cancellation drop | | Stale Ephemeral MCP Endpoints | Problem: When a hung child process is recycled, resending initial mcpServers with outdated localhost ports fails because proxy endpoints have changed.🔗 problem: stale proxy port | Uses McpProxyPool to dynamically intercept, remap, and heal MCP tool URLs across process restarts.🔗 solution: proxy URL remapping | | Orphaned SQLite Checkpoints | Problem: Canceling a turn leaves in-progress checkpoints uncommitted in SQLite, causing fatal panics ("could not find doneCh for checkpoint") on future turns.🔗 problem: orphaned checkpoint | Scans the session SQLite database on startup and teardown, updating orphaned in-progress checkpoints to ABORTED (status 5).🔗 solution: checkpoint repair | | Unscoped Database Corruptions | Problem: Global database repair scans would mutate concurrent session databases across open tabs, corrupting active turns.🔗 problem: concurrent tab safety | Scopes checkpoint repair strictly to the target sessionId.db, isolating concurrent editor tabs.🔗 solution: scoped session repair | | Database Concurrency Lockout | Problem: Raw DatabaseSync without busy timeout throws SQLITE_BUSY: database is locked when reading conversation steps during active writes.🔗 problem: raw sqlite busy error | Configures all database connections with timeout: 2000 to wait out locks during concurrent reads and writes.🔗 solution: sqlite timeout wait | | Dropped History Chunks on Load | Problem: Raw agy_acp_server drops thought chains and agent message chunks during session/load, loading an incomplete history.🔗 problem: dropped history chunks | Directly inspects protobuf steps in SQLite and reconstructs missing thought and message update events.🔗 solution: sqlite history reconstruction | | Noisy WebSocket stderr Logs | Problem: Upstream binary dumps unbuffered RAW WS MSG: debug payloads to stderr, flooding editor logs.🔗 problem: stderr noise | Filters noisy websocket trace logs from stderr by default, exposing them only when REFINED_AGY_TRACE=1 is explicitly set.🔗 solution: stderr filter | | Flattened Model Variants & Efforts | Problem: Upstream binary flattens all model and reasoning variants into a confusing 11-item flat dropdown list (gemini-3.8-flash-high, gemini-pro-agent, etc.) without dedicated reasoning controls.🔗 problem: flattened model list | Decomposes upstream models into clean base model choices (gemini-3.8-flash, gemini-3.1-pro, etc.) and injects standard reasoning effort controls (high, medium, low), translating settings upstream.🔗 solution: decomposed effort options | | Non-Canonical Mode ID Rejection | Problem: Upstream binary expects internal mode IDs (auto_edit, yolo, default) and rejects standard Paseo mode identifiers like accept-edits, dangerously-skip-permissions, and plan.🔗 problem: mode rejection | Translates client mode aliases to canonical internal IDs across outbound requests, session reloads, and child restarts.🔗 solution: mode normalization | | Silent Background Task Execution | Problem: Subagents and background tasks execute silently; upstream binary produces no stdout chunks during STATE_WAITING_FOR_TASKS, leaving editor UIs frozen.🔗 problem: silent background tasks | Synthesizes standard ACP session/update plan notifications (sessionUpdate: "plan") tracking active subagent roles and background tasks with live progress and completion.🔗 solution: plan synthesis | | Missing Usage & Token Metrics | Problem: Upstream binary never emits ACP usage_update notifications, leaving editor context window meters blank.🔗 problem: missing usage metrics | Intercepts SQLite step metadata to extract token counts and emits standard ACP sessionUpdate: "usage_update" with usedTokens and maxTokens.🔗 solution: token usage synthesis | | Dangling Running Tool Calls | Problem: When commands are backgrounded, upstream never emits terminal tool_call_update with status: "completed", leaving editor UIs with an infinite active running animation.🔗 problem: dangling running tool call | Tracks active tool calls and marks backgrounded tools completed immediately, before assistant text streams, and upon turn completion.🔗 solution: tool call auto-completion | | Interactive Question Deadlock | Problem: When ask_question is active, sending a chat prompt or cancel causes upstream to reject the message with "A foreground turn is already active", deadlocking sessions indefinitely.🔗 problem: question collision | Intercepts user chat prompts and cancellations to auto-unblock pending question permission requests to the child process and complete UI tool states.🔗 solution: question unblocking | | Premature Empty Turn Stop | Problem: Upstream binary prematurely concludes prompt turns with empty completions (stopReason=16) without emitting assistant message chunks, leaving editor UIs frozen in silence.🔗 problem: premature turn termination | Injects system prompt steering and intercepts empty prompt turn completions to autonomously dispatch self-healing continuation directives without proxy text synthesis.🔗 solution: self-healing continuation | | Repetitive Tool Calling Loop | Problem: Upstream binary has no loop detector and will execute cyclic or identical tool calls indefinitely, burning thousands of tokens and freezing sessions.🔗 problem: repetitive tool loop | Tracks tool signatures and resource paths per turn using suffix cycle matching, sending session/cancel upstream, auto-completing tools, and steering the model to proceed e2e without polluting chat.🔗 solution: loop circuit breaker |

Setup

Automatic Configuration (Recommended)

Run the one-line setup command to install and configure both Paseo and Zed:

pnpm add -g @simonepri/refined-antigravity-acp && refined-antigravity-acp setup

[!NOTE] Google Terms of Service: The setup command checks if Google's official agy_acp_server binary is installed. If missing, it displays a link to the Google Antigravity Terms of Service and prompts you to accept them before downloading the binary from Google's CDN (dl.google.com). For non-interactive setups or CI, pass -y (or --yes) to accept automatically: refined-antigravity-acp setup --yes.

To configure a specific editor only:

refined-antigravity-acp setup paseo   # Configures ~/.paseo/config.json & restarts daemon
refined-antigravity-acp setup zed     # Configures Zed settings.json

The setup command resolves your active Node runtime (process.execPath) and global CLI path automatically, handles Zed JSONC comments safely, and restarts the Paseo daemon.

Manual Configuration

Install globally:

pnpm add -g @simonepri/refined-antigravity-acp

Locate installed binary paths:

which node
which refined-antigravity-acp
which pnpm

[!TIP] The wrapper downloads agy_acp_server.par if not already installed locally.

1. Paseo (ACP Agent Provider)

Register the wrapper in ~/.paseo/config.json under agents.providers:

Global Binary (Recommended)

{
  "agents": {
    "providers": {
      "refined-antigravity-acp": {
        "extends": "acp",
        "label": "Antigravity",
        "command": ["<node-path>", "<refined-antigravity-acp-path>"],
        "enabled": true
      }
    }
  }
}

[!NOTE] The Paseo daemon runs outside the login shell environment. Providing absolute paths from which node and which refined-antigravity-acp prevents env: node: No such file or directory errors.

Zero-Install (pnpm dlx)

{
  "agents": {
    "providers": {
      "refined-antigravity-acp": {
        "extends": "acp",
        "label": "Antigravity",
        "command": ["<pnpm-path>", "dlx", "@simonepri/refined-antigravity-acp"],
        "enabled": true
      }
    }
  }
}

Restart the Paseo daemon after modifying config.json:

paseo daemon restart

2. Zed Editor (ACP Agent)

Add refined-antigravity-acp to your Zed settings.json under agent.profiles:

Global Binary (Recommended)

{
  "agent": {
    "profiles": {
      "antigravity": {
        "type": "acp",
        "command": "<node-path>",
        "args": ["<refined-antigravity-acp-path>"]
      }
    }
  }
}

[!NOTE] Zed launches external agent processes without inheriting shell version manager PATH variables. Explicit paths from which node and which refined-antigravity-acp ensure reliable execution.

Zero-Install (pnpm dlx)

{
  "agent": {
    "profiles": {
      "antigravity": {
        "type": "acp",
        "command": "<pnpm-path>",
        "args": ["dlx", "@simonepri/refined-antigravity-acp"]
      }
    }
  }
}

3. Standalone CLI and Other ACP Editors

Run directly from any terminal or editor speaking standard ACP over stdio:

refined-antigravity-acp

Zero-install alternative: pnpm dlx @simonepri/refined-antigravity-acp.

Authentication

Google's ACP server handles authentication directly. On initialization, the server advertises standard ACP authMethods (Google OAuth, Gemini Enterprise, Gemini API keys, or Agent Platform).

For OAuth logins, the server runs a local browser login flow and saves credentials to the operating system keychain. The CLI requires no manual authentication step.

Configuration & Environment Variables

| Variable | Default | Description | | :--------------------------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REFINED_AGY_OFFICIAL_ACP_VERSION | 1.2.1 | Version of the official upstream Google Antigravity ACP binary (agy_acp_server.par) to download if not installed locally. (Falls back to REFINED_AGY_VERSION if set). | | REFINED_AGY_ACP_BIN | Auto-detected | Custom path to an agy_acp_server.par binary. | | REFINED_AGY_RECYCLE_TIMEOUT_MS | 10000 | Timeout (in ms) when respawning and resyncing a replacement process after an upstream Antigravity crash or deadlock (e.g. subagent channel panic). Caps how long internal initialization, session loading, and mode restoration requests can take before retrying. | | REFINED_AGY_TRACE | 0 | Set to 1 to trace inbound/outbound ACP JSON-RPC message ids to stderr and restore the full upstream debug log (normally filtered). | | REFINED_AGY_DATA_DIR | ~/.refined-antigravity | Base directory for the MCP proxy's remembered-port configuration. |

Protocol Coverage

Refined Antigravity ACP implements the Agent Client Protocol (ACP) specification across two layers:

• Direct Passthrough: Requests and notifications requiring no modification pass through unchanged: client filesystem operations (fs/*), terminals (terminal/*), authentication (authenticate, logout), permission requests (session/request_permission), and MCP bridge channels.
• Hardening and Telemetry: The wrapper intercepts session methods to prevent deadlocks, repair database state, and synthesize missing ACP notifications (usage_update token metrics and plan subagent tracking).

[!NOTE] All synthesized and modified messages are verified against the canonical ACP JSON Schema (Draft 2020-12) and type-checked against @agentclientprotocol/sdk in src/core/acp-conformance.test.ts.

Development

pnpm install
pnpm run check       # runs format:check, lint, typecheck, and dead-code
pnpm run test        # fast, hermetic unit tests (no auth required)
pnpm run test:e2e    # end-to-end integration tests (requires local agy login)

Contributing

Every fix pull request must follow this structure:

1. Reproduction First (E2E): Before writing any fix or changing code, you must first reproduce the issue with an end-to-end test in src/fixes/<bug-name>/index.e2e.test.ts. The test must fail against the raw upstream binary (spawnRawAgy()) labeled with problem: <description>.
2. Deterministic Over System Prompts: Prefer programmatic stream transformation, message adaptation, or process supervision over prompt injection. Keep injected system prompts to the absolute minimum necessary; if an issue can be solved deterministically in code without adding or modifying system prompts, that is always preferred.
3. Directory: Place the fix in src/fixes/<bug-name>/, named after the bug (for example, dangling-tool-calls). Do not prefix with issue numbers.
4. Header: Add a JSDoc block with Problem: and Solution: sections at the top of src/fixes/<bug-name>/index.ts.
5. Tests: Include both an upstream reproduction (problem: <description>) and a fix verification (solution: <description>) in src/fixes/<bug-name>/index.e2e.test.ts (tested against spawnRawAgy() vs spawnWrapped()), alongside fast hermetic unit tests in src/fixes/<bug-name>/index.test.ts.
6. Exports: Export the fix from src/fixes/index.ts and register it in src/index.ts.
7. Documentation: Add a row to the table in readme.md linking the fix and tests.
8. Verification: Run quality checks before submitting:

   pnpm run check && pnpm run build && pnpm test

Terms of Service Notice

Google's Antigravity Additional Terms of Service restrict using the Service in connection with unauthorized third-party software.

Refined Antigravity ACP operates as a local proxy between ACP clients (Paseo, Zed) and Google's official agy_acp_server binary:

• What it does: It supervises the local child process to recover from upstream deadlocks and crashes, repairs orphaned SQLite checkpoints, sanitizes streaming Markdown and diagrams, and injects workspace context and slash skills.
• What it does not do: It does not make direct calls to Google cloud APIs, does not touch, store, or extract OAuth credentials or API keys, and does not bypass server-side quotas or rate limits.

As with any third-party editor integration for official binaries, please review Google's Terms of Service to ensure your use complies with the policies applicable to your account.

Disclaimer

This is an independent open-source project and is not affiliated with, authorized, or endorsed by Google LLC. "Antigravity", "Gemini", and Google are trademarks of Google LLC.

License

MIT © Simone Primarosa