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:

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

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

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