Pi Antigravity ACP Subagent

Headless Google Antigravity delegation for Pi: send implementation work to an autonomous coding agent while Pi keeps control of limits, recovery, and review.

The package is designed for unattended workflows. Antigravity runs with --approval-mode=yolo and permission requests are handled automatically without waiting for Pi.

Install

pi install npm:pi-antigravity-acp-subagent

Or install it from a local checkout:

pi install C:\path\to\antigravity-acp-subagent

Requirements:

• Node.js 22 or newer.
• Google Antigravity available and authenticated on the machine.
• Network access the first time the official Antigravity ACP server is downloaded.

The package does not bundle the large ACP runtime. It downloads Google's official runtime on first use and reuses it afterwards.

Quick start

Once installed, ask Pi to delegate an implementation task:

ask_antigravity({
  task: "Implement the missing retry handling and add focused tests.",
  cwd: "C:\\projects\\my-app",
  timeoutMinutes: 30
})

The returned task record includes status, result, changed files, checkpoints, review information, permission events, and network activity. Pi can resume or inspect the task without asking the user to manage a second terminal.

What this extension provides

Capability	Pi tool
Start an autonomous implementation task	ask_antigravity
Continue an interrupted task	resume_antigravity
Run one controlled repair pass after a failed review	repair_antigravity_task
Wait for an active or queued task	await_antigravity_task
Validate installation and authentication	antigravity_doctor
Run a local end-to-end smoke test	antigravity_smoke_test

Execution mode

Antigravity is started in YOLO mode:

Pi -> ask_antigravity -> ACP (`--approval-mode=yolo`)
                         |
                         +-- any tool operation -> execute automatically

Important details:

• The user does not need to click an approval dialog for ordinary operations.
• Normal development work can proceed automatically.
• The extension still enforces execution timeouts, inactivity limits, output limits, and process cleanup.

Safety and reliability

The extension is intentionally autonomous, but it is not unrestricted:

• Timeouts, inactivity detection, output limits, and resource limits stop unhealthy runs.
• The complete child-process tree is cleaned up when a task finishes, fails, is cancelled, or times out.
• On macOS and Linux, ACP runs in its own process group so helper processes are terminated with the task as well.
• Tasks are queued per workspace so concurrent agents do not collide in the same project.
• State is persisted outside the installed package at ~/.pi/agent/antigravity-acp-subagent, allowing recovery across package updates. Existing state from older releases is migrated automatically.
• Checkpoints include untracked files, not just files already known to Git.
• Old task records and checkpoints are pruned automatically after the retention limit or storage budget is reached.
• Sensitive values are redacted from persisted diagnostics when possible.
• Network intent is recorded for commands such as curl, wget, package publishing/installing, remote Git, Docker registry, SSH, and SCP.
• ACP tool calls are attributed to files when the server provides a tool-call identifier.
• A failed task can receive at most one controlled repair pass; repeated autonomous retry loops are not allowed.
• The agent must finish with a structured final report instead of keeping the process alive and rereading forever.

The ACP child process is launched with --approval-mode=yolo; permission requests are auto-approved and never routed to Pi.

Useful commands

/antigravity                         Show extension help
/antigravity doctor                  Check runtime, auth, and installation
/antigravity smoke                   Run the local ACP smoke test
/antigravity tasks                   List persisted tasks
/antigravity queue                   Show queued and active work
/antigravity logs                    Show recent task events
/antigravity history                 Show completed task history
/antigravity processes               Find leftover ACP processes
/antigravity review <taskId>         Show final quality review
/antigravity inspect <taskId>        Inspect task details and checkpoints
/antigravity cancel <taskId>         Cancel an active or queued task
/antigravity models                  List available Antigravity models
/antigravity model <name>            Set the preferred model
/antigravity reasoning <level>       Set reasoning effort

Recovery and diagnostics

Use antigravity_doctor or /antigravity doctor first when setup is unclear. For a task that was interrupted, use resume_antigravity with its task ID. For an active task, await_antigravity_task waits for completion without starting another agent. If the final review reports a narrowly fixable problem, repair_antigravity_task performs one bounded repair attempt.

The smoke test uses a local fake ACP server and does not require a real coding task. It is useful after installation or an upgrade:

antigravity_smoke_test({ "keepArtifacts": false })

Configuration notes

The extension stores its task state, event log, checkpoints, and audit details in ~/.pi/agent/antigravity-acp-subagent. Set PI_ANTIGRAVITY_DATA_DIR when a different durable location is required. Keep that directory available if you want resume and history to work across Pi sessions.

antigravity_doctor also checks the current platform/architecture target, the archive extractor, write access to the data directory, the ACP executable permission, authentication, and model discovery.

The package deliberately does not add an OS-level sandbox. Its protection comes from Pi-controlled decisions, workspace/path guards, bounded execution, process cleanup, persistence, and audit data. If a stronger containment boundary is required, it must be provided by the host environment.

Development

npm install
npm run check
npm test

The repository CI runs syntax checks and tests on Windows, macOS, and Linux with Node.js 22 and 24.

The published package contains the extension source and this README; the official ACP runtime remains managed separately by Antigravity.

License

MIT