agy_admin
Run bounded diagnostics and metadata actions for the bridge and agy CLI.
LABSCO SUMMARY
Long Antigravity work survives the call that started it.
The design choice that matters is that MCP calls do not own the process: a detached supervisor does, so a run keeps going through a harness restart and is picked up afterwards by run id. That is what makes real parallelism practical — start several runs, wait on an event condition across all of them rather than polling each transcript, and take the terminal view only when one asks for attention. Reviews follow the same shape: start the typed run, wait, then read the validated artifact rather than scraping the transcript.
What it is
A control plane in front of the Antigravity CLI. Runs are started as detached, supervised processes with their own state, logs and transcript, so the harness can restart, a call can time out, and the work carries on.
What you get
- Runs started in a workspace as a normal task, or as a persistent interactive conversation, or continued against an exact conversation id
- A run that cannot report success until a named file is non-empty, for work whose whole point is the artifact
- Sparse waiting instead of polling — wait on any_attention, any_terminal, all_terminal or any_event across a list of runs, and wake only when one of them happens
- One observation surface with four views: merged state across runs, or status, transcript or terminal for a single run, all bounded in size
- Input sent into a live run, with optional guards that reject the write if the event or transcript cursor moved after you last looked
- Runs cancelled cleanly, taking down the process group rather than orphaning it, and final results read back whole or in byte ranges
- Typed review runs over a commit, over branch and working-tree changes, or over a named file list, each producing an artifact that a companion tool validates and summarises
- Goals that create named targets and run them with bounded parallelism, inspected as one coordinated batch
- Bounded diagnostics over the bridge and the CLI, including a doctor action for when a run reports that authentication is needed
Requirements
The Antigravity CLI (agy) installed and already signed in — agy --version only proves the binary exists, so run agy models first and complete the browser login if it asks. Also uv/uvx, and tmux on macOS, since foreground runs live in persistent tmux sessions that a terminal can attach to without killing the agent. AGY_CMD points the bridge at that authenticated agy executable. It runs over stdio as uvx codex-agy-bridge@latest, and Codex CLI installs it with codex mcp add. When a run still hits auth, it comes back with status="auth_required" and opens a visible sign-in session. MIT.
Setup effort
One command — codex mcp add codex-agy-bridge --env AGY_CMD="$(command -v agy)" -- "$(command -v uvx)" codex-agy-bridge@latest
USE CASES
01
Running several Antigravity tasks side by side
Start each run in its own workspace, then wait on one condition across the whole list — first to need attention, or all finished — instead of polling any of them.
02
Picking work back up after the harness restarted
Runs outlive the call that started them, so the status, transcript and final result are still there to read by run id.
03
Answering a run that is waiting on you
Send the input with a cursor guard attached, so the write is rejected rather than applied blindly if the run moved on between your last look and the send.
04
Getting a commit or a branch reviewed
Start a typed review with a focused issue and narrow scope paths, wait for it to finish, then read the validated artifact summary instead of the raw transcript.
05
Making sure a run produced the file it was asked for
Name the expected file at start; the run cannot reach completion while that file is still empty.
06
Driving a batch of related tasks as one effort
Create a goal, start named targets under it with a parallelism cap, and read the status of the whole batch rather than of each run.
07
Working out why nothing is starting
Run the bridge diagnostics, and when a run reports that authentication is needed, open the terminal view on the visible sign-in session it started.
14 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
agy_goal
Manage bridge scheduler goals with actions create, start_target, status.
dangerously_skip_permissions must be true when supplied.
agy_login
Refresh Antigravity auth state and optionally open one login session.
agy_review_branch
Start a typed review Run for branch and working-tree changes.
Keep issue focused and use narrow scope_paths when possible. Wait for completion with agy_run_wait, then prefer agy_review_result. Avoid frequent agy_run_observe(include_terminal_tail=True) calls unless debugging the bridge.
agy_review_commit
Start a typed review Run for one commit and return immediately.
Keep issue focused and use narrow scope_paths when possible. After the run completes, prefer agy_review_result over manually polling raw artifacts.
agy_review_files
Start an artifact-gated typed review Run for local files.
agy_review_result
Validate and summarize the artifact from a typed review Run.
Preferred way to consume completed commit, branch, or file review Runs.
agy_run_cancel
Cancel one active Run and terminate its Antigravity process group.
agy_run_input
Send input to a live foreground Run with optional stale-write guards.
agy_run_observe
Inspect Run state through one lean observation surface.
view="full" returns merged observable state for all run_ids. view="status", "transcript", or "terminal" requires exactly one run_id and returns the corresponding focused view.
agy_run_result
Read final result metadata, or a bounded chunk when offset_bytes is set.
agy_run_start
Start or continue one foreground Antigravity Run.
mode="task" starts a normal bridge-owned task. mode="interactive" starts a persistent conversation session that should be used sparingly. Supplying conversation_id continues that exact Antigravity conversation. Use agy_start_with_expected_file for reviews and other artifact-producing tasks. dangerously_skip_permissions must be true; the bridge always forwards --dangerously-skip-permissions to Antigravity.
agy_run_wait
Wait for sparse Run events instead of repeatedly polling status.
run_ids is always a list, even for one Run. Supported condition values: any_attention, any_terminal, all_terminal, any_event, plus aliases attention, terminal, finished, finish, complete, completed, result, all_finished, all_complete, and all_completed.
agy_start_with_expected_file
Start one task Run that cannot complete until expected_file is non-empty.
BEFORE YOU INSTALL
What to know first
Tools you get
14 tools when we connected. The documentation lists 8; agy_login, agy_start_with_expected_file and the review tools (agy_review_branch, agy_review_commit, agy_review_files, agy_review_result) are undocumented. In Codex, names may carry the server prefix, as in codex_agy_bridge_agy_run_wait.
Requires
- Codex CLI for the command below, or another local stdio MCP-capable harness
- The official Antigravity CLI (agy), already authenticated locally
- tmux on macOS
- It currently targets Python 3.11+, macOS
- Antigravity CLI 1.0.8-compatible commands and trajectory files
CONTEXT COST
Light Standing cost
Rated by the size of the 14 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Codex
TERMINAL
codex mcp add codex-agy-bridge \
--env AGY_CMD="$(command -v agy)" \
-- "$(command -v uvx)" codex-agy-bridge@latest
