Quick Start
python scripts/agy_bridge.py --cd "/path/to/project" --PROMPT "Your task"
Output: JSON with success, SESSION_ID, agent_messages, steps_file, and optional error / note / stderr. On failure, error names the upstream cause agy recorded (e.g. a 400/503 status) when one exists.
Parameters
usage: agy_bridge.py [-h] --PROMPT PROMPT --cd CD
[--model MODEL] [--SESSION_ID SESSION_ID]
[--sandbox] [--no-skip-permissions]
[--print-timeout PRINT_TIMEOUT]
[--return-all-messages]
{check,plugin} ...
Antigravity (agy) Bridge
options:
-h, --help show this help message and exit
--PROMPT PROMPT Instruction for the task to send to agy.
--cd CD Workspace root for agy (sets cwd + --add-dir).
--model MODEL Model alias (flash-low/medium/high, pro-low/high, sonnet,
opus, gpt-oss) or canonical string. Omit to use the
settings.json default.
--SESSION_ID SESSION_ID
Resume a conversation by UUID. Maps to agy --conversation.
--sandbox Run in agy sandbox mode.
--no-skip-permissions
Do NOT pass --dangerously-skip-permissions. WARNING:
with default toolPermission=request-review, print mode
WILL HANG. Only for interactive review workflows.
--print-timeout PRINT_TIMEOUT
agy --print-timeout (e.g. 5m, 10m). Default 10m.
--return-all-messages
Include reasoning + all type=15 steps in the response.
subcommands:
check Probe agy install / version / auth / current model.
plugin Thin passthrough to `agy plugin list|import|install|enable|disable`.
Multi-turn Sessions
Always capture SESSION_ID from the first response for follow-up (maps to agy --conversation <UUID>, which appends to the same conversation DB):
# Initial task
python scripts/agy_bridge.py --cd "/project" --PROMPT "Analyze auth in login.py"
# Continue with SESSION_ID
python scripts/agy_bridge.py --cd "/project" --SESSION_ID "uuid-from-response" --PROMPT "Write unit tests for that"
Common Patterns
Prototyping (request diffs):
python scripts/agy_bridge.py --cd "/project" --PROMPT "Generate unified diff to add logging" --model pro
Switch model per call:
python scripts/agy_bridge.py --cd "/project" --PROMPT "Review this Rust" --model sonnet
python scripts/agy_bridge.py --cd "/project" --PROMPT "Same code" --model opus
Setup check:
python scripts/agy_bridge.py check
Manage skills/plugins (passthrough to agy):
python scripts/agy_bridge.py plugin list
python scripts/agy_bridge.py plugin import /path/to/plugin
How It Works
agy --print writes nothing to stdout. The bridge instead runs agy, discovers the new conversation SQLite DB at ~/.gemini/antigravity-cli/conversations/<UUID>.db, and extracts the assistant reply from the step_type=15 rows' step_payload protobuf (field f20 → f1). MCP servers (~/.gemini/antigravity/mcp_config.json), the memory doc (~/.gemini/GEMINI.md), and skills are pre-configured by the user and auto-loaded by agy — the bridge does not manage them.
When a run fails upstream, agy writes no reply text at all and instead records the executor error in a step_type=17 row (f24 → f3: f1 user-facing line, f2 status detail). The bridge reads that row and reports the real cause — e.g. FAILED_PRECONDITION (code 400): User location is not supported for the API use. or UNAVAILABLE (code 503): No capacity available for model ... — instead of blaming its own parsing. stderr alone carries only agy's generic Agent execution terminated due to error. and no status code.
On resume, both extractors window on idx > after_idx, where the boundary spans all step types: a failed run's type=17 row lands after its last type=15 step, so a type=15-only boundary would re-attribute that stale error to the next run.
The bridge does not retry. A 400 geo rejection will almost certainly fail again on an immediate retry, and 503 capacity exhaustion is better answered by switching --model than by replaying — which could also repeat tool side effects. The structured error is passed through so the caller decides.
Security Note
By default the bridge passes --dangerously-skip-permissions to agy. This is mandatory for non-interactive --print mode because agy's default toolPermission is request-review, which blocks waiting for a human to approve tool calls — and since --print captures no TTY, the process hangs until timeout. With --dangerously-skip-permissions, agy auto-approves all tool calls. Only pass --no-skip-permissions if agy can service interactive permission prompts. The bridge always runs under a hard outer timeout (--print-timeout + 60s) so a hung agy cannot block indefinitely.
Known Limitations
- Protobuf extraction is schema-dependent. The bridge parses agy's conversation DB without a
.proto file: replies from f20 → f1 of step_type=15 rows, upstream errors from f24 → f3 of step_type=17 rows. If agy changes its internal schema, extraction returns empty. The reported error distinguishes the two cases — a message naming an upstream status means agy failed and the bridge worked; the schema-drift hint appears only when no error row explains the empty reply. Fix locations: extract_answer() and extract_run_error() in scripts/agy_bridge.py.
agy models returns empty on this build; model aliases are hardcoded.--continue is intentionally NOT exposed (target selection is opaque); use --SESSION_ID to resume a specific conversation.