antigravity-cli

1---2name: antigravity-cli3description: "Operate the Antigravity CLI (agy): plugins, auth, sandbox."4version: 0.2.05author: Tony Simons (asimons81), Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [Coding-Agent, Antigravity, CLI, Auth, Plugins, Sandbox]11    related_skills: [grok, codex, claude-code, hermes-agent]12---13 14# Antigravity CLI (`agy`)15 16Operator guide for the Antigravity CLI, invoked as `agy`. Run all `agy`17commands through the Hermes `terminal` tool; inspect its config and logs with18`read_file`. This skill is reference + procedure — it does not wrap a network19API, so there is nothing to authenticate from Hermes itself.20 21## When to Use22 23- Installing, updating, or smoke-testing the `agy` binary24- Driving non-interactive `agy --print` / `agy -p` one-shots25- Debugging Antigravity auth, sandbox, permissions, or plugin state26- Reading Antigravity settings, keybindings, conversations, or logs27 28## Mental model29 30Antigravity has two layers — keep them distinct or the guidance will be wrong:31 321. **Shell wrapper commands** — `agy help`, `agy install`, `agy plugin`,33   `agy update`, `agy changelog`. Run these through the `terminal` tool.342. **Interactive in-session slash commands** — `/config`, `/permissions`,35   `/skills`, `/agents`, etc. These only exist inside a running `agy` TUI36   session, not on the shell wrapper.37 38`agy help` shows the shell wrapper surface, NOT the in-session slash commands.39 40## Prerequisites41 42- The `agy` binary on PATH. Verify through the `terminal` tool:43  `command -v agy && agy --version`.44- No env vars or API keys required by this skill — Antigravity manages its own45  auth via the OS keyring / browser sign-in (see Authentication below).46 47## How to Run48 49Invoke every `agy` command through the `terminal` tool. Examples:50 51```52terminal(command="agy --version")53terminal(command="agy help")54terminal(command="agy plugin list")55terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")56```57 58For an interactive multi-turn TUI session, launch `agy` with `pty=true` (and59tmux for capture/monitoring), the same pattern the `codex` / `claude-code`60skills use. For one-shot smoke tests and scripted prompts, prefer61`agy --print` (non-interactive).62 63To inspect Antigravity's own files, use `read_file` on the paths under Core64paths below — do not `cat` them through the terminal.65 66## Delegation patterns67 68`agy` is a coding-agent backend in the same family as `codex` / `claude-code`,69so the same delegation shapes apply. Use these when handing real work (features,70fixes, reviews, second opinions) to Antigravity rather than just smoke-testing.71 72### One-shot (preferred for scripted prompts and second opinions)73 74```75terminal(command="agy -p 'Review this diff for bugs and security issues' --model 'Gemini 3.1 Pro (High)'", workdir="/path/to/repo", timeout=300)76```77 78`-p` is non-interactive: it runs the prompt and exits. Pick the engine with79`--model` (run `agy models` for the exact display strings, e.g.80`'Gemini 3.1 Pro (High)'`, `'Claude Opus 4.6 (Thinking)'`). Add extra context81roots with repeatable `--add-dir`.82 83### Long / bounded runs (tests, builds, multi-file changes)84 85Background it and get notified on completion, the same as the `codex` skill:86 87```88terminal(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)89# then: process(action="poll"/"log"/"wait", session_id=<id>)90```91 92### Interactive multi-turn (PTY + tmux)93 94For a conversational session, launch `agy -i` (or bare `agy`) under `pty=true`95with tmux for `capture-pane` / `send-keys`, exactly the pattern documented in96the `codex` / `claude-code` skills. Resume later with `--continue` / `-c` or a97specific `--conversation <id>`.98 99### Parallel instances (batch sub-issue / worktree fan-out)100 101Create one git worktree per task and launch an independent `agy -p` in each102(background), then collect results — same worktree fan-out the `codex` skill103uses for batch issue fixing. Bound concurrency to what the machine and your104review capacity can absorb.105 106### Output + bounding caveat (differs from Claude Code)107 108- `agy -p` returns **plain text** — there is **no `--output-format json`** and109  no result envelope with `session_id` / cost / turn count. Parse stdout110  directly; don't expect a JSON object.111- There is **no `--max-turns`**. A print run is bounded by **`--print-timeout`**112  (default `5m`). Raise it for long tasks: `--print-timeout 20m`. Pair with the113  `terminal` `timeout=` so the outer call doesn't cut the run short.114 115### Orchestration boundary116 117Antigravity is a **worker execution backend or third-opinion reviewer** — an118execution detail owned by the agent/profile running a task, NOT a first-class119orchestration primitive. Do not put `agy` on a kanban board as its own card or120treat it as a coordination layer; route work through the normal task graph and121let the assigned worker choose `agy` (vs. codex/claude-code/direct tools) as its122method. Reach for it explicitly only when the user asks, when a worker is123configured to wrap it, or when you want a Gemini-family cross-check against124another agent's plan or diff.125 126## Core paths127 128- Binary / entrypoint: `agy`129- App data dir: `~/.gemini/antigravity-cli/`130- Settings file: `~/.gemini/antigravity-cli/settings.json`131- Keybindings file: `~/.gemini/antigravity-cli/keybindings.json`132- Logs: `~/.gemini/antigravity-cli/log/cli-*.log`133- Conversations: `~/.gemini/antigravity-cli/conversations/`134- Brain artifacts: `~/.gemini/antigravity-cli/brain/`135- History: `~/.gemini/antigravity-cli/history.jsonl`136- Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`137 138## Quick Reference139 140### Wrapper commands141- `agy changelog`142- `agy help`143- `agy install`144- `agy plugin` / `agy plugins`145- `agy update`146 147### Useful flags148- `--add-dir`149- `--continue` / `-c`150- `--conversation`151- `--dangerously-skip-permissions`152- `--print` / `-p`153- `--print-timeout`154- `--prompt`155- `--prompt-interactive` / `-i`156- `--sandbox`157- `--log-file`158- `--version`159 160### Plugin subcommands (`agy plugin --help`)161- `list`, `import [source]`, `install <target>`, `uninstall <name>`,162  `enable <name>`, `disable <name>`, `validate [path]`, `link <mp> <target>`,163  `help`164 165### Install flags (`agy install --help`)166- `--dir`, `--skip-aliases`, `--skip-path`167 168### In-session slash commands169- **Conversation control:** `/resume` (`/switch`), `/rewind` (`/undo`),170  `/rename <name>`, `/clear`, `/fork`, `/reset`, `/new`171- **Settings & tools:** `/config`, `/settings`, `/permissions`, `/model`,172  `/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`,173  `/usage`, `/logout`, `/agents`174- **Prompt helpers:** `@` path autocomplete, `esc esc` clears the prompt (when175  not streaming), `!` runs a terminal command directly, `?` opens help176 177## Settings and permissions178 179### Common settings keys (`settings.json`)180- `allowNonWorkspaceAccess`181- `colorScheme`182- `permissions.allow`183- `trustedWorkspaces`184 185### Permission modes186`request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`.187 188### Sandbox behavior189- `enableTerminalSandbox` is a boolean in `settings.json`; default `false`.190- Launch-time overrides (`--sandbox`, `--dangerously-skip-permissions`) can191  supersede persistent settings for the current session.192 193## Authentication behavior194 195- The CLI tries the OS secure keyring first.196- With no saved session, it falls back to browser-based Google sign-in.197- Locally it opens the default browser; over SSH it prints an authorization URL198  and expects the auth code pasted back.199- `/logout` removes saved credentials.200 201## Plugins202 203- Plugins stage under `~/.gemini/antigravity-cli/plugins/<plugin_name>/`.204- They can bundle skills, agents, rules, MCP servers, and hooks.205- `agy plugin list` returning no imported plugins is a valid empty state.206 207## Pitfalls208 209- `agy help` shows wrapper commands, not interactive slash commands.210- `agy --version` is the safe non-interactive version check; `agy version` is211  interactive and can fail without a real TTY.212- First place to look for failures: `~/.gemini/antigravity-cli/log/cli-*.log`213  (read with `read_file`).214- Don't confuse persistent JSON settings with launch-time overrides.215- `~/.gemini/antigravity-cli/bin/agentapi` is a thin wrapper to `agy agentapi`.216- On WSL, token storage is file-based, so auth issues are usually local-file /217  session-state problems, not browser-only problems.218- Workspace identity can depend on launch directory and the `.antigravitycli`219  project marker.220- `agy -p` prints plain text only — no `--output-format json`, no result221  envelope. Don't try to parse a JSON object out of it (unlike `claude-code`).222- Bound print runs with `--print-timeout` (default `5m`), not `--max-turns`223  (which does not exist on `agy`).224 225## Verification226 227Confirm the install is real and usable, all through the `terminal` tool (read228files with `read_file`):229 2301. `terminal(command="command -v agy")`2312. `terminal(command="agy --version")`2323. `terminal(command="agy help")`2334. `terminal(command="agy plugin list")`2345. `read_file` on `~/.gemini/antigravity-cli/settings.json`2356. `read_file` on the latest `~/.gemini/antigravity-cli/log/cli-*.log`2367. If needed, `read_file` on `~/.gemini/antigravity-cli/keybindings.json`237 238## Support files239 240- `references/cli-docs.md` — condensed notes from the getting-started, usage,241  and features docs.242