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>/

Quick Reference

Wrapper commands

• agy changelog
• agy help
• agy install
• agy plugin / agy plugins
• agy update

Useful flags

• --add-dir
• --continue / -c
• --conversation
• --dangerously-skip-permissions
• --print / -p
• --print-timeout
• --prompt
• --prompt-interactive / -i
• --sandbox
• --log-file
• --version

Plugin subcommands (agy plugin --help)

• list, import [source], install <target>, uninstall <name>, enable <name>, disable <name>, validate [path], link <mp> <target>, help

Install flags (agy install --help)

• --dir, --skip-aliases, --skip-path

In-session slash commands

• Conversation control: /resume (/switch), /rewind (/undo), /rename <name>, /clear, /fork, /reset, /new
• Settings & tools: /config, /settings, /permissions, /model, /keybindings, /statusline, /tasks, /skills, /mcp, /open <path>, /usage, /logout, /agents
• Prompt helpers: @ path autocomplete, esc esc clears the prompt (when not streaming), ! runs a terminal command directly, ? opens help

Settings and permissions

Common settings keys (settings.json)

• allowNonWorkspaceAccess
• colorScheme
• permissions.allow
• trustedWorkspaces

Permission modes

request-review, always-proceed, strict, proceed-in-sandbox.

Sandbox behavior

• enableTerminalSandbox is a boolean in settings.json; default false.
• Launch-time overrides (--sandbox, --dangerously-skip-permissions) can supersede persistent settings for the current session.

Authentication behavior

• The CLI tries the OS secure keyring first.
• With no saved session, it falls back to browser-based Google sign-in.
• Locally it opens the default browser; over SSH it prints an authorization URL and expects the auth code pasted back.
• /logout removes saved credentials.

Plugins

• Plugins stage under ~/.gemini/antigravity-cli/plugins/<plugin_name>/.
• They can bundle skills, agents, rules, MCP servers, and hooks.
• agy plugin list returning no imported plugins is a valid empty state.

Pitfalls

• agy help shows wrapper commands, not interactive slash commands.
• agy --version is the safe non-interactive version check; agy version is interactive and can fail without a real TTY.
• First place to look for failures: ~/.gemini/antigravity-cli/log/cli-*.log (read with read_file).
• Don't confuse persistent JSON settings with launch-time overrides.
• ~/.gemini/antigravity-cli/bin/agentapi is a thin wrapper to agy agentapi.
• On WSL, token storage is file-based, so auth issues are usually local-file / session-state problems, not browser-only problems.
• Workspace identity can depend on launch directory and the .antigravitycli project marker.
• agy -p prints plain text only — no --output-format json, no result envelope. Don't try to parse a JSON object out of it (unlike claude-code).
• Bound print runs with --print-timeout (default 5m), not --max-turns (which does not exist on agy).

Verification

Confirm the install is real and usable, all through the terminal tool (read files with read_file):

1. terminal(command="command -v agy")
2. terminal(command="agy --version")
3. terminal(command="agy help")
4. terminal(command="agy plugin list")
5. read_file on ~/.gemini/antigravity-cli/settings.json
6. read_file on the latest ~/.gemini/antigravity-cli/log/cli-*.log
7. If needed, read_file on ~/.gemini/antigravity-cli/keybindings.json

Support files

• references/cli-docs.md — condensed notes from the getting-started, usage, and features docs.