agy-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:

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:

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

# 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.

# 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 ≥--stalls, 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>/.

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