Pi Antigravity ACP Subagent

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

The package is designed for unattended workflows. There are no browser clicks or user prompts in the middle of a task: when a sensitive operation needs a decision, Pi receives a structured permission request and decides according to its own policy.

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
Decide a pending sensitive operation	resolve_antigravity_permission
Validate installation and authentication	antigravity_doctor
Run a local end-to-end smoke test	antigravity_smoke_test

Headless permission flow

The flow is controlled by Pi from start to finish:

Pi -> ask_antigravity -> ACP
                         |
                         +-- ordinary operation -> execute
                         |
                         +-- sensitive operation -> pendingPermission
                                                       |
                                      Pi reviews the request and calls
                                      resolve_antigravity_permission

Important details:

• The user does not need to click an approval dialog.
• Normal development work can proceed automatically.
• Destructive, protected, or otherwise sensitive operations are independently gated by the extension.
• The approval mode is single-use (allow_once); approvals are not silently persisted as a blanket allow rule.
• A denial returns a structured result so Pi can adapt, retry safely, or report the blocker.

Safety and reliability

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

• Destructive operations have a per-task budget and a global budget.
• Protected paths and workspace-boundary violations are denied, including symlink escapes.
• Timeouts, inactivity detection, loop 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.
• Tasks are queued per workspace so concurrent agents do not collide in the same project.
• State is persisted under the workspace, allowing recovery after interruption.
• Checkpoints include untracked files, not just files already known to Git.
• 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.

This extension does not enable a --yolo or permission-bypass mode.

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 the workspace-specific Pi extension directory. Keep that directory available if you want resume and history to work across Pi sessions.

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 published package contains the extension source and this README; the official ACP runtime remains managed separately by Antigravity.

License

MIT