Bilal140202 Collaborating with Antigravity (Codex edition)
agy-bridge is a thin JSON wrapper around the Google Antigravity (agy)
CLI plus a gemini CLI fallback. The bridge returns stable
BridgeResponse envelopes designed to drop cleanly into Codex's
exec-json protocol via --output-protocol codex.
When to use
- You want a second opinion from Antigravity / Gemini on a tricky bug, design call, or code review.
- You want to prototype a change in an isolated worktree before touching the main checkout.
- You want a long-running agent loop to run in the background while Codex continues other work.
Avoid for trivial single-step questions — the round-trip is overkill.
Quick start
python scripts/agy_bridge.py \
--cd "/path/to/project" \
--PROMPT "Find every place that calls db.commit() without a try/except." \
--mode review \
--output-protocol codex
The bridge prints one JSON line on stdout: {"success": true, "SESSION_ID": "…", "agent_messages": "…", "adapter": {…}}. With
--output-protocol codex the event log conforms to Codex exec-json
(thread.started, item.completed, turn.completed).
Modes
| Mode | Use it for | Worktree | Writes |
|---|---|---|---|
ask (default) |
Q&A, code reading | no | no |
plan |
Multi-step planning | no | no |
prototype |
Diff-only suggestions | optional | no |
review |
Critique a staged change | no | no |
execute |
Apply edits in a worktree | yes | requires --allow-write |
browser |
Research with browsing | no | no |
long |
Detached agent loop | no | varies |
Multi-turn
Capture and reuse SESSION_ID:
# Turn 1
python scripts/agy_bridge.py --cd /proj --PROMPT "Find race conditions in src/queue/"
# → {"SESSION_ID": "abc-123", ...}
# Turn 2
python scripts/agy_bridge.py --cd /proj --SESSION_ID abc-123 \
--PROMPT "Propose a minimal fix for the worst one."
Detached long jobs
Codex projects that run long agent loops should prefer the MCP tool
surface (agy_start / agy_status / agy_result / agy_read /
agy_cancel / agy_sessions) over polling the CLI in a shell loop. The supervisor
handles worker thread lifecycle, log spooling, and cross-platform
process-group cleanup.
Output protocols
--output-protocol codex— Codex-shaped exec-json events (thread.started,item.completed,turn.completed).--output-protocol claude— Claude Code stream-json (default).--output-protocol raw— internal canonical event envelope.
Safety
The bridge scrubs secrets from every error / log / response, runs
under SafetyPolicy, and refuses destructive prompts even with
--allow-write. The doctor (agy_doctor MCP tool, or
python -m agy_mcp.doctor) reports the environment without leaking
secrets.
Detailed references
references/usage.md— full CLI flag reference + MCP tool surface + exit codes.references/prompt-patterns.md— proven prompt scaffolds per mode.references/security.md— threat model, secret scrub, denylist, worktree, audit log layout.