sub-agy

Use Antigravity as a subagent in Claude Code / Codex / Kimi Code.

English | 简体中文

sub-agy turns the Antigravity CLI (agy) into an asynchronous code-execution backend for your planning agent. The planner writes a plan and reviews results; the heavy lifting runs in the background on your Gemini quota, inside an isolated git worktree, and comes back as a structured acceptance report.

How it works

flowchart LR
    P["Plan<br/>Claude Code · Codex · Kimi Code"] -- "sub-agy run" --> S["Detached supervisor<br/>(FIFO slot queue)"]
    S --> W["agy · Gemini<br/>isolated git worktree"]
    W -- "--json-schema" --> R["result.json<br/>structured acceptance"]
    R -- "watcher wakes the agent" --> V{Review}
    V -- pass --> M["git merge agy/&lt;job-id&gt;<br/>(always human)"]
    V -- fail --> F["feedback<br/>same conversation, next round"] --> S

Loading

Features

• Async dispatch, background execution — run returns a job_id immediately; a detached supervisor keeps agy going even after the caller exits. Jobs beyond max_concurrent queue up FIFO.
• git worktree isolation — every job runs on its own branch (agy/<job-id>) in its own worktree; your main branch stays clean.
• Structured acceptance contract — --json-schema makes agy report summary / files_changed / tests_passed and more.
• Proactive completion notification — one background watcher per job: whichever job finishes first gets reviewed first. A Stop-hook safety net (sub-agy pending) catches anything left unharvested.
• Automatic feedback loop — failed acceptance triggers feedback, which keeps the conversation and starts the next repair round.
• 0-token quota check — quota reads the Antigravity 5h/weekly windows for free.

Requirements

• agy CLI ≥ 1.1.8, logged in once interactively (run agy once to complete OAuth)
• Python ≥ 3.11
• uv (recommended) or pipx
• git (needed for worktree isolation; non-git projects fall back to in-place execution)
• Claude Code, Codex desktop, or Kimi Code CLI (at least one)

Installation

The CLI is required — plugins alone do not work. The Claude Code / Codex / Kimi Code plugins are thin orchestration layers: every plugin command shells out to the sub-agy binary and fails with exit 127 if it is missing. If you prefer not to install it globally, the only fallback is cloning the repo and setting export SUB_AGY_HOME=<repo path> — the plugins then run it from source via uv run --project, which still requires uv.

Since v0.1.1, /subagy:doctor detects a missing CLI and offers to install it for you (one confirmation, then uv tool install). The agy binary and its OAuth login always remain manual.

CLI (no clone needed)

uv tool install git+https://github.com/Besty0728/sub-agy

Verify:

sub-agy doctor

Claude Code plugin

/plugin marketplace add Besty0728/sub-agy
/plugin install subagy@subagy
/reload-plugins

Codex desktop

No clone needed — add a git marketplace to ~/.codex/config.toml:

[marketplaces.subagy]
source_type = "git"
source = "https://github.com/Besty0728/sub-agy"

Restart Codex and install subagy from the plugin panel.

For offline/development use, a local marketplace works too:

[marketplaces.subagy]
source_type = "local"
source = "<path to clone>"

Kimi Code CLI

/plugins install https://github.com/Besty0728/sub-agy
/reload

Commands are namespaced: /subagy:dispatch, /subagy:harvest, etc. After dispatch, each job is watched by a background subagy-watcher subagent that returns to the main agent the moment the job finishes. For local development use /plugins install <path to clone> (the plugin is copied to $KIMI_CODE_HOME/plugins/managed/; reinstall after editing sources).

Configuration (optional)

sub-agy runs fine with zero configuration. To change defaults, create ~/.config/sub-agy/config.toml (override the location with the SUB_AGY_CONFIG environment variable). Every key is optional; the values below are the built-in defaults:

default_model = "gemini-3.7-flash"  # model slug passed to agy
default_effort = "medium"           # low | medium | high
default_timeout = "30m"             # per-job timeout, Go duration (Ns/Nm/Nh)
max_concurrent = 3                  # jobs running at once per project; extras queue FIFO
max_retries = 1                     # extra attempts after a timeout
queue_timeout = "2h"                # max wait for a run slot before the job errors
agy_bin = "agy"                     # agy binary name or absolute path

A missing file simply means the defaults above. Per-job CLI flags (--model / --effort / --timeout) override the config.

Quick start

1. Write a plan file

cat > plan.md <<'EOF'
---
scope: [src/**/*.py]
acceptance:
  - pytest tests/ -q passes
constraints:
  - no new dependencies
---
Add type annotations to the login function and fix the type errors this exposes.
EOF

2. Dispatch

In Claude Code (the main agent defaults to gemini-3.7-flash + medium effort, auto-raising to high for complex plans and lowering to low for trivial ones):

/subagy:dispatch plan.md

Or straight from the CLI (with explicit --effort / --model if you like):

sub-agy run --plan plan.md --cwd ./my-project

3. Automatic review

When a watcher wakes the main agent, it reviews the result following the /subagy:harvest rules: accept, fail, or send it back for another round.

4. Merge

Once acceptance passes, merge the execution branch yourself:

git merge agy/<job-id>

Quota check

sub-agy quota --oneline

Sample output (currently localized in Chinese):

Gemini 模型：5h 限额剩余 99.8%（32分钟后重置），7d 限额剩余 99.8%（6天11小时后重置）；Claude/GPT 模型：7d 限额剩余 100.0%

CLI reference

Command	Description
sub-agy run --plan <plan.md>	Dispatch a plan, returns job_id immediately
sub-agy status [--all]	Show job status, queue position, tokens, elapsed
sub-agy result <job-id>	Harvest the structured result of a finished job
sub-agy feedback <job-id> "..."	Send feedback, start the next repair round
sub-agy watch <job-id>	Block until the job reaches a terminal state
sub-agy cancel <job-id>	Cancel a job
sub-agy list	List jobs in the current project
sub-agy pending [--under <dir>]	List finished-but-unharvested jobs (data source for the Stop-hook safety net)
sub-agy cleanup <job-id>	Remove the job worktree and branch
sub-agy quota [--oneline] [--pretty]	Query Antigravity quota (0 tokens)
sub-agy doctor	Environment diagnostics

Security & compliance

• Official-CLI process orchestration only — sub-agy never touches model APIs and never stores or proxies API keys.
• Fully autonomous + worktree isolation + human merge — agy always starts with --dangerously-skip-permissions for unattended execution; the safety boundary is the isolated git worktree, the plan's scope/constraints, and the fact that git merge is always triggered by a human.
• Automatic feedback, manual merge — feedback re-runs with full context preserved; git merge agy/<job-id> is always yours to run.

License

MIT