How to Drive Antigravity from Claude Code

One AI agent can run another. The trick is a filesystem handshake, a per-run human gate, and knowing exactly which command to type.

The pattern: a station, not an API

Antigravity is driven as an external command-line session, never imported as a library and never called per token. The interface is a folder — a “station” — with a simple contract: a queue of work to do, an inbox (or a fenced text block) for what comes back, and a stable id rule so each result maps to its request. Claude Code prepares the station, the worker acts inside it, and Claude ingests the output. Keeping the handshake on the filesystem is what makes the boundary auditable: every input and output is a file you can inspect. The same no-API seam applies beyond image work – for driving a local agent to draft written content the same way, see generating catalog content with a local AI agent.

Drive the worker through a folder it can see, not an API it can call – the files are the audit trail.

Prerequisites: manual mode and a bounded directory

Two things must be true before a run. First, the operator’s session is in a manual, “ask” permission mode, so launching the worker requires an explicit human approval at the prompt. This gate is not red tape — it is the concurrency control. Because every run needs a manual yes, runs serialize through the operator: one at a time, never concurrent. Second, the worker’s file access is bounded to a single directory. Approve the run only after reading that scope, so you know exactly what the worker can touch.

The command, flag by flag

The worker is invoked headless with a single instruction. The core command:

agy --print "<the task, in plain language>" \
    --print-timeout 40m \
    --add-dir /path/to/station
Code language: Bash (bash)

Each flag earns its place:

• --print "<task>" runs one non-interactive turn with the task you pass, then exits. No chat session, no back-and-forth.
• --add-dir /path/to/station bounds the worker’s file tools to that one directory — the smallest blast radius. It is the difference between “act inside this folder” and “act anywhere.”
• --print-timeout 40m caps the wall-clock time for the whole turn. The default is short (about five minutes), which fits roughly one image; size it to the batch or the turn is killed mid-run.

Two postures: writing versus proposing

The same pattern serves two jobs, and the permission posture differs because one job writes files and the other does not.

Writing files – image generation. When the worker must save its output (image files into the station’s inbox), it needs to auto-approve its own internal tool, because a headless run cannot stop to ask. That is what the worker’s own --dangerously-skip-permissions flag does — and it is safe only because --add-dir has already fenced the worker to one folder:

agy --dangerously-skip-permissions --print-timeout 40m \
    --print "Read queue.md. For every entry with status pending, generate one 16:9 image \
             and save it as inbox/<id>.png; report each saved path; do not edit other files." \
    --add-dir /path/to/image-station
Code language: Bash (bash)

Proposing text – website and source evaluation. The very same worker also does research: reading a captured web page, evaluating a site, and drafting a first-pass data adapter. Here it must not write anything — it only proposes. So the dangerous flag is dropped entirely, and the output is captured from the worker’s printed text between clear markers:

agy --print "Evaluate this source and draft a first-pass adapter. \
             Return the code between <<<ADAPTER>>> markers and notes between <<<NOTES>>> markers. \
             Do not write any files." \
    --print-timeout 9m \
    --add-dir /path/to/discovery-repo
Code language: Bash (bash)

The rule is worth stating plainly: grant the power to write only when writing is the job, and never for a worker that should merely propose.

Give the worker permission to write only when writing is the task – a proposer runs read-only.

Size the timeout to the batch

The default timeout fits about one image; each render takes a couple of minutes. If the cap is too low, the turn is killed partway and unsaved work is discarded, not returned. Size the timeout to the batch — roughly a few minutes per item — and instruct the worker to save or print each result as it finishes, so an interrupted run still yields the items it completed.

Keep runs gentle and serial

Never fire a whole queue blind. Generate one item or a small batch, look at the output, then release the next few. A driven agent is still load and still risk, and a style or quality problem caught on the first item is far cheaper than the same problem multiplied across fifty. The operator gate already enforces one run at a time; the gentle-batch habit keeps each run small enough to judge.

Record provenance and review before you accept

Nothing the worker produces ships unchecked. Store the exact instruction and inputs alongside each result, so any output is reproducible and auditable. Then review against a clear specification — for an image, that it is on subject and free of text or hands; for a proposed adapter, that a test gate actually passes on real data. The worker proposes; a reasoning agent and a human dispose. This review step is the whole reason the pattern is safe to run at all.

When not to hand over the keys

• Never make the worker authoritative. It drafts; the decision stays with the operator and the reviewing agent.
• Never run concurrent sessions. Queue behind the single operator gate.
• Never grant write access to a proposer. If the job is to evaluate or draft text, run read-only and capture the output from its printed markers.
• Never skip the record. An undocumented result is not finished work; it is archaeology someone has to redo.

The short version

Driving Antigravity from Claude Code is a folder handshake plus a human gate. Claude Code prepares a station, an operator approves one headless agy --print run bounded by --add-dir, and Claude reviews the result before it ships. Add the worker’s own skip-permissions flag only when it must write files, keep it read-only when it only proposes, size the timeout to the batch, run gently and one at a time, and record every result. The same handful of commands then serves both image generation and website evaluation.

Frequently Asked Questions

How does one AI agent drive another safely?

Through a bounded folder and a per-run human approval. The driving agent prepares the work, an operator approves a single scoped command, and the result is reviewed before acceptance. The folder boundary and the manual gate together keep the worker from acting outside its task.

What does the --add-dir flag do?

It limits the worker’s file tools to one directory, so it can only read and write inside that folder. Approving a run means reading that scope first, so you know exactly what the worker can reach before you say yes.

When should I use --dangerously-skip-permissions?

Only when the worker must write its own output in a headless run — for example saving generated images — and only after --add-dir has fenced it to one folder. For a worker that just proposes text, drop the flag and run read-only.

Why run the worker one task at a time?

Because a manual approval gates every run, the runs naturally serialize, which prevents two workers colliding on the same files. It also keeps each batch small enough to inspect, so a problem is caught early rather than multiplied across a queue.

Can the same setup do more than generate images?

Yes. The same command pattern drives a worker to evaluate websites and draft first-pass data adapters — reading a page and proposing code as text. Only the permission posture changes: writing jobs may save files, proposing jobs stay read-only.