Non-blocking /agy-loop:loop scheduler for Google Antigravity Desktop & CLI (agy), powered by native schedule timers, isolated subagents, and live-reloading loop.md
English · 简体中文 · Why AGY Loop? · Quick Install · Commands & Flags · loop.md Guide · Exit & Stop · Architecture
AGY Loop brings a non-blocking, context-isolated loop scheduler (/agy-loop:loop) to Antigravity Desktop (Marketplace-ready) and Antigravity CLI (agy). Instead of locking your prompt with shell sleep or dumping repetitive build, test, and CI logs into your main conversation, agy-loop delegates each check or fix pass to an isolated loop-worker (or self) background subagent and parks between iterations on Antigravity's native schedule tool at zero token cost.
Inspired by Claude Code's
/loopworkflow and engineered around Antigravity's reactive subagent wakeup, sub-minuteDurationSecondstimers, statefulIdlere-awakening, and Git worktree isolation.
> /agy-loop:loop check current PR CI status and fix failures --stateful
⏺ Dispatched Loop #1/20 to loop-worker (stateful, sandbox). Main prompt is free.
[42s later · reactive subagent wake-up]
⏺ [Loop #1/20] Fixed snapshot mismatch in src/render.test.ts and pushed 9c41e2b; CI re-running | Next wake-up in 45s (self-paced)
> Meanwhile, explain how token caching works in src/auth.ts
⏺ Token caching in src/auth.ts stores verified JWT claims in an LRU map keyed by SHA-256...
(Background timer sleeps at 0 tokens/sec; your main chat stays clean and responsive.)
[45s later · timer wake-up -> Iteration #2]
⏺ [Loop #2/20] Unit & lint checks passed; awaiting e2e matrix (4/5 green) | Next wake-up in 90s (self-paced)
[90s later · timer wake-up -> Iteration #3]
⏺ [Loop #3/20] DONE: All 5 CI checks green on PR #42; active schedule cleared.
| Capability | Shell sleep Loop |
Claude Code /loop |
AGY Loop (agy-loop) |
|---|---|---|---|
| Wait Mechanism | Blocking shell sleep |
Built-in session cron queue | Native non-blocking schedule timers & crons |
| Main Chat Availability | Locked while waiting | Free between ticks | Free between ticks and while subagent runs |
| Context Isolation | Pollutes main chat with raw logs | Shares main conversation window | Clean loop-worker / self subagent window; 1-line main summaries |
| Minimum Granularity | 1s (blocks turn) |
1m cron floor (30s rounds up to 1m) |
Sub-minute DurationSeconds down to exact seconds (15s, 30s, 45s) |
| Dynamic Backoff | Fixed delay only | Model-selected 1m–1h delay |
Worker-reported NEXT_DELAY_SEC (30–60s active, 120–300s CI, 600–1800s idle) |
Live-Reloading loop.md |
None | .claude/loop.md & ~/.claude/loop.md |
Re-read every tick: .agents/loop.md -> loop.md -> ~/.gemini/config/loop.md -> built-in fallback |
| Stateful Debugging | Full transcript bloat | Shared main history | Opt-in --stateful Idle subagent re-awakening via send_message |
| Risk-Free Edits | Mutates active working tree | Mutates active working tree | Opt-in --worktree (branch isolated Git worktree) or --share copy |
- Antigravity CLI (
agy)v1.5.0+(verified againstcli-1.5.9strict validator) or Antigravity Desktop - Zero Node.js / npm required for native
agy plugin installor the one-linecurlinstaller (Node.js >= 18orBunis only needed if you use thenpx/bunxCLI bridge)
agy-loop is packaged as a pure, Marketplace-compatible dual-habitat plugin: the repository root is simultaneously a strict v1 Antigravity native plugin (plugin.json, hooks.json, skills/loop/SKILL.md, agents/loop-worker.md) and a zero-dependency npm CLI installer (bin/agy-loop.mjs). Once installed:
- In Antigravity's native plugin model, bundled skills register cleanly under the plugin namespace as
/agy-loop:loopin both Antigravity Desktop and Antigravity CLI (agy), keeping the plugin 100% self-contained without writing extra files outside~/.gemini/config/plugins/. - In Antigravity Desktop (Customizations -> Plugins / Marketplace), the plugin card also exposes 3 one-click starter prompt chips (
suggestedPrompts) to launch common loops or inspect/agy-loop:loop status. - If
agyCLI is already open during installation, run/skills reloadonce so/agy-loop:loopappears in slash autocomplete immediately.
npx agy-loop
# or with Bun:
bunx agy-loopMigrating from a manual ~/.gemini/config/skills/loop or ~/.gemini/config/agents/loop-worker.md setup? Because Antigravity loads user-level ~/.gemini/config/ files before plugins, pass --clean-shadow to install agy-loop and archive those loose files into ~/.gemini/config/.agy-loop-backup-<timestamp>/ automatically:
npx agy-loop install --clean-shadowagy plugin install https://github.com/maxlee/agy-loopMigrating from loose
~/.gemini/config/files?agy plugin installstages the plugin without removing pre-existing~/.gemini/config/skills/loop/SKILL.mdor~/.gemini/config/agents/loop-worker.md(which otherwise overrideloop-workereven under/agy-loop:loopand intercept/loop).agy-loopincludes a zero-overheadSessionStarthook (hooks.json) that stays silent (0tokens) when clean and automatically alerts you on session start if loose shadow files exist. Archive them non-destructively in one command (zero Node/npm required):sh ~/.gemini/config/plugins/agy-loop/install.sh --clean-shadowThen run
/skills reloadin open sessions, clean directly insideagyvia/agy-loop:loop doctor --clean-shadow, or runnpx agy-loop doctor --clean-shadow.
curl -fsSL https://raw.githubusercontent.com/maxlee/agy-loop/main/install.sh | shWith automatic shadow-file backup:
curl -fsSL https://raw.githubusercontent.com/maxlee/agy-loop/main/install.sh | sh -s -- --clean-shadowgit clone https://github.com/maxlee/agy-loop.git
cd agy-loop
agy plugin install .| Mode | Example Commands | Behavior |
|---|---|---|
| 1. Fixed Interval + Prompt | /agy-loop:loop 30s curl -fsS http://localhost:8080/health/agy-loop:loop 5m check the deploy/agy-loop:loop check PR #42 comments every 2h |
Runs on a fixed cadence (s, m, h, d). Chains non-overlapping DurationSeconds timers by default (supporting sub-minute 30s and non-cron 90s / 7m), or registers a 5-field CronExpression when --cron is passed. |
| 2. Dynamic Self-Paced | /agy-loop:loop check CI and fix failures/agy-loop:loop run pytest and fix failing tests --stateful |
Omits the interval. After each pass, loop-worker inspects live activity and sets NEXT_DELAY_SEC (30–60s active build/fix, 120–300s CI queue wait, 600–1800s quiet green backoff). |
3. Live-Reloading loop.md Maintenance |
/agy-loop:loop/agy-loop:loop 15m |
Omits the inline prompt. Re-reads .agents/loop.md -> loop.md -> ~/.gemini/config/loop.md -> built-in branch maintenance fallback on every tick (self-paced for /agy-loop:loop, fixed cadence for /agy-loop:loop 15m). |
| 4. One-Shot Delayed Check-In | /agy-loop:loop in 20m verify staging smoke tests/agy-loop:loop --once 10m check if docker build finished |
Schedules a single non-blocking DurationSeconds timer (max_iterations = 1), runs one isolated subagent pass when the timer fires, reports the result, and stops. |
| 5. Lifecycle & Diagnostics | /agy-loop:loop status (or list)/agy-loop:loop stop [id|all] (or cancel)/agy-loop:loop doctor [--clean-shadow]/agy-loop:loop help |
Lists active schedules & loop subagents, cancels a specific or all running loops (manage_task + manage_subagents), diagnoses (or non-destructively archives with --clean-shadow) shadow files, skills.json filters, and active loop.md resolution, or prints concise usage. |
Flags can appear anywhere in /agy-loop:loop arguments:
| Flag | Default | Description |
|---|---|---|
--max <N> |
20 (1 with --once) |
Upper bound on iterations before the loop automatically stops to protect quota. |
--stateful |
fresh |
Reuse a single loop-worker conversation ID across ticks, waking it from Idle via send_message so multi-turn debugging context persists off the main thread. |
--worktree |
inherit |
Run the worker inside an isolated Git branch/worktree (Workspace: "branch") so risky edits never touch your active checkout while you chat. |
--share |
inherit |
Run the worker inside a shared working copy (Workspace: "share"). |
--model <tier> |
flash (loop-worker) |
Override subagent model tier: inherit, flash_lite, flash, or pro. |
--self |
loop-worker |
Delegate iterations to the built-in full-capability self subagent (also auto-enabled when the prompt starts with / to invoke a nested skill like /agy-loop:loop 20m /code-review, or requires MCP tools). |
--cron |
false |
Use native 5-field CronExpression (schedule tool) when the fixed interval >= 60s maps cleanly to cron (1m, divisors of 60m or 24h, 1d). |
--exact |
false |
Set ExactTiming: true on --cron schedules to fire on exact wall-clock minutes without anti-herd jitter. |
--daemon |
false |
Set IsDaemon: true on --cron schedules for standing jobs that continue firing after the current task finishes. |
--once |
false |
Execute a single delayed run (max_iterations = 1) and exit cleanly after reporting. |
When you run bare /agy-loop:loop or interval-only /agy-loop:loop 15m (without an inline prompt), agy-loop resolves instructions on every wake-up (up to 25,000 bytes) in strict priority order:
.agents/loop.mdin the current workspace (project-scoped team or repo loop policy)loop.mdin the workspace root~/.gemini/config/loop.md(personal global maintenance defaults across repositories)- Built-in branch maintenance fallback: checks uncommitted/unfinished repo work and incremental tests, inspects open PR review comments and CI status via
ghwhen available, and reports a single green status line if clean.
Because resolution runs dynamically on every tick via skills/loop/scripts/loop-helper.sh resolve-task, you can edit .agents/loop.md while a loop is parked in the background and the updated instructions take effect on the very next wake-up without restarting /agy-loop:loop.
# Branch Maintenance Policy
1. Run `npm test` (or the fastest incremental test command for touched files).
2. If tests fail, inspect the failure, apply a minimal root-cause fix, and re-run the failing test once in this turn to verify.
3. If `gh` is authenticated and an open PR exists for the current branch:
- Check `gh pr checks` for failing CI jobs.
- Check unresolved review comments and address straightforward mechanical fixes.
4. Stop with `LOOP_STATUS: DONE` once local tests pass and all PR checks are green; return `LOOP_STATUS: BLOCKED` if an architectural decision or missing secret is required.You can stop an active loop at any time through four clean paths, in addition to built-in automatic exit conditions:
- Slash Command (
/agy-loop:loop stop) Run/agy-loop:loop stop(or/agy-loop:loop stop <taskId>//agy-loop:loop cancel) to cancel activescheduletimers/crons viamanage_task(Action="kill")and terminate any running or idleloop-workerviamanage_subagents(Action="kill"). - Conversational Stop
Tell the session in plain language:
"stop the current loop"(or"stop the loop after this iteration finishes"). - Interactive CLI TUI Panels (
/tasks&/agents)- Type
/tasks, highlight the scheduled loop timer or cron job, and presskto kill future wake-ups (xclears completed entries). - Type
/agents, highlight arunningoridleloop-worker, and presskto kill it immediately (temporary--worktreebranches are cleaned up automatically). When a worker requests permission approval, pressCtrl+Kto quick-approve orAlt+Jto teleport into its live transcript (Escreturns to main chat).
- Type
- Foreground Turn Interrupt (
Esc) PressEscto interrupt an active foreground dispatch turn immediately without closingagyCLI (pressingCtrl+Ctwice exits the CLI).
Automatic Stop Conditions: Every loop stops and clears any remaining schedule automatically when the worker returns LOOP_STATUS: DONE (objective satisfied), LOOP_STATUS: BLOCKED (human input or credentials required), or reaches --max <N> (default 20 iterations).
Antigravity loads user-level customizations in ~/.gemini/config/ ahead of installed plugins (~/.gemini/config/plugins/agy-loop/). When you install via agy plugin install https://github.com/maxlee/agy-loop, Antigravity stages the plugin without deleting pre-existing loose ~/.gemini/config/skills/loop/SKILL.md or ~/.gemini/config/agents/loop-worker.md, which otherwise override the un-namespaced loop-worker subagent (even when invoking /agy-loop:loop) and intercept /loop.
To prevent silent precedence collisions:
- Zero-Overhead
SessionStartAuto-Detector (hooks.json): Runsskills/loop/scripts/loop-helper.sh session-starton session start. When clean, it returns{}in<5msat0token cost with zero UI output. When loose shadow files exist, it displays an automatic startup alert naming the colliding paths. - One-Command Non-Destructive Cleanup: Archive colliding loose files into
~/.gemini/config/.agy-loop-backup-<timestamp>/(then run/skills reloadin any openagysession):- POSIX shell (zero Node/npm required):
sh ~/.gemini/config/plugins/agy-loop/install.sh --clean-shadow - Inside
agy(works right away via plugin prefix):/agy-loop:loop doctor --clean-shadow - Via npm CLI bridge:
npx agy-loop doctor --clean-shadow
- POSIX shell (zero Node/npm required):
| Command | Description |
|---|---|
npx agy-loop [install | update] |
Install or update agy-loop via agy plugin install (warns if user-level shadow files exist) |
npx agy-loop install --clean-shadow |
Install agy-loop and archive loose shadow files into ~/.gemini/config/.agy-loop-backup-<timestamp>/ |
npx agy-loop doctor [--json] |
Inspect agy version, plugin registration (agy plugin list --json), shadow files, skills.json include_only/exclude filters, and active loop.md (status alias supported) |
npx agy-loop doctor --clean-shadow [--json] |
Non-destructively archive loose shadow files into ~/.gemini/config/.agy-loop-backup-<timestamp>/ and re-run diagnostics (status --clean-shadow alias supported; run /skills reload in open sessions) |
npx agy-loop validate [--json] |
Run agy plugin validate --strict against the packaged plugin root |
npx agy-loop uninstall |
Cleanly remove the plugin via agy plugin uninstall agy-loop (remove alias supported) |
npx agy-loop doctor
# Archive pre-existing loose shadow files non-destructively:
npx agy-loop doctor --clean-shadow
# Machine-readable JSON output:
npx agy-loop doctor --jsonRemove agy-loop completely with a single command:
# Via npm bridge:
npx agy-loop uninstall
# Via native Antigravity CLI:
agy plugin uninstall agy-loop
# Via one-line or local POSIX uninstaller:
curl -fsSL https://raw.githubusercontent.com/maxlee/agy-loop/main/uninstall.sh | sh
./uninstall.shSee ARCHITECTURE.md for full details on the Three-Turn Reactive Lifecycle, Task & Pacing Resolution flow, 4-line Worker Output Contract, and Sandbox/Worktree isolation model.
sh -n install.sh uninstall.sh skills/loop/scripts/loop-helper.sh # Check POSIX shell syntax
npm test # Run isolated unit & integration tests
agy plugin validate --strict . # Strict Antigravity v1 plugin check (0 findings)Distributed under the MIT License. Copyright © Max.