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:

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:

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

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

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

Environment variables

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.