Quickstart
Plan in Antigravity, compile with agb plan, execute with agb run, watch with agb status
You plan in Antigravity and execute with agb. Planning stays where it already works: the desktop app's plan mode or a planning conversation in an agy session. Both write a brain artifact (implementation_plan.md under ~/.gemini/antigravity-cli/brain/ or ~/.gemini/antigravity/brain/). agb doesn't replace that phase. It compiles the artifact: treat implementation_plan.md as source and plan.json as its compiled output.
This page assumes you have finished Installation and agb doctor passes. Inside an interactive Antigravity session, you can also invoke any of these steps in natural language with /agb <description> (for example, /agb compile my latest brain plan and run it) or with the specific /agb-plan, /agb-run, and /agb-review slash commands.
Compile a plan
agb brains # list plan artifacts, newest first
agb plan <brain-id> /abs/repo # compile → gate → plan.jsonThe compiler converts the plan with a frontier model, then runs it through the plan gates (structural checks, coldstart, parallax, and an advisory premortem). Any failure goes back into a fresh conversion rather than leaving you with invalid JSON. When findings survive that loop, the fix belongs in the plan: refine it in Antigravity, or edit the spec, and re-run agb plan. See Plan boundary.
Useful flags: --out <file> (default plan.json), --force (overwrite an existing output file, which is refused otherwise), --no-coldstart, --no-parallax, --no-premortem.
Validate it (optional)
A compiled plan has already passed validation. If you edited plan.json by hand, check it again:
agb validate plan.jsonRun it
agb run plan.jsonEach ticket is built in its own worktree, gated, prosecuted by another model family, and merged in order. The final report is printed to stdout as JSON.
Watch it
From another terminal:
agb status /abs/repo # one-shot snapshot of the current run
agb status /abs/repo --watch # refresh in place (--interval <ms>, default 1000)For a richer view, start the sidecar dashboard with agb sidecar /abs/repo.
Exit codes
The general rule is 0 = pass, 2 = gate failure or findings, 1 = usage or internal error (bin/agb.mjs). For the commands on this page:
| Command | 0 | 1 | 2 |
|---|---|---|---|
agb plan | compiled, plan.json written | missing arguments, output exists without --force, or quota telemetry unavailable from agy (L195-L210) | blocking findings, plan not compiled (C10) |
agb validate | plan valid | unreadable or malformed file (internal error) | plan invalid (C10) |
agb run | every ticket succeeded | plan invalid (C10) | one or more tickets failed (C10) |
agb status | snapshot printed | the removed TUI flag was passed (use agb sidecar) (L269-L272) | — (with --watch, the code comes from the watch loop) |
An invalid plan exits with 1 from agb run but with 2 from agb validate. For validate, an invalid plan is the finding it exists to report. For run, it is a usage error.
The full table for every command is in Exit and error codes.
Next steps
- Writing plans: hand-writing
plan.jsonwhen you have no brain artifact. - Walkthrough: a complete worked example.
- Plan schema: every field
agb validateenforces.