agy-foreman

Hand plan tasks from Claude Code to Gemini 3.8 Flash as headless, CI-style runs of the Antigravity CLI, and merge only what passes your tests.

agy 🟢🟢🟢🟢🟢🟢🔵 6/7 tasks · #7 You shall not pass · › running · 42 tool calls · plan 41m07s

The Claude Code status line while Gemini works on the last task of a plan. Each task gets a marker: done, running, failed or not started.

agy-foreman lets Claude Code hand tasks from a plan to Gemini 3.8 Flash through Google's agy CLI. Each task runs in agy's headless mode, which Google's docs describe for scripting and CI, and is treated like a CI job: one non-interactive agy -p run with a fixed brief, in its own git worktree. The server then runs your tests on the result, and only branches that pass get merged.

It works with plans written by Superpowers and changes written with OpenSpec, as well as one-off tasks.

Status: v0.1, pre-release. It runs end to end on Windows, Linux and macOS.

Works with your plans

agy-foreman reads the plan file you already have and runs one task per job:

| Plan source | File | A task is | | ------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------- | | Superpowers writing-plans | any .md plan | a ### Task 3: … section | | OpenSpec change | openspec/changes/<name>/tasks.md | a ## 3. … section with its - [ ] 3.1 items | | none | none | a task description passed to agy_start |

For Superpowers plans, test code blocks in a task become the contract tests, and the Create: / Modify: file lists become Gemini's checklist. For OpenSpec changes, the open - [ ] items do that job, and the change's proposal.md, design.md and specs/ are added to Gemini's brief, so it gets the context even when the change folder isn't committed yet.

Quick start

You need Node 20 or newer, git 2.38 or newer, Claude Code, and the Antigravity CLI (agy) logged in to your Google account.

npm install -g agy-foreman

Set up a repository you want to use it in:

cd your-repo
agy-foreman init           # config + status line
agy-foreman doctor         # checks node, git, agy login
agy-foreman install-skill  # teaches Claude to delegate
claude mcp add agy-foreman -- agy-foreman serve

On Windows, register it as claude mcp add agy-foreman -- cmd /c agy-foreman serve.

Restart Claude Code and ask it to run a plan, for example: "Run task 3 of docs/plans/auth.md with Gemini." You get one approval card for the plan. Later tasks run without asking until the plan file changes.

How it works

flowchart LR
    C[Claude Code] -- agy_start --> J[JobManager]
    J -- approval card<br/>once per plan --> U((You))
    J --> P[Pipeline]
    subgraph P[Pipeline: one job]
      direction TB
      W[worktree + setup] --> R[contract tests<br/>must fail] --> B[brief + skills<br/>+ tool-call gate] --> A[agy -p<br/>Gemini 3.8 Flash] --> V[server-side verify] --> M[commit + merge check]
    end
    P -- envelope --> J
    J -- wake --> C
    C -- agy_act finalize --> G[(your branch)]

1. Start: Claude calls agy_start with a task and a token estimate; jobs that are cheaper to do directly are refused.
2. Approve: one card per plan, valid for 24 hours or until the plan file changes.
3. Isolate: a git worktree, your setup command, and contract tests that must fail before Gemini starts.
4. Gate: a hook decides every tool call; your global agy settings can't widen it.
5. Run: Gemini runs headless; if the quota runs out, you choose retry, continue without Gemini, or wait.
6. Verify: protected files are restored, then the tests run and the counts and git state are checked for tampering.
7. Merge: Claude reviews the result and squashes the branch.

When a job fails, the failure is recorded as an incident and Claude writes a one-line lesson. Lessons that match a new task are added to its brief. A lesson that shows up three times is offered to you as a permanent rule for the skill.

Reference

MCP tools

| Tool | Purpose | | ------------ | -------------------------------------------- | | agy_status | Running jobs, cooldown, top lessons | | agy_start | Start an implement or explore job | | agy_get | Progress or the final result | | agy_act | Finalize, follow up, cancel, record a lesson |

CLI

| Command | Purpose | | --------------------------------- | -------------------------------------------------------------------- | | serve | The MCP server (default) | | wait <job> | Block until a job ends | | watch [job] | Live progress in a terminal | | apply <plan> <step> | Write a plan step's full-code files and run the tests (--dry-run) | | report | What the jobs cost: states, tokens, incidents (--since YYYY-MM-DD) | | statusline | Add the claude-gauges status line | | init, doctor, install-skill | Setup |

Configuration

init creates .agy-foreman.json in the repo root:

{
  "test_command": [
    "npx",
    "vitest",
    "run",
    "--reporter=default",
    "--reporter=junit",
    "--outputFile.junit=reports/junit.xml"
  ],
  "test_report": "reports/junit.xml",
  "setup_command": ["npm", "ci"],
  "allowed_commands": ["npm run typecheck", "npx prettier"],
  "protected_paths": ["test/**", "**/*.test.*"]
}

| Key | Default | Meaning | | -------------------- | ------------- | --------------------------------------------- | | test_command | none | Command the server runs to verify | | test_report | none | JUnit report for test counts | | setup_command | none | Runs in each new worktree | | allowed_commands | [] | Extra commands Gemini may run | | unknown_commands | deny | deny, allow or ask_user | | protected_paths | test globs | Files Gemini may not change | | approval | per_plan | per_plan or per_task | | effort | high | low, medium or high | | max_concurrent | 2 | Jobs at once | | max_runs_per_hour | 10 | Hourly cap | | refuse_ratio | 1.5 | When delegating costs more than doing it | | allowed_mcp, web | [], false | MCP tools and web access for Gemini | | gate | elicitation | client if your client has no approval cards |

Saving tokens

• Steps that already contain their code. If a plan step spells out the files and tests in full, do not delegate it: agy-foreman apply <plan> <step> writes the files and runs your test_command. It only creates files, and refuses anything ambiguous ("append to", two blocks for one path, a path that exists) without writing a byte.
• Repeat reads are short. A second agy_get on a finished job returns a short record with unchanged: true; ask for diff_mode to get the full one. Denied commands are capped at five entries.
• Timeouts keep the work. A timed-out run is still verified: the result is timeout with partial: true and a verify report, so finished work is visible. A run that goes quiet for 300 s (AGY_STALL_SEC) with no tool step running is stopped; if the tests pass it ends as passed ("ended early"). The default timeout is three times the median passed run, between 10 and 30 minutes, once ten jobs have passed.
• Second strike. Each result carries attempt; a failed or timed-out second try adds a hint to take the work back.
• A service error (503 and the like) after real work is resumed once automatically.
• agy-foreman report shows where the tokens went.

Status line

agy-foreman does not draw its own status line. claude-gauges shows your jobs, the Gemini quota, your Claude limits and the cache timer under the Claude Code prompt, and reads the status file below. Run agy-foreman statusline to install it: it asks first, downloads the release for your system and checks its SHA-256. agy-foreman statusline --manual prints the install commands instead.

Status file

While jobs run, agy-foreman keeps status.json in its state folder up to date (%LOCALAPPDATA%gy-foreman on Windows). Status lines can read it to show progress; the format is described in docs/superpowers/specs/2026-10-30-status-snapshot-design.md.

Limitations

• Gemini 3.8 Flash only, with effort low, medium or high. Other models in agy need plans that this project doesn't target.
• Implement jobs need a test command. Without a machine check there is nothing to verify, so the skill tells Claude not to delegate.
• agy starts your global agy MCP servers on every run. The gate denies Gemini access to them, but they still start up. agy has no per-run switch to turn this off.

Terms of service

agy-foreman is not affiliated with Google.

It uses agy the way Google describes headless mode: for scripting and CI. Every task is one non-interactive run with a fixed brief in a throwaway git worktree, and the result is checked by your test suite, like a CI job. It never touches your login and never switches accounts.

Google's FAQ also says wrapping agy in third-party agents isn't supported on consumer plans. If you want to be fully covered, use it with a Gemini Enterprise account.

agy-foreman is provided as is under the MIT license. You're responsible for how you use it with your Google account.

Development

src/
├── agy/        run(request) → Outcome: spawns agy -p, parses stream-json, detects quota, kills the process tree
├── pipeline/   runJob(spec) → Envelope: worktree, contract tests, gate and hook, guard, verify, report
├── jobs/       JobManager: approval, token gate, queue, quota card, progress, ledger, lessons
├── apply/      `apply`: write a plan step's full-code files, then run the tests
├── snapshot/   builds and writes status.json for status lines
├── gauges/     verified download and install of claude-gauges
├── report.ts   `report`: what the jobs cost
├── server.ts   the four MCP tools
└── cli.ts      serve, wait, watch, apply, report, statusline, init, doctor, install-skill
skills/gemini-delegation/   the skill (SKILL.md and 7 references)

npm ci
npm test            # unit and integration tests with the fake agy; CI runs them on Windows, Linux and macOS
npm run test:ci     # typecheck, formatting check, then the tests (what agy-foreman runs to verify its own jobs)
npm run test:live   # one small real agy call (uses a little quota)

Contributing

Bug reports and pull requests are welcome. For bigger changes, please open an issue first so we can talk it through.

Before you send a PR, run npm run test:ci (typecheck, formatting and tests), and add a test if you're fixing a bug.

Credits

• agy-bridge by Shahzaib (MIT): agy-foreman started as a fork of it.
• claude-agy-mcp by elkaix (MIT): the stream-json parser and the fake agy used in the tests are adapted from it.

The license notices for both are in NOTICE.

License

MIT © 2026 Mountaser Halak