agy-foreman MCP server
Commit Oct 30, 2026Delegates complex tasks from Claude Code to Gemini 3.8 Flash using the Antigravity CLI with automated testing and git worktree isolation.
Also known as mountaser/agy-foreman
- Stars
- 6
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- MIT
What is agy-foreman MCP?
agy-foreman delegates complex tasks from Claude Code to Gemini 3.8 Flash using the Antigravity CLI with automated testing and git worktree isolation. It exposes 4 tools, such as agy_status, agy_start, agy_get.
Summary generated from the project's README
About agy-foreman MCP server
Delegating complex coding tasks from Claude Code to Gemini 3.8 Flash is what agy-foreman enables for developers seeking automated, CI-style execution. By using the Antigravity CLI in headless mode, the server manages tasks within isolated git worktrees to ensure changes do not interfere with your main environment. It functions as a bridge that hands off specific implementation or exploration jobs to Gemini, then subjects the results to your local test suite before any code is merged.
To use this server, you need Node 20 or newer, git 2.38 or newer, Claude Code, and an active Antigravity CLI login via your Google account. The system integrates with existing workflows like Superpowers plans or OpenSpec changes, using task sections or markdown checklists to define the work. It provides specialized tools such as agy_start for initiating jobs, agy_status for monitoring progress, and agy_act to finalize results or record lessons from failures. This setup ensures that only branches passing your defined test_command are squashed and merged back into your repository.
What you can do with it
- 1Automated task delegationHand off a specific task from a markdown plan file to Gemini for implementation.
- 2Isolated code executionRun complex coding changes in a separate git worktree to prevent workspace pollution.
- 3Verified code mergingEnsure that any code generated by an AI agent passes your local test suite before it is merged.
- 4Learning from failuresAutomatically record lessons from failed jobs to improve future task performance.
Written from the project's README. Every use case is checked against a quote from it.
agy-foreman MCP tools 4
Detected from the READMEagy_statusagy_startagy_getagy_act
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemountaser/agy-foreman is public and reachablegithub.com/mountaser/agy-foreman ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/mountaser/agy-foreman ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagy-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)]
- Start: Claude calls
agy_startwith a task and a token estimate; jobs that are cheaper to do directly are refused. - Approve: one card per plan, valid for 24 hours or until the plan file changes.
- Isolate: a git worktree, your setup command, and contract tests that must fail before Gemini starts.
- Gate: a hook decides every tool call; your global agy settings can't widen it.
- Run: Gemini runs headless; if the quota runs out, you choose retry, continue without Gemini, or wait.
- Verify: protected files are restored, then the tests run and the counts and git state are checked for tampering.
- 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 yourtest_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_geton a finished job returns a short record withunchanged: true; ask fordiff_modeto 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
timeoutwithpartial: trueand averifyreport, 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 aspassed("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 reportshows 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,mediumorhigh. 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
agyused in the tests are adapted from it.
The license notices for both are in NOTICE.
License
MIT © 2026 Mountaser Halak
agy-foreman MCP questions
What tools does agy-foreman MCP provide?
It exposes 4 tools, including agy_status, agy_start, agy_get, agy_act.
Does it work on Windows?
Yes, it runs end to end on Windows, Linux, and macOS.