agy-cli

---
name: agy-cli
description: Run Google's Antigravity CLI (`agy`) — an agentic coding assistant powered by Gemini 3 (with Claude/GPT model access). Use when the user says "run/ask/use agy", "antigravity", wants a second-opinion audit from Gemini's agentic stack, or wants Claude to delegate a build/refactor task with the three effort tiers: default chat (fast), `/grill-me` (interactive planning), or `/goal` (autonomous long-running execution). Ships a heartbeat-guarded runner (`agy_run.sh`) so headless `/goal` runs never blind-hang — it watches the agy log and kills stalls in ≤3m instead of waiting out a 45m timeout — plus a session preflight (`agy_preflight.sh`) for updates, model report, and config repair. Knows the real REPL slash commands, the headless `-p` flag, conversation resume, sandboxing, plugins, and the on-disk state layout under `~/.gemini/antigravity-cli/`.
---

# Antigravity CLI (`agy`)

Google's agentic coding CLI. Runs Gemini 3 (Pro/Flash) by default, with internal access to Claude Sonnet/Opus 4.5/4.6 and GPT-OSS models. Pairs a chat REPL with planning, scheduling, and autonomous "goal" workflows that write `implementation_plan.md` + `task.md` to a per-conversation brain directory and emit project files into the workspace.

Use it when the user:
- says "run/ask/use agy" or "antigravity"
- wants a second opinion from Gemini's agentic loop (Claude is the primary, agy is the audit/delegate)
- wants Claude to delegate a multi-step build, refactor, or research task to a different model family
- specifically asks to compare effort tiers (default vs. `/grill-me` vs. `/goal`)

## Prerequisites

Already installed on this user's system at `/Users/george/.local/bin/agy`. For others:

```bash
agy changelog                  # version notes (no --version flag exists)
agy install                    # configure PATH + shell aliases (idempotent)
```

First-time login is interactive (OAuth via browser). State lives at `~/.gemini/antigravity-cli/`.

**Run the preflight once at the start of an agy delegation session** — it checks for/applies CLI updates (keeps you on the newest build), reports the active model, and repairs the empty `mcp_config.json` that otherwise errors on every startup:

```bash
.claude/skills/agy-cli/scripts/agy_preflight.sh --fix
```

Leave auto-update **on** for interactive use (the user wants the latest). Only set `AGY_CLI_DISABLE_AUTO_UPDATE=T` in throwaway CI where update pings are unwanted.

## The Three Effort Tiers (the key mental model)

This is what the user means by "difference between efforts." Same prompt, very different behavior:

| Tier | How to invoke | Latency | What it does |
|------|---------------|---------|--------------|
| **Default chat** | `agy -p "<prompt>"` or just type in REPL | seconds | One-shot answer or short tool-use loop. Outline-level depth. Best for Q&A, quick edits. |
| **`/grill-me`** | Type `/grill-me <idea>` in REPL | interactive | Interviews you to extract requirements, resolve design ambiguities, and align on a plan **before** writing code. Use when the idea is vague. |
| **`/goal`** | `/goal <objective>` in REPL or `agy -p "/goal <objective>"` | minutes → hour+ | Autonomous loop: drafts `implementation_plan.md`, writes a `task.md` checklist, spawns research subagents, creates project files, runs tests, iterates until done. Persists to `~/.gemini/antigravity-cli/brain/<convo-id>/`. |

**Verified timing on this machine** (plan a Pomodoro CLI in Python):
- plain `-p`: ~18s → returns a written outline
- `-p "/goal …"`: ~73s → creates `pyproject.toml`, `pomodoro/{config,database,timer,ui,cli}.py`, `tests/test_pomodoro.py`, runs the test suite, writes `task.md` + `walkthrough.md`

Rule of thumb: pick `/goal` only when you actually want files on disk and are OK waiting. Bump `--print-timeout` for headless `/goal` runs (default 5m is often not enough).

## Headless usage (the only safe mode for automation)

`agy` interactive mode requires a real TTY (`bubbletea: could not open TTY` if you try to pipe into it). For Claude-driven invocations always use `-p`.

```bash
# One-shot prompt, prints to stdout
agy -p "Refactor this function for readability: $(cat foo.py)"

# Bump timeout for /goal runs (default --print-timeout is 5m0s)
agy --print-timeout 30m -p "/goal Build a CLI Pomodoro tool in Python with SQLite history"

# Add extra workspace directories the agent may read/edit
agy --add-dir ./api --add-dir ./web -p "Audit cross-package type mismatches"

# Auto-approve every tool/permission prompt (DESTRUCTIVE — see safety)
agy --dangerously-skip-permissions -p "/goal Migrate db schema and update callers"

# Run inside the built-in restricted sandbox (safer auto-approval)
agy --sandbox --dangerously-skip-permissions -p "/goal Try three refactor approaches"

# Initial prompt then drop into interactive (won't work from Claude — no TTY)
agy -i "Start a fastify scaffold"
```

## No more 10-minute hangs: the heartbeat runner

**Why bare `agy -p` hangs.** `agy -p` buffers all output to the end (no streaming) and can stall silently: a tool that tries to escape the sandbox waits for a TTY approval that never comes headless, an SSE/network turn stalls, or quota throttles mid-run. With a bare call Claude then blind-waits up to `--print-timeout` — and the old advice was to set that to 20–45m. That is the 10-minute (or worse) dead wait. Verified on this machine: agy writes its `--log-file` every <4s while healthy, so *log silence is a reliable stall signal*.

**The fix — always run `/goal` and any multi-step task through the heartbeat runner**, `scripts/agy_run.sh`. It launches agy with a `--log-file`, watches that log for liveness, and exits the instant agy **finishes** OR the log goes **silent for `--stall` seconds** (default 180) — killing the whole process tree. A 10–45m blind wait becomes ≤3m stall detection. Launch it with `run_in_background: true` so the harness fires one completion notification.

```text
# RIGHT — heartbeat-guarded; one notification on done / stalled / timeout
Bash(command=".claude/skills/agy-cli/scripts/agy_run.sh \
      --label healthz --timeout 30m --add-dir \"$(pwd)\" --sandbox --skip-perms \
      \"/goal Add a /healthz route with a unit test\"",
     run_in_background=true)
# → on notification, read stdout: it prints an AGY_STATUS block. Then Read AGY_STDOUT.

# WRONG — bare call: buffers, can stall, blind-waits the full timeout
Bash(command="agy --print-timeout 45m -p \"/goal ...\"")
```

The runner prints a parseable status block and sets an exit code:

| exit | `AGY_STATUS` | meaning → action |
|------|-------------|------------------|
| 0 | `done` | agy exited cleanly. Read `AGY_STDOUT`; for `/goal`, read `AGY_BRAIN/walkthrough.md`. |
| 1 | `stalled` | log silent ≥`--stall`s, killed. See `AGY_HINT` (often: a sandbox-escape prompt → add `--skip-perms`, or an SSE/quota stall). Inspect `AGY_LOG` tail before retrying. |
| 2 | `timeout` | hit the `--timeout` ceiling while still active. Raise `--timeout` or narrow the task. |
| 4 | (any) + `AGY_ERROR_SIGNAL` | auth/quota/rate-limit found in stdout. **STOP, do not retry**, back off ≥60s. |
| 3 | `error` | bad args (e.g. missing prompt). |

It also surfaces `AGY_MODEL` (parsed from the log) so you can see which model actually ran.

Key flags: `--stall N` (silence threshold, default 180), `--timeout DUR` (hard ceiling, default 30m), `--add-dir`, `--sandbox`, `--skip-perms`, `--continue`, `--conversation U`, `--label NAME`. Run `agy_run.sh` with no prompt to see full usage.

Sizing `--timeout` (the hard ceiling; the heartbeat catches stalls long before this):

| Task shape | `--timeout` |
|------------|-------------|
| Q&A / short generation / 1–2 file review | omit the runner — a bare `agy -p` is fine (short, won't stall) |
| Multi-file audit, small refactor | `10m` |
| `/goal` for a feature in an existing codebase | `20m` |
| `/goal` from-scratch project or large migration | `45m`–`1h` |

Quick Q&A can still use a bare `agy -p "…"` (it returns in seconds and can't meaningfully stall). Reserve the runner for `/goal` and anything multi-step.

### Resuming conversations

agy persists every conversation as a `.pb` proto file in `~/.gemini/antigravity-cli/conversations/` and a matching brain dir at `~/.gemini/antigravity-cli/brain/<uuid>/`.

```bash
agy -c -p "Continue from where we left off"          # resume most recent
agy --conversation <uuid> -p "Add tests for X"        # resume a specific one
ls ~/.gemini/antigravity-cli/conversations/           # find UUIDs
```

## REPL slash commands (verified from changelog + live test)

These only work **inside the interactive REPL** (or as the first token of a `-p` prompt for `/goal`, `/grill-me`, `/schedule`):

| Command | Purpose |
|---------|---------|
| `/help` | Tabbed help: Commands + Shortcuts (sorted by keybinding) |
| `/goal <objective>` | Autonomous long-running build/refactor (see effort tiers above) |
| `/grill-me <idea>` | Interactive interview to align on a plan before coding |
| `/schedule <spec>` | One-shot timer or cron-style recurring background task |
| `/diff` | Interactive commit selection tree (supports 7- to 40-char git short hashes) |
| `/resume` | Pick a prior session to resume (use `ctrl+delete` to remove sessions) |
| `/usage` | Real-time quota + spending across models |
| `/quota` | Remaining quota for each model |
| `/config` | Open the in-app configuration UI |
| `/settings` | Theme + tool permission modes (`request-review`, `auto-approve`, `proceed-in-sandbox`) |
| `/statusline <help\|enable\|on\|disable\|off\|delete\|reset>` | Manage custom status line |

> Do **not** trust any other slash command list a model claims `agy` has — many are commonly hallucinated (e.g. `/model`, `/effort`, `/thinking`, `/agents`, `/keybindings`, `/export`, `/permissions`, `/switch`, `/rewind`, `/undo`). They are not in the changelog. If unsure, run `/help` interactively.

### Model selection ("always the newest model")

There is **no CLI flag** for model or reasoning effort (`--model`, `--effort`, `--reasoning`, `--thinking` all error with `flags provided but not defined`). The model is chosen in the REPL `/settings` (or `/config`) and **persists** across runs — it is not stored in a file you can safely hand-edit.

So the workflow for "always newest model":
1. Once, in the interactive REPL: `/settings` → pick the top tier (the Pro/Max Gemini 3.x, not Flash/Lite). It sticks for all later headless runs.
2. Every run, `agy_run.sh` prints `AGY_MODEL=` (and `agy_preflight.sh` reports it) by parsing the run log's `model_config_manager` line. If it shows a Flash/low tier on a hard task, tell the user to switch it in `/settings`.

On this machine the selected model is currently **`Gemini 3.5 Flash (Medium)`** — fast, but switch to the Pro tier for serious `/goal` work.

## Subcommands

```bash
agy changelog                # release notes (also the only way to see version)
agy update                   # in-place updater
agy install [--skip-aliases] [--skip-path] [--dir <path>]
agy plugin list
agy plugin import [gemini|claude]
agy plugin install <name[@marketplace]>
agy plugin uninstall <name>
agy plugin enable|disable <name>
agy plugin validate [path]
agy plugin link <marketplace> <target>
```

Plugins install into `~/.gemini/config/` (shared with Gemini CLI) since v1.0.2.

## Flag reference

| Flag | Description |
|------|-------------|
| `-p`, `--print`, `--prompt` | **Required for headless.** Run one prompt, print the response, exit |
| `-i`, `--prompt-interactive` | Run an initial prompt then continue interactively (needs TTY) |
| `-c`, `--continue` | Resume the most recent conversation |
| `--conversation <uuid>` | Resume a specific conversation by ID |
| `--add-dir <path>` | Add a directory to the workspace (repeatable) |
| `--sandbox` | Run with terminal sandbox restrictions enabled |
| `--dangerously-skip-permissions` | Auto-approve all tool permission requests |
| `--print-timeout <duration>` | Timeout for `-p` (default `5m0s`; bump for `/goal`) |
| `--log-file <path>` | Override CLI log file path |

## Environment variables

| Var | Effect |
|-----|--------|
| `AGY_CLI_HIDE_ACCOUNT_INFO=T` | Hide email + plan tier from header |
| `AGY_CLI_DISABLE_AUTO_UPDATE=F` | Disable nightly auto-update check |
| `AGY_BROWSER_WS_URL` / `AGY_BROWSER_ACTIVE_PORT_FILE` | Point browser-automation tool at a specific Chrome DevTools endpoint |

## On-disk layout (useful for debugging + recovery)

```
~/.gemini/antigravity-cli/
├── conversations/<uuid>.pb       # full chat history (protobuf)
├── brain/<uuid>/                 # per-conversation planning state
│   ├── implementation_plan.md    # written by /goal
│   ├── task.md                   # live checklist
│   └── walkthrough.md            # post-run summary
├── scratch/                      # default workspace when none specified
├── log/cli-YYYYMMDD_HHMMSS.log   # CLI logs (current also at cli.log symlink)
├── settings.json                 # theme + trustedWorkspaces
├── keybindings.json
├── history.jsonl                 # prompt history
└── installation_id
```

When a `/goal` run finishes, **read its `walkthrough.md` and `task.md`** from the matching brain dir to summarize what it actually did — the final stdout often only lists files.

## Critical gotchas

1. **No TTY = no REPL.** Anything other than `agy -p …` will fail with `bubbletea: could not open TTY` when invoked from Claude's Bash. Always use `-p`.
2. **Bare `agy -p` for `/goal` is the hang.** It buffers output to the end and can stall with no TTY to approve a sandbox-escape, leaving Claude to blind-wait the full `--print-timeout`. Route `/goal` and multi-step tasks through `scripts/agy_run.sh` (heartbeat watchdog) — see "No more 10-minute hangs" above. Default print timeout (5m) is also too short for builds; the runner defaults `--timeout` to 30m.
3. **`/help` in `-p` mode is just a prompt.** The model will hallucinate slash commands it doesn't have. The list above is the verified one.
4. **`--dangerously-skip-permissions` lets agy run any shell command and edit any file in the workspace without asking.** Pair with `--sandbox` and a narrowly scoped `--add-dir` when delegating from Claude.
5. **No `--model` / `--effort` flag exists.** Effort = which slash command you prefix. Model = `/settings` inside the REPL.
6. **Workspace defaults to `~/.gemini/antigravity-cli/scratch`** if not invoked from a trusted directory. Use `--add-dir $(pwd)` when running headless so the agent operates on your actual project.
7. **`agy` drops `.antigravitycli/` into the workspace root** the first time it's run there — a symlink folder pointing to `~/.gemini/config/projects/<uuid>.json`. Add `.antigravitycli/` to `.gitignore` (already done in this repo).
8. **Empty `~/.gemini/config/mcp_config.json` throws on every startup** (`unexpected end of JSON input`). Harmless but noisy. `agy_preflight.sh --fix` resets it to `{}` (with a backup).

## Staying under quota and not tripping abuse heuristics

Antigravity rides on a single OAuth session against Google's Gemini/Antigravity backend. Behaviour that looks bot-like or abusive can throttle or temporarily lock the account. Follow these rules whenever Claude is the one invoking `agy`:

**Concurrency**
- **Never run two `agy -p` processes in parallel.** They share the same OAuth quota and trigger rate-limit responses (and the abuse heuristics that follow them). Serialize calls — if Claude has three things to ask, send them as three sequential prompts or, better, one combined prompt.
- Use `-c` / `--conversation <uuid>` to extend an existing chat instead of spawning fresh sessions; fewer cold starts means fewer auth refreshes and fewer "new session" signals.

**Prompt shape**
- Be explicit about expected output length ("answer in ≤5 bullets", "code-only, no commentary"). `/goal` charges per tool-use turn — vague goals mean more turns.
- Reserve `/goal` for work that genuinely needs file-writing autonomy. Default-chat answers a code question for a fraction of the quota.
- Don't loop `/goal` calls without backoff. If a `/goal` failed, fix the prompt before re-running — don't re-fire it three times in a row.

**Monitoring**
- Before a big delegated run, the user can check headroom interactively with `/usage` and `/quota`. There is no headless equivalent today; if Claude sees `429`, `quota`, `rate limit`, or `RESOURCE_EXHAUSTED` in agy's output, **stop and report — do not retry**.
- On 429, back off at least 60s before any subsequent call, and prefer a smaller default-chat prompt to confirm the account is live before resuming `/goal` work.

**Environment**
- Keep auto-update **on** for interactive use (the user wants the newest build); run `agy_preflight.sh` once per session to apply updates. Only set `AGY_CLI_DISABLE_AUTO_UPDATE=T` in throwaway CI where update pings are unwanted.
- Set `AGY_CLI_HIDE_ACCOUNT_INFO=T` if streaming agy output anywhere shareable, to keep the user's email and plan tier out of logs.
- Do **not** wrap `agy` in retry-on-failure loops (`while ! agy …; do …; done`). Failed auth or quota errors must surface, not auto-retry.

**Sandboxing**
- `--dangerously-skip-permissions` without `--sandbox` is both a security risk **and** a quota risk — an unconstrained agent can spiral into long tool-use chains. Always pair the two for delegated `/goal` runs, plus a narrow `--add-dir`.

## Recommended invocation patterns

```bash
# Second-opinion code audit (read-only intent)
agy --add-dir "$(pwd)" -p "Audit src/auth/ for OWASP issues. Report only — do not modify files."

# Quick Q&A / one-shot generation
agy -p "Write a regex that matches RFC 5322 email addresses, with one-line explanation."

# Delegated build (autonomous, expect minutes) — via the heartbeat runner
.claude/skills/agy-cli/scripts/agy_run.sh --label healthz --timeout 30m \
    --add-dir "$(pwd)" --sandbox --skip-perms \
    "/goal Add a /healthz endpoint to the Fastify server in src/api with a unit test."
# Launch with run_in_background: true; on the notification, read the AGY_STATUS block.

# Interview-first design alignment (must be interactive — tell the user to run it themselves)
# In REPL: /grill-me Build a Slack bot that summarizes our standup channel daily

# Recurring background task (interactive only)
# In REPL: /schedule every weekday at 09:00 run "Summarize yesterday's git log and post to #eng"

# Resume the last conversation with new instructions
agy -c --add-dir "$(pwd)" -p "Now add error handling to the route we built"
```

## Best practices (quick checklist)

- Run `agy_preflight.sh --fix` once at session start (updates + model report + config repair).
- Bare `agy -p "…"` is fine for quick Q&A. For `/goal` and any multi-step task use `scripts/agy_run.sh` (heartbeat watchdog) with `run_in_background: true` — never bare `agy -p "/goal …"` (that's the hang).
- `--stall` (default 180s) catches hangs in ≤3m; `--timeout` is just the hard ceiling. On `AGY_STATUS=stalled`, read `AGY_HINT` before retrying.
- `/grill-me` is interactive-only — instruct the user to run it themselves; Claude cannot drive it through Bash.
- For risky delegated work: `--sandbox` + `--dangerously-skip-permissions` + narrow `--add-dir`. Never the middle two without the first.
- Serialize agy calls. Never run two in parallel. On `429` / quota errors: stop, report, do not retry.
- Reuse conversations with `-c` instead of starting fresh sessions when continuing the same thread.
- After a `/goal` run, read `~/.gemini/antigravity-cli/brain/<latest-uuid>/walkthrough.md` for a faithful summary of what changed.
- Don't trust any slash command the model invents — only the verified list above is real.
- Comparison workflow: state Claude's answer first, then run the same prompt via `agy -p`. Pick `/goal` mode only when the user wants both agents to *implement*, not just opine.

More agent context in georgekhananaev/claude-skills-vault

63 other files this repository gives its agents, the first 60 shown.