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:
shpython <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:
shpython <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.
