# Antigravity CLI Delegate

[中文](README.zh-CN.md) · [Skill](SKILL.md) · [Host setup](references/host-setup.md)

A small agent skill and event-driven runner for delegating bounded work to **Gemini
Flash through Google Antigravity CLI**. The caller sends a short brief, receives live
tool progress, and accepts a compact final result. No status polling or supervisor model.

- Defaults to the newest **listed Gemini Flash >= 3.8, Medium**. High is opt-in.
  Exact model requests win; explicit Claude Opus Thinking is also supported.
- One pending MCP call, standard progress notifications, one terminal response.
- Prompts go through stdin; raw events and stderr stay in private local files.
- Default final summary: 2,400 characters plus an explicit truncation marker and
  evidence paths. Tool arguments, outputs, and reasoning are excluded from progress.
- CLI failure, invalid results, cancellation, and deadlines fail closed. No automatic retries.

This is a community project, not an official Google or OpenAI product. It uses `agy`,
not the `gemini` CLI. An existing authenticated Antigravity account is required.

## Install

Requires **Node 22+**, **macOS or Linux**, and an authenticated `agy` installation.
Tested against `agy 1.2.0`; the runner checks capabilities and available models on each run.

```bash
git clone https://github.com/WangZhuo2015/antigravity-cli-delegate.git
cd antigravity-cli-delegate
npm ci --ignore-scripts
```

For Codex skill discovery, link the repository to your skills directory. If the
destination already exists, preserve it before replacing it:

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "$PWD" "${CODEX_HOME:-$HOME/.codex}/skills/antigravity-cli-delegate"
```

Register the MCP server for the no-polling workflow:

```bash
codex mcp add antigravity-delegate -- node "$PWD/scripts/mcp.mjs"
```

Set `tool_timeout_sec = 660` in the resulting
`[mcp_servers.antigravity-delegate]` configuration table for the default 600-second
runner deadline. Restart the host session if needed. Other MCP hosts can run the same
stdio command; see [host setup](references/host-setup.md) for timeouts and progress tokens.
The host controls whether progress is displayed and whether other work can run concurrently.

## Use

Ask your agent:

> Use $antigravity-cli-delegate to review src/parser.mjs for the failing empty-input
> case. Read only that module and its test. Report the cause with line references;
> do not edit files.

Or call the MCP `delegate` tool directly:

```json
{
  "cwd": "/absolute/project",
  "task": "Goal: fix the empty-input case. Scope: src/parser.mjs and test/parser.test.mjs only; preserve unrelated changes. Check: node --test test/parser.test.mjs. Report: changed files and check results.",
  "mode": "accept-edits"
}
```

The default mode is `plan` with `--sandbox`. Use `accept-edits` only when the user
has authorized those edits. These settings and prompt constraints are not a filesystem
allowlist; use an isolated workspace when stronger containment is needed. The caller
still checks the diff and acceptance evidence. `SUCCESS` only means the CLI completed.

The same runner works without MCP dependencies from a foreground terminal:

```bash
node scripts/run.mjs --cwd /absolute/project --task-file /absolute/brief.txt
```

Optional flags: `--effort high`, `--model EXACT_LISTED_ID`, `--mode accept-edits`,
`--timeout-seconds 600`, `--max-summary-chars 2400`. Use `AGY_BIN` for a custom CLI path.

## How it avoids caller overhead

```text
short brief → one delegate call → agy stdin / NDJSON event stream
                               ↘ tool-state notifications → host UI
                                ↘ complete local evidence → disk
                                 ↘ compact final result → caller model
```

The runner waits on pipe and process events. Its only timers are a deadline and
termination escalation; there are no heartbeat, sleep/check, or polling loops. A host
that offers only polling shell sessions cannot provide no-polling background execution;
use MCP or a single foreground call instead. There is no background job queue or
durable reconnect/resume mechanism: closing the MCP transport cancels active work.

The rewritten skill is roughly 61% shorter by word count than its original local
version. This is not a measured token-cost reduction. Actual caller usage depends on
the host, brief, result length, and verification. The `usage` field is the **worker's**
usage. The runtime also avoids returning repeated preflight output to the caller.

## Verify and contribute

```bash
npm test
node scripts/smoke.mjs
```

`npm test` is offline and uses a protocol double. The second command is an explicit
live check using your authenticated account: it asks Gemini to read a temporary fixture,
checks the answer and unchanged files, and receives progress through the official MCP
client. It is excluded from CI and may consume account quota. Test logs contain local
workspace data; review them before sharing and remove them when no longer needed.

Tests cover model routing, streaming before completion, duplicate filtering, bounded
summaries, private evidence, stdin quoting, unsuccessful status/exit, broken streams,
timeouts, and cancellation. Contributions should preserve these observable behaviors.
Run `npm test` before submitting changes; do not include credentials or local run logs.

## License

[MIT](LICENSE). Protocol references: [Antigravity headless mode](https://antigravity.google/docs/cli/headless/)
and [MCP progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress).