Antigravity CLI

Use the installed agy CLI as an external coding agent. The bundled client returns a task ID immediately and keeps a background worker available for follow-ups. It runs each turn with official streaming JSON input/output and resumes the exact Antigravity conversation on the next turn. Waiting for the process and stderr to finish makes permission denials and partial-output timeouts visible; each follow-up incurs CLI startup time.

Delegate when the user requests Antigravity or another agent can add value that you can verify. Keep routine work with the supervising agent when the extra startup and review time would outweigh that benefit.

Antigravity CLI must already be installed and authenticated. Run scripts/agy.py with the project's Python 3.12+ interpreter. The helper uses only the standard library; when the project has no Python environment, uv run --python 3.12 <script> ... also works. Resolve the script relative to this skill, not the project receiving the task.

Assign and follow up

Provide the goal, absolute working directory, relevant files and evidence, scope, and completion check. Antigravity does not inherit the supervising agent's conversation. Use a UTF-8 prompt file for substantial instructions:

python <script> start --cwd <absolute-project-path> --prompt-file <task-file>
python <script> wait <task_id> --timeout 30
python <script> status <task_id>
python <script> reply <task_id> --prompt-file <follow-up-file>
python <script> cancel <task_id>
python <script> close <task_id>

Keep independent work with the supervising agent while the task runs. wait timing out only returns a snapshot; it does not cancel the task. reply is accepted after the current turn finishes. Retain the task_id and close the worker when no more follow-ups are needed.

The helper supplies both the process working directory and --add-dir. For concurrent edits to overlapping files, use separate worktrees and pass their paths as --cwd; the helper does not create worktrees. Check actual output paths, since Antigravity can also write to its conversation artifacts.

Configuration and permissions

Inherit Antigravity's authentication, model, and permission configuration. Subscription and API authentication remain Antigravity's responsibility. Do not switch providers, change authentication, or rewrite its global settings to conceal a failure.

start --model, --effort, --mode, and --sandbox are task-specific overrides. Honor the user's model or effort choice. Otherwise choose effort according to complexity, error cost, and ease of verification; omit the override when the model's support or the appropriate choice is uncertain. Discover models with agy --output-format json models.

Match permissions to the authorized work. --mode plan is a planning instruction, not enforced read-only access: headless plan review can proceed automatically. The supervising agent's sandbox does not configure AGY's. Do not promise isolation without checking the target platform's support.

For authorized workspace edits, --mode accept-edits allows file changes without interactive diff review; shell commands still follow tool permission rules. If a file tool rejects the target as an invalid artifact path, ask Antigravity to write a regular workspace file instead of an artifact. Inspect that tool error before attempting a shell workaround or expanding permissions.

Headless AGY cannot accept programmatic approval responses. When the helper reports blocked, inspect denied_actions and the partial result. If the task requires those tools, use scoped Antigravity permission rules or an interactive AGY session to establish the required permissions, following the original authorization. Do not repeatedly submit a blocked operation with unchanged permissions. The helper exposes --dangerously-skip-permissions only as an explicit override; do not use it merely to avoid an approval. Scoped rules limit which actions match; they are stored in Antigravity's global settings, not as temporary grants managed by this helper.

Check results and recover

Read status, closed, stop_reason, error, denied_actions, and tool_errors together. completed means the turn returned a response, not that its claims or edits were verified. Inspect the diff, output files, and relevant checks. AGY may recover from an individual tool error, so tool errors remain visible even when the final turn completes.

The helper does not equate native SUCCESS or exit code 0 with completion. It checks permission denials and stderr timeout diagnostics, and enforces its own startup, turn, and shutdown deadlines.

cancel stops that task's AGY process tree and closes its worker. It does not undo edits or external actions already performed. Read partial results before retrying. To continue a closed conversation, explicitly start a new task with its returned session_id:

python <script> start --cwd <same-project-path> --conversation <session_id> --prompt-file <follow-up-file>

An open task can use reply after a provider failure. This is an explicit new turn in the same conversation; there is no automatic retry. If startup failed before a session ID was obtained, resolve the error and start again.

If installation, authentication, network, permissions, or execution blocks the task, tell the user what failed and what remains incomplete. Do not silently replace the requested Antigravity contribution with your own work or another provider. Committing, publishing, and other external actions retain the authorization boundaries of the original assignment.

Use <script> --help for commands and references/client.md for state fields, timeouts, storage, and diagnostics.