Antigravity CLI (agy) Operator Guide for Hermes Agent

The Antigravity CLI (agy) is a coding-agent backend you invoke through the Hermes Agent terminal tool. You would reach for it when you need a Gemini-family cross-check on a plan or diff, want to run a non-interactive code review, or prefer Antigravity's plugin and sandbox model over alternatives like codex or claude-code. This guide covers everything from installation verification to advanced delegation patterns, all without wrapping a network API.

What it does

agy gives you two distinct layers of control. The shell wrapper commands (agy help, agy install, agy plugin, agy update, agy changelog) let you manage the binary and its plugins from the Hermes terminal. Inside a running TUI session, slash commands (/config, /permissions, /skills, /agents) handle interactive configuration and conversation control. Keep these layers separate: agy help shows only the wrapper surface, not the in-session commands.

You can use agy for one-shot prompts with --print, interactive multi-turn sessions with a PTY, or backgrounded long runs for tests and multi-file changes. It manages its own authentication through the OS keyring or browser sign-in, so no environment variables or API keys are required from Hermes.

Before you start

• The agy binary must be on PATH. Verify through the terminal tool:

terminal(command="command -v agy && agy --version")

• No env vars or API keys required by this skill. Antigravity manages its own auth via the OS keyring or browser sign-in (see Authentication below).
• All agy commands run through the terminal tool. Do not use cat to inspect Antigravity's files; use read_file on the paths under Core paths.
• The skill is reference + procedure, not a network API wrapper. There is nothing to authenticate from Hermes itself.

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.

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. It is 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//

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 , uninstall , enable , disable , validate [path], link , help

Install flags (agy install --help)

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

In-session slash commands

• Conversation control: /resume (/switch), /rewind (/undo), /rename , /clear, /fork, /reset, /new
• Settings & tools: /config, /settings, /permissions, /model, /keybindings, /statusline, /tasks, /skills, /mcp, /open , /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//.
• 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.

When not to use it

Do not use agy as a coordination layer or first-class orchestration primitive. It is a worker execution backend or third-opinion reviewer. If you need a JSON result envelope or --max-turns bounding, claude-code may be a better fit. For tasks that require a different model family or plugin ecosystem, consider codex or direct tool use instead.

Limits and gotchas

• agy -p returns plain text only. No --output-format json, no result envelope with session_id / cost / turn count.
• There is no --max-turns. Bounding is via --print-timeout (default 5m).
• On WSL, token storage is file-based, so auth issues are local-file / session-state problems, not browser-only problems.
• Workspace identity can depend on launch directory and the .antigravitycli project marker.
• agy --version is safe and non-interactive; agy version is interactive and can fail without a real TTY.

Related skills

This skill pairs with grok, codex, claude-code, and hermes-agent for multi-agent workflows and cross-model verification. See the respective skill guides for PTY patterns, worktree fan-out, and result collection.