joogy06/agent-foundry/antigravity-cli

Antigravity CLI (agy)

Task-indexed reference for the Antigravity CLI. `agy` is the SOLE second-opinion / challenger / research delegate on this host. Verified locally 2026-07-24 from agy --help, agy help <sub>, agy models, and agy --version (1.1.6).

`agy` is the SOLE second-opinion / challenger / research delegate on this host.

The gemini CLI was retired from this ecosystem on 2026-07-25 by user directive — not

because Google withdrew it, but because agy replaced it. The gemini-cli skill, the

nano-banana image skill that wrapped it, and its affordance registry were deleted.

There is no gemini fallback path. Do not add one, and do not reintroduce gemini -p

or mcp__gemini-cli__* calls to any skill.

Do NOT confuse this with the Vertex AI Gemini API, which is alive and in use —

vertex-banana calls it directly via VERTEX_API_KEY with no CLI dependency. Retiring the

CLI did not retire the API.

Two CLIs matter on this host: agy (~/.local/bin/agy, v1.1.6) = the Antigravity-runtime delegate (this skill) — the SOLE second-opinion delegate; antigravity (/bin/antigravity, v1.107.0) = the editor (VS Code/code-server fork), NOT for headless orchestration. Note that ~/.gemini/ is agy's own config home (agy.md, antigravity-cli/, OAuth creds) despite the name — never delete it.

Canonical host directive: ~/.claude/CLAUDE.md → "Antigravity CLI (agy) — host-specific

directive". This skill is the operational detail behind it.

When to use

• Delegating a headless prompt to a non-Claude model for a second opinion, challenger

review, design ratification, or research — the agy -p "..." pattern.

• Authoring skills/agents that shell out to agy.
• Managing agy plugins, sessions, sandbox, or auth.
• Any skill needing a non-Claude second opinion — route it through

agy -p now.

The headless orchestration pattern (primary use)

Two patterns, chosen by whether agy must USE TOOLS (read files, run commands, search) or only reason over content you pipe in:

# Pattern 1 — ADVISORY (default): agy reasons over an inline/self-contained prompt.
# Under --sandbox, headless agy auto-denies EVERY tool, so this prompt MUST NOT
# need to read a file or run a command — give it everything inline.
timeout 600 agy --sandbox -p "<full self-contained prompt>" < /dev/null
 
# Pattern 2 — TOOL-CAPABLE (opt-in): agy must read files / run commands / search.
# --dangerously-skip-permissions is the ONLY thing that unlocks headless tool use;
# it still runs INSIDE --sandbox (shell/git stay gated). Verified working 2026-07-17.
timeout 600 agy --sandbox --dangerously-skip-permissions -p "<prompt>" < /dev/null
git -C <repo> status --short   # tripwire after any repo-exposed call

• **HEADLESS-TOOL RULE (verified 2026-07-17 on agy 1.1.3; RE-VERIFIED 2026-07-24 on 1.1.6

with --model gemini-3.6-flash-high — Pattern 2 read a real file successfully, ~29s). `--sandbox` in headless `-p` mode auto-denies every tool — not just shell/git but `read_file` too ("jetski: no output produced — a tool required the … permission that headless mode cannot prompt for"). The `permissions.allow` list in `~/.gemini/antigravity-cli/settings.json` is inert under --sandbox** (its action(*) grants only take effect un-sandboxed, and un-sandboxed agy -p is blocked by the Claude Code auto-mode classifier). So a Pattern-1 call that needs to READ a file silently no-shows — inline everything, or switch to Pattern 2. --dangerously-skip-permissions overrides the auto-deny while --sandbox keeps shell/git capped (the S052 commit vector); native write_file is the accepted residual → keep the git status --short tripwire, never --add-dir a writable repo. Standing config stays TIGHT (command(agy), command(cpmail) only) — capability is a per-call flag, not a standing broad grant. This SUPERSEDES the older "omit --sandbox for writes" advice below: never drop --sandbox, add the skip-permissions flag instead.

• FLAG ORDER RULE — every flag BEFORE `-p` (root-caused 2026-07-02). -p is a Go string

flag: it consumes the NEXT token as the prompt, even if that token starts with -. So agy -p --sandbox "X" silently runs with prompt = literal --sandbox, sandbox OFF, and "X" discarded — agy then improvises from its implicit memory (observed: authored AND executed a repo-editing script across two such malformed calls; also the cause of the 2026-07-01 smart-analyst incident where an "analyst" edited two tracked test files after its brief never reached it). It can also fork-bomb: the inner agent re-tests the same broken command recursively until timeout. Always agy --sandbox --add-dir D --print-timeout 15m -p "…" — -p "<prompt>" LAST.

• **SANDBOX RULE — --sandbox is MANDATORY for consultancy/read-only delegation, but know its

scope (#157, S052 rogue auto-commit incident; re-verified 2026-07-02 on 1.0.15). agy has write/shell/git tools ON by default, and headless `-p` auto-approves them without `--dangerously-skip-permissions` — a plain `agy -p "create a file …"` probe wrote the file. `--sandbox` enables bubblewrap *terminal* restrictions: it constrains shell/git commands (the S052 rogue-commit class) but does NOT gate agy's native file-write tool — a correctly sandboxed call still edited a file in its `--add-dir` workspace on request (verified 2026-07-02). Therefore: (1) `--sandbox` on every advise-only call; (2) do NOT `--add-dir` a writable live repo for consultancy — pipe content (`cat file | agy --sandbox -p "…"`) or point at a read-only copy; (3) open consultancy prompts with "Advisory only — do not modify any files; answer on stdout" (`~/.gemini/agy.md` also enforces an advise-only default at the directive layer); (4) tripwire: after any call that exposed a repo, run `git status --short` and revert anything agy touched. Never omit --sandbox** (superseded 2026-07-17 by the HEADLESS-TOOL RULE above): when agy must write/run tools, keep --sandbox AND add --dangerously-skip-permissions — that gives tool use with shell/git still capped, which is strictly safer than dropping the sandbox.

• STDIN RULE — `< /dev/null` is MANDATORY for headless calls (root-caused 2026-06-05, task #135).

agy reads non-TTY stdin until EOF before running the prompt; in background/harness/cron shells stdin is an open stream that never EOFs, so agy blocks forever with 0 bytes of output — and --print-timeout does NOT protect you (it only guards the response-print phase, which is never reached). Close stdin (< /dev/null) or pipe real input (cat file | agy -p "..." — the pipe EOFs). ALWAYS also wrap in a shell timeout. Prompt SIZE is irrelevant: a 30-char prompt hung in the bad context; an 11KB prompt with stdin closed answered in 9 seconds. (Discriminating evidence: T1 bare/background = exit 124 @ 0B; T2 identical + < /dev/null = answer in 5s. Same stdin-until-EOF behavior class as codex exec.)

• Convention: pass no model flag. As of agy ≥1.0.5 a --model flag DOES exist (and an

agy models subcommand lists the choices) — but our convention is to omit it and let agy use the Antigravity-account configured model. Do not add --model unless a call explicitly needs a specific model. (There is no short -m alias; the gemini -m gemini-3.1-pro-preview pattern still does NOT apply to agy.) See Models below — the account default moved to Gemini 3.6 Flash on 2026-07-24, so the omit-the-flag convention now gets 3.6 for free.

• agy takes no API-key env prefix — it authenticates via the Antigravity account

(~/.antigravity/). The gemini GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= prefix does NOT apply to agy.

• Output is plain text on stdout — parse text, not JSON. There are no structured

response fields.

• --print-timeout defaults to 5m; raise it for long deliberations:

agy --print-timeout 15m -p "...".

• For verdict provenance, append a served_by probe line to the prompt — self-reported

model identity is unreliable. Observed 2026-06-05: the account default served gemini-3.5-flash. Observed 2026-07-24: the account default serves Gemini 3.6 Flash. Both are flash-tier — weight challenger/analyst verdicts accordingly (advisory tier), per the established tier-stratified-verdict practice. Flash-tier is not a limitation to work around: agy is flash-only by standing directive (see the Models HARD-RULE). If a decision needs pro-tier reasoning, escalate to a different arm rather than repointing agy's model.

Models (verified 2026-07-24, agy models on 1.1.6)

gemini-3.6-flash-{high,medium,low}    gemini-3.1-pro-{high,low}
gemini-3.5-flash-{high,medium,low}    claude-sonnet-4-6
                                      claude-opus-4-6-thinking
                                      gpt-oss-120b-medium

• Account default = `gemini-3.6-flash` (verified 2026-07-24 via a served_by probe with

no --model flag). The omit-the-flag convention therefore rides the 3.6 line automatically.

• Effort suffixes (-high / -medium / -low) are new relative to the 3.5 line and select

reasoning effort within a model. Measured on this host (Pattern 1, trivial prompt): gemini-3.6-flash-high ≈ 5s, gemini-3.6-flash-low ≈ 5s; Pattern 2 (tool-capable, one read_file) ≈ 29s on -high. Both patterns verified working on 3.6. <HARD-RULE> agy runs GEMINI FLASH MODELS ONLY. No exceptions, no roles, no "utility work" carve-out. (User directive, 2026-07-24.)

Two independent reasons, both binding:

1. Provider diversity (the `claude-*` / `gpt-oss-*` half). agy occupies the third-model slot

precisely because it is not Anthropic and not OpenAI. A claude-backed "third model" shares the Claude arm's blind spots and the cross-check becomes theatre; gpt-oss-* collapses into the Codex arm the same way. This is a live trap: agy seats in avengers already fail over to claude hosts when the headless permission auto-deny fires (S062–S067 carry-over), and the tempting "fix" for an agy no-show is --model claude-sonnet-4-6. That is the WRONG fix — it converts a recorded provider gap into a hidden one.

1. Flash-only tier discipline (the `gemini-3.1-pro-*` half). agy is a flash-tier delegate by

standing directive. Do not reach for pro to "get a better answer" — treat agy verdicts as advisory-tier and weight them accordingly. If a decision genuinely needs pro-tier reasoning, that is a reason to escalate to a different arm (Claude/Codex), not to repoint agy.

Correct responses to an agy no-show or a weak agy answer: (a) re-apply the STDIN + FLAG-ORDER + Pattern-2 rules and retry, (b) record the provider gap honestly and proceed short-handed. There is no gemini fallback — that CLI was retired from this ecosystem 2026-07-25. Never repoint the model. </HARD-RULE>

Verified flags (from agy --help, v1.1.6)