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 "" 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 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 in REPL or agy -p "/goal " | 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//. |

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

agy -c -p "Continue from where we left off"          # resume most recent
agy --conversation  -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 | Autonomous long-running build/refactor (see effort tiers above) | | /grill-me | Interactive interview to align on a plan before coding | | /schedule | 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 | 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 ]
agy plugin list
agy plugin import [gemini|claude]
agy plugin install 
agy plugin uninstall 
agy plugin enable|disable 
agy plugin validate [path]
agy plugin link  

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 | Resume a specific conversation by ID | | --add-dir | 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 | Timeout for -p (default 5m0s; bump for /goal) | | --log-file | 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/.pb       # full chat history (protobuf)
├── brain//                 # 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/.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 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//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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: georgekhananaev
• Source: georgekhananaev/claude-skills-vault
• License: MIT
• Homepage: https://www.npmjs.com/package/claude-skills-vault

Install and usage instructions live in the source repository linked above.