Antigravity CLI

Antigravity CLI (agy)

Operator guide for the Antigravity CLI, invoked as agy. Run all agy commands through the Hermes terminal tool; inspect its config and logs with read_file. This skill is reference + procedure — it does not wrap a network API, so there is nothing to authenticate from Hermes itself.

When to Use

• Installing, updating, or smoke-testing the agy binary
• Driving non-interactive agy --print / agy -p one-shots
• Debugging Antigravity auth, sandbox, permissions, or plugin state
• Reading Antigravity settings, keybindings, conversations, or logs

Mental model

Antigravity has two layers — keep them distinct or the guidance will be wrong:

1. Shell wrapper commands — agy help, agy install, agy plugin, agy update, agy changelog. Run these through the terminal tool.
2. Interactive in-session slash commands — /config, /permissions, /skills, /agents, etc. These only exist inside a running agy TUI session, not on the shell wrapper.

agy help shows the shell wrapper surface, NOT the in-session slash commands.

Prerequisites

• The agy binary on PATH. Verify through the terminal tool: command -v agy && agy --version.
• No env vars or API keys required by this skill — Antigravity manages its own auth via the OS keyring / browser sign-in (see Authentication below).

How to Run

Invoke every agy command through the terminal tool. Examples:

terminal(command="agy --version")
terminal(command="agy help")
terminal(command="agy plugin list")
terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")

For an interactive multi-turn TUI session, launch agy with pty=true (and tmux for capture/monitoring), the same pattern the codex / claude-code skills use. For one-shot smoke tests and scripted prompts, prefer agy --print (non-interactive).

To inspect Antigravity's own files, use read_file on the paths under Core paths below — do not cat them through the terminal.

Delegation patterns

agy is a coding-agent backend in the same family as codex / claude-code, so the same delegation shapes apply. Use these when handing real work (features, fixes, reviews, second opinions) to Antigravity rather than just smoke-testing.

One-shot (preferred for scripted prompts and second opinions)

terminal(command="agy -p 'Review this diff for bugs and security issues' --model 'Gemini 3.1 Pro (High)'", workdir="/path/to/repo", timeout=300)

-p is non-interactive: it runs the prompt and exits. Pick the engine with --model (run agy models for the exact display strings, e.g. 'Gemini 3.1 Pro (High)', 'Claude Opus 4.6 (Thinking)'). Add extra context roots with repeatable --add-dir.

Long / bounded runs (tests, builds, multi-file changes)

Background it and get notified on completion, the same as the codex skill:

terminal(command="agy -p 'Implement the change described in TASK.md and run the tests' --dangerously-skip-permissions", workdir="/path/to/repo", background=true, notify_on_complete=true)
# then: process(action="poll"/"log"/"wait", session_id=<id>)

Interactive multi-turn (PTY + tmux)

For a conversational session, launch agy -i (or bare agy) under pty=true with tmux for capture-pane / send-keys, exactly the pattern documented in the codex / claude-code skills. Resume later with --continue / -c or a specific --conversation <id>.

Parallel instances (batch sub-issue / worktree fan-out)

Create one git worktree per task and launch an independent agy -p in each (background), then collect results — same worktree fan-out the codex skill uses for batch issue fixing. Bound concurrency to what the machine and your review capacity can absorb.

Output + bounding caveat (differs from Claude Code)

• agy -p returns plain text — there is no --output-format json and no result envelope with session_id / cost / turn count. Parse stdout directly; don't expect a JSON object.
• There is no --max-turns. A print run is bounded by --print-timeout (default 5m). Raise it for long tasks: --print-timeout 20m. Pair with the terminal timeout= so the outer call doesn't cut the run short.

Orchestration boundary

Antigravity is a worker execution backend or third-opinion reviewer — an execution detail owned by the agent/profile running a task, NOT a first-class orchestration primitive. Do not put agy on a kanban board as its own card or treat it as a coordination layer; route work through the normal task graph and let the assigned worker choose agy (vs. codex/claude-code/direct tools) as its method. Reach for it explicitly only when the user asks, when a worker is configured to wrap it, or when you want a Gemini-family cross-check against another agent's plan or diff.

Core paths

• Binary / entrypoint: agy
• App data dir: ~/.gemini/antigravity-cli/
• Settings file: ~/.gemini/antigravity-cli/settings.json
• Keybindings file: ~/.gemini/antigravity-cli/keybindings.json
• Logs: ~/.gemini/antigravity-cli/log/cli-*.log
• Conversations: ~/.gemini/antigravity-cli/conversations/
• Brain artifacts: ~/.gemini/antigravity-cli/brain/
• History: ~/.gemini/antigravity-cli/history.jsonl
• Plugin staging: ~/.gemini/antigravity-cli/plugins/<plugin_name>/