Understudy

A live cockpit for the AI coding agents you delegate to Google Antigravity (agy / Gemini). Offload the grunt work to a cheap model, watch it work in plain language, and save your premium model budget for the hard thinking.

Why

Premium coding-model budgets run out fast, and rate limits bite. Google Antigravity / Gemini agents are cheap with generous limits — but they run headless and you can't see what they're doing. Understudy makes delegating to the cheap model safe and visible: hand off routine implementation, watch every step, and keep your premium model for what actually needs it. Smart routing, not magic.

Quickstart

Give Antigravity a bounded task and watch it work:

mkdir -p ~/agy-sandbox/my-task
echo "Add a /health endpoint to server.js and a test for it" > ~/agy-sandbox/my-task/prompt.md

npx agy-understudy run --dir ~/agy-sandbox/my-task --prompt ~/agy-sandbox/my-task/prompt.md

Then open the cockpit — in another terminal, or any time after the fact:

npx agy-understudy

It opens at http://127.0.0.1:4288 and streams what each run is doing, live.

Writing prompts that actually run

A short, goal-style prompt with no execution mode often makes the agent stop to ask for approval instead of doing the work: it proposes a design, asks "does this look right?", and exits. The process exits cleanly, so the cockpit badges the run "Ended with question" (not "Completed") and shows you the exact question — but no files were written.

To get a run that does the work end to end:

1. Pass --mode accept-edits so the agent may write files without a confirmation step.
2. Make the prompt imperative and explicitly forbid stopping for approval.
3. Give it absolute paths it may edit and a single validation command.

mkdir -p ~/agy-sandbox/health-task
cat > ~/agy-sandbox/health-task/prompt.md <<'EOF'
Implement the requested change now. This is a non-interactive run: do NOT ask for
confirmation, do NOT stop at a design proposal, do NOT wait for approval.

Goal: add a GET /health endpoint that returns {"ok": true} to server.js.
You may edit only: /absolute/path/to/server.js and /absolute/path/to/test/server.test.mjs.
Acceptance checks: GET /health responds 200 with {"ok": true}.
Run only this validation command: npm test.
At the end, state the changed files, the validation output, and any remaining limitation.
EOF

npx agy-understudy run \
  --dir ~/agy-sandbox/health-task \
  --prompt ~/agy-sandbox/health-task/prompt.md \
  --mode accept-edits

Even on a clean exit, open the run and check the files it produced — always verify the result independently.

What you see

• A live activity strip: reading / exploring / planning / writing code / testing / question / done.
• An Explanation tab: a step-by-step timeline plus a "how Antigravity works" primer.
• The prompt it was given and the files it produced.

Understudy shows the runs you start through it (understudy run is what records the log and the run manifest it reads). It is a cockpit for delegated work, not a general-purpose tail of everything agy has ever done on your machine.

Requirements

• Google Antigravity CLI (agy) on your PATH.
• Node.js ≥ 20.

Configuration

• --root <dir> / UNDERSTUDY_ROOT — where runs live (default ~/agy-sandbox).
• --port <n> / UNDERSTUDY_PORT — cockpit port (default 4288).

How it works

One Node process serves the cockpit UI and a small API that reads the run directories under your root. The "what is it doing?" explanation comes from a deterministic local parser — no LLM, no network call, no telemetry. A watchdog protects delegated runs (6-minute limit, 90-second stall kill) and terminates the whole process group so nothing is orphaned.

The server binds to 127.0.0.1 only, answers GET only, and never writes to your run directories. See SECURITY.md.

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.

Understudy is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Google. "Antigravity" and "Gemini" are trademarks of Google LLC.