paseo-acp-agy

Agent Client Protocol (ACP) provider adapter connecting Google Antigravity (agy) to Paseo, Zed, and any ACP-compliant agent client over stdio.

Overview

paseo-acp-agy allows you to use Google Antigravity as a first-class agent provider inside Paseo. It implements the JSON-RPC Agent Client Protocol over standard input/output (stdio), dynamically exposing supported models, tracking session token usage, calculating real-time cost, displaying context window usage, and supporting slash commands.

Features

• Zero-Downtime Daemon Compatibility: Conforms to the Paseo Server & CLI specification. Updates to this adapter apply to future agent launches without restarting the Paseo daemon.
• Dynamic Model Catalog: Exposes Google Gemini (Flash, Pro) and Anthropic Claude models configured in your Antigravity CLI environment.
• Usage & Quota Telemetry: Real-time context window meters, prompt/output token tracking, pricing windows, and quota limit notifications.
• Session Management: Native support for session modes (Default / Plan mode), session cancellation, and resume.
• Slash Commands: In-session support for /help, /usage, and /resume.

Quick Start in Paseo

1. Configure Provider in Paseo

Add antigravity under agents.providers in your ~/.paseo/config.json:

{
  "agents": {
    "providers": {
      "antigravity": {
        "extends": "acp",
        "label": "Antigravity",
        "command": ["npx", "-y", "paseo-acp-agy", "--acp"],
        "enabled": true
      }
    }
  }
}

Local / Development Setup: If you cloned this repository locally, you can compile and point directly to the binary:

"command": ["node", "/path/to/paseo-acp-agy/dist/index.js"]

Or install globally:

npm install -g paseo-acp-agy

And configure "command": ["paseo-acp-agy"].

2. Reload Paseo Configuration

Apply changes immediately without restarting the daemon:

paseo reload

3. Verify with Diagnostics

Run the official Paseo provider diagnostic command:

paseo provider diagnostic antigravity

List detected models:

paseo provider models antigravity

4. Run an Agent

Launch a task directly from your terminal:

paseo run --provider antigravity "Analyze the repository architecture"

Or select Antigravity from the provider dropdown in the Paseo Desktop App or Web UI (https://app.paseo.sh).

5. Official Paseo Catalog Entry

To include paseo-acp-agy in Paseo's built-in provider store (ACP_PROVIDER_CATALOG), see the Paseo Catalog Specification.

Plan Usage & Context Window Meter Setup

To display the Google Antigravity quota breakdown in Paseo's Settings -> Usage (Plan usage) and activate the real-time context-window meter ("bolinha") in the chat composer:

npx -y paseo-acp-agy setup

Or if installed globally:

paseo-acp-agy setup

Then restart your Paseo app or daemon:

paseo daemon restart

Note: paseo-acp-agy also checks and auto-configures your local Paseo server automatically whenever it launches via --acp. Running setup manually ensures your existing daemon instance picks up the telemetry hooks immediately upon restart.

Requirements

• Node.js: >= 20.0.0 (Node.js 22 recommended)
• Google Antigravity CLI (agy): Installed and authenticated in your PATH (or specified via AGY_BIN_PATH).
• Paseo: Paseo CLI / Daemon (@getpaseo/cli) >= 0.7.0.

Security, Permissions & Antigravity CLI Limitations

In the Agent Client Protocol (ACP) specification, the host client (e.g., Paseo or Zed) acts as the security supervisor. Native ACP agents query the host via session/request_permission before executing tools (read_file, write_file, terminal commands).

Why --dangerously-skip-permissions is enabled by default

The official Google Antigravity CLI (agy) communicates with this adapter via --input-format stream-json --output-format stream-json:

1. No Interactive TTY: agy runs headlessly over piped JSON-RPC stdio. In this mode, agy's internal terminal prompt (Allow <tool>? [y/n]) cannot reach an interactive user.
2. Headless Permission Denials: Without --dangerously-skip-permissions, whenever agy accesses a workspace folder or runs a tool that has not been explicitly pre-approved in ~/.gemini/antigravity-cli/settings.json, its internal check fails and aborts immediately with:

   permission check failed for read_file: user denied permission for read_file(...)

3. No External Permission Callback: Unlike native ACP agents or Claude's Agent SDK, agy's stream-json interface does not support an external pause-and-confirm handshake. Once a tool step starts in agy, it has already been scheduled internally.

To prevent unrecoverable user denied permission errors on fresh workspaces (especially on new Windows or Linux installations), paseo-acp-agy:

• Passes --dangerously-skip-permissions by default so tool authorization is delegated to the host application.
• Passes --add-dir <cwd> on process startup to demarcate the current project workspace directory.
• Streams tool invocations (step_update → tool_call) in real time to the Paseo UI so the user retains full visibility over all actions.

Controlling Permissions & Sandbox Mode

You can adjust this behavior using environment variables in your Paseo configuration or shell:

| Variable | Description | Default | | :--- | :--- | :--- | | AGY_ACP_DANGEROUSLY_SKIP_PERMISSIONS | Set to false or 0 to disable automatic skip and strictly require pre-approved permissions in ~/.gemini/antigravity-cli/settings.json | true | | AGY_ACP_SANDBOX | Set to true or 1 to launch agy with terminal restrictions enabled (--sandbox) | false |

Environment Variables

| Variable | Description | Default | | :--- | :--- | :--- | | AGY_BIN_PATH | Path to the Google Antigravity binary | Auto-detected from PATH or ~/.local/bin/agy | | AGY_ACP_DANGEROUSLY_SKIP_PERMISSIONS | Auto-approve tool permissions in headless agy | true | | AGY_ACP_SANDBOX | Enable terminal sandbox mode (--sandbox) | false | | AGY_ACP_LOG_FILE | Enable debug file logging | Disabled |

Development

# Clone repository
git clone https://github.com/tucomel/paseo-acp-agy.git
cd paseo-acp-agy

# Install dependencies
npm install

# Typecheck
npm run typecheck

# Run test suite (56+ unit & protocol tests)
npm test

# Build distribution
npm run build

# Test ACP initialization via stdio
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}\n' | node dist/index.js

License

MIT © Arthur Melo