Experimental Settings → Experimental → Flows
Agentic coding workflows that loop until the tests pass
Write your way of working down once. Foreman runs it on every task: plan, build, check, fix, review, and then it stops and waits for you.
Foreman is a free, open-source desktop app for macOS and Windows that runs AI coding agents in parallel. Claude Code, Codex, Cursor and OpenCode each work in their own git worktree on their own branch, while you review diffs, answer questions and open pull requests from one window.
macOS & Windows · Apache-2.0 · No account · v1.2.4
[edges]
plan = "implement"
implement = "checks"
checks = { passed = "review", failed = "implement" }
review = { clean = "ship-check", findings = "implement" }
ship-check = { continued = "pr", sent-back = "implement" }
[loops.fix-until-green]
over = ["implement", "checks"]
at_most = { iterations = 4, minutes = 45 }Run one. Watch it loop.
Press Run flow. The checks fail, the agent goes round again, the review comes back clean, and the run stops at the gate until you answer. It's simulated here, step for step as the app records it.
Plan, build, loop on the checks until they pass, get a clean review, then ask you before a draft PR.
task = "Keep returnTo after sign-in"
Ready · 6 steps · 2 loops · 1 gate
- fix-until-green · at most 4 iterations · 45 min
- review-until-clean · at most 2 iterations
Gate · ship-check · waiting for you
The review is clean. Open a draft PR?
Send back adds a note: Also send an expired token to /login.
Run ledger
00:00- Press Run flow. Each step writes one line here: what it was, how it ended and what it changed. Later steps and loops read it.
.foreman/flows/fix-until-green.tomlShow the flow file
# .foreman/flows/fix-until-green.toml (simplified for this page)
name = "Fix until green"
description = "Plan, implement, fix what fails, review, then ask before a draft PR."
[inputs]
task = "What to build or fix"
[start]
step = "plan"
[steps.plan]
kind = "turn" # an agent turn in the flow's workspace
persona = "architect" # read-only: plans, never edits
prompt = "Research how to do this and write a plan. Don't change any files yet. {{task}}"
[steps.implement]
kind = "turn"
persona = "developer"
prompt = "Implement the plan. Address what failed or what you were sent back for."
context = ["plan.answer", "checks.results"]
[steps.checks]
kind = "checks" # the repo's approved check commands, never an agent
[steps.review]
kind = "review" # a read-only reviewer tab reads the diff
persona = "qa-engineer"
context = ["diff"]
[steps.ship-check]
kind = "gate" # a person decides before anything leaves the computer
show = ["diff", "checks.results"]
ask = "The review is clean. Open a draft PR?"
[steps.pr]
kind = "pr"
draft = true
body = "{{ledger}}"
[edges]
plan = "implement"
implement = "checks"
checks = { passed = "review", failed = "implement" }
review = { clean = "ship-check", findings = "implement" }
ship-check = { continued = "pr", sent-back = "implement", stopped = "done" }
pr = { opened = "done" }
[loops.fix-until-green]
over = ["implement", "checks"]
at_most = { iterations = 4, minutes = 45 }
iteration = "same-tab" # or "compact-when-full" or "fresh-with-summary"
[loops.review-until-clean]
over = ["review", "implement", "checks"]
at_most = { iterations = 2 }
[after]
workspace = "keep"
foreman flow run fix-until-green --input task="make the tests pass" --wait01 · The idea
What is an agentic coding workflow?
An agentic coding workflow is a fixed procedure that coding agents follow step by step: who plans, who builds, which checks must pass, who reviews, and where a person decides. In Foreman it's a flow, a graph of agent steps that runs the same way every time.
Write a way of working down once as a graph of agent steps: loops that run until the checks pass or a review comes back clean, and gates where you decide. A flow names its steps, says which fact chooses the next one, and bounds its loops. It has no expressions and no scripting language, on purpose: the facts it branches on are the ones Foreman already knows.
turnAn agent turn, with a persona and a prompt.checksYour repo’s approved check commands. Never an agent.reviewA read-only reviewer reads the diff: clean or findings.gateYou decide: continue, send back with a note, or stop.prPushes the branch and opens a draft pull request.waitWaits on the pull request’s CI or its review.decideAn agent picks one of the options the flow names.scriptRuns a saved command. Deterministic, no model.workspaceA fresh worktree from the base branch or a step’s end.pickYou choose between two results built side by side.
02 · The case for loops
Why do loops beat one-shot prompts?
A one-shot prompt ends when the agent says it's done. A loop ends when a fact says so: the checks pass, the review comes back with no findings, or a bound is hit.
- youmake the tests pass
- agentDone! All tests pass now.
- you
npm test - npm
✕ 2 failing
implementdeveloperchecksfailed · 2 testsimplementiteration 2 of at most 4checkspassedreviewcleanship-checkwaiting for you
Stop on facts, not on prose
Edges branch on what a step produced:
passed,failed,clean,findings. Never on the agent's words.Every loop is bounded
Iterations, minutes and cost, whichever comes first. A bound that ends a loop ends the run as stopped, never as completed.
Memory between rounds
A run ledger records each step: what it was shown, how it ended, what it changed. A loop can continue the same chat, compact it, or start fresh with the ledger.
Cheaper steps
An agent handed one job inside a fixed procedure can often run on a smaller model. Each step can name its own agent, model and effort.
03 · In the box
Which flows ship with Foreman?
Eleven built-in flows and ten personas. Each flow has bounds on every loop and a gate before anything leaves your computer. Start from one, copy it, change a step.
- 01
fix-until-greenImplement, run the checks, fix what fails, review until clean, then ask before shipping.
- 02
research-then-implementAn architect plans, you check the plan, a developer builds until the checks pass, QA reviews.
- 03
test-firstFailing tests first, a check that they really fail, then the change.
- 04
issue-to-draft-prResolved, reviewed, committed after you look, then a draft pull request, with CI fixed until green.
- 05
second-opinionOne plan built in two workspaces on two loadouts, then you pick the one to keep.
- 06
two-reviewersQA, then security, both clean on the same tree before you see it.
- 07
keep-branch-freshFor a schedule: merge origin/main, fix what fails, push after you look.
- 08
flaky-test-triageRuns your saved flaky-tests command, then quarantines a flaky test or fixes a real failure.
- 09
document-what-changedA docs writer updates the docs, then QA checks they match the diff.
- 10
worth-buildingA research report, three rounds of two independent reviews and a consensus, then you decide.
- 11
idea-to-featureRequirements, design, build and QA, each with a gate to iterate.
Who works each step? Personas.
A persona is the role a step plays, written once as a markdown file and reused across flows. Its worth is in its constraints, not its title: what it may edit, what it is shown and how it must end. Foreman enforces them.
architectPlans. Read-only, ends at a gate.developerBuilds, and reports when it is done.qa-engineerFinds problems. Never fixes them.designerReads before-and-after screens.product-managerDecides whether and what, never how.ux-designerTurns requirements into a design spec.security-reviewerRead-only. Ends with findings.docs-writerWrites only under docs/.researcherWrites a report under docs/research/.research-reviewerReviews a report on its own.
04 · Where it lives
Where does a flow live?
In a TOML file beside your repository, .foreman/flows/<name>.toml, committed and reviewed like code. Personal flows live in the app. Either way you can read every step before it runs.


- Start from a built-in. Copy it to personal and change a step.
- Ask the assistant. Say who does what; it drafts the flow and you apply it or don't.
- Make a flow from this. Turn a chain of work you did by hand into a draft flow.
- Run it anywhere. From Automations, New workspace, a schedule or
foreman flow run.
05 · Guard rails
Can I trust agents to loop on their own?
You don't have to: a flow can't do anything its steps couldn't do alone, every loop is bounded, and a gate stops the run until you answer. Each run works in its own git worktree, so your checkout never moves.
- GatesA gate shows the diff, the check results or a file, and offers Continue, Send back with a note, or Stop. Your phone can answer it too.
- Unattended turnsTurn steps run on Claude Code unattended. Any approval nobody planned for is denied, and any question stops the run for you.
- ReviewsReview and decide steps can run on Codex, read-only. An approval they ask for waits for you.
- Scoped writesA persona's
writesis enforced by Foreman, not the prompt: a docs-writer edits onlydocs/. - ApprovalStarting a flow approves exactly what it runs. Change the flow, a persona or a command and Foreman asks again.
- LocalRuns happen on your computer while Foreman runs. The ledger stays in Foreman, never in your repo.
06 · Around the flow
What else does Foreman do?
Everything a flow stands on works by hand too: one worktree per agent, diffs to review, approvals that spell it out and a command line for all of it.
One worktree per agent
Every workspace is its own git worktree on its own branch. Agents never step on each other, and your main checkout stays clean.
Watch them all at once
Tiles shows several workspaces side by side so you can step in where you are needed. Built for 10 to 12 agents running at once.
Review every change
Read each change as a diff before you commit, push or open a pull request. Checkpoints let you rewind a workspace to any turn.
Approvals that spell it out
An approval breaks a command down part by part, marks anything that leaves your computer, and says exactly what Always allow adds.
A real command line
Almost everything in the window works from a terminal with the foreman command. Every command takes --json and exit codes are stable, so scripts and CI can rely on them.
Automations and schedules
Save prompts as templates and run them on demand or on a schedule: hourly, daily, weekly or monthly, in your time zone. Run Foreman without a window, or at login, and schedules keep going.
07 · Compared
How is Foreman different from Conductor and T3 Code?
All three run agents in their own git worktrees. Foreman adds flows that loop until checks pass with human gates, and it's open source under Apache-2.0 on macOS and Windows.
—A dash means not listed on their site
| Feature | Foreman | Conductor | T3 Code |
|---|---|---|---|
| Open source | Apache-2.0 | No | MIT |
| macOS | Yes | Yes | Yes |
| Windows | Yes | Mac only | Yes |
| One git worktree per agent | Yes | Yes | Yes |
| Agents | Claude Code, Codex, Cursor, OpenCode, any ACP agent | Claude Code, Codex, Cursor | Claude Code, Codex and more |
| Flows that loop until checks pass, with human gates | Yes | — | — |
| AI employees with git-backed memory | Yes | — | — |
| Scheduled automations and auto-fix CI | Yes | — | — |
| Your own cloud sandboxes (E2B, Daytona, Vercel, Docker) | Experimental | — | — |
| Scriptable CLI, --json on every command | Yes | — | — |
| Approve from your phone | Yes | — | Yes |
| No account, no telemetry upload | Yes | — | — |
08 · Start
Get started in a minute
Download, add a repository, and run your first flow from the window or a terminal.
- Download ForemanFor macOS (Apple Silicon) or Windows. Git on your PATH is all it needs.
- Add a git repo and sign in an agentYour own Claude Code, Codex, Cursor or OpenCode login or API key.
- Create workspacesOne per task, each its own worktree. Switch on Flows and pick a flow under Start with.
# Loop until the checks pass
$ foreman flow run fix-until-green --input task="make the tests pass" --wait
# See what is waiting for you
$ foreman approvals
# Open a draft pull request
$ foreman pr create atlas --draft
09 · FAQ
Questions developers ask
What is Foreman?
Foreman is a free, open-source desktop app for macOS and Windows that runs AI coding agents in parallel. Claude Code, Codex, Cursor and OpenCode each work in their own git worktree on their own branch, while you review diffs, answer questions and open pull requests from one window.
Is Foreman free and open source?
Yes. Foreman is free and licensed under Apache-2.0, with the full source on GitHub at github.com/elite-build/foreman. There is no paid tier, no account and no Foreman cloud service.
Which coding agents does Foreman support?
Foreman runs Claude Code, Codex, Cursor and OpenCode, plus any agent that speaks the Agent Client Protocol (ACP). Each agent signs in with your own subscription or API key, set in Settings → Agents.
How do I run multiple Claude Code agents in parallel?
Add a git repository to Foreman and create one workspace per task. Each workspace is a separate git worktree on its own branch, so several Claude Code sessions edit the same repository at once without conflicts. Tiles shows them side by side.
Why does each agent need its own git worktree?
A git worktree is a second checkout of the same repository on a different branch. Giving each agent its own worktree means agents never overwrite each other's files, every change lands on a reviewable branch, and your main checkout stays untouched.
Does my code leave my computer?
Only through the agents you choose. Foreman runs locally with no account and no telemetry upload; your agents talk to their own model providers. In your own workspaces, an approval marks any command that leaves your computer before it runs, and AI employees hold Slack posts and Linear changes for you.
Do coding agents need my approval for every command?
Only if you want them to. Approvals are a setting: with Claude Code tool approvals on (Settings → Account), each command is spelled out part by part before it runs, anything that leaves your computer is marked, and Always allow shows exactly what it adds. Every agent still works in its own worktree, and checkpoints rewind any turn.
Which operating systems does Foreman run on?
Foreman runs on macOS (Apple Silicon, signed and notarized) and Windows. You need Git on your PATH and a login or API key for at least one agent.
Can Foreman run coding agents on a schedule?
Yes. Any saved prompt template can run hourly, daily, weekly or monthly in your time zone, and opt-in auto-fix sends failing CI logs to your agent. Scheduled runs use Claude Code and happen while Foreman is running, which can be without a window or from login.
Can I control Foreman from my phone?
Yes. Pair a phone with a QR code to answer approvals, steer agents, comment on diffs and read terminals, live. On the same Wi-Fi it connects directly, and anywhere else through your own Tailscale network. Native iOS and Android apps are coming soon.
Can coding agents run in a cloud sandbox like E2B?
Yes, as an experiment. A workspace's worktree and agent can run in a sandbox on your own E2B, Daytona, Vercel Sandbox or Docker account, for Claude Code, Codex and OpenCode. Provider keys stay on your computer and never go into the sandbox.
Which integrations does Foreman have?
GitHub (pull requests, merges, CI and reviews), GitLab, Linear, Slack and Langfuse, plus MCP. Each connection has a default per service, each repository can pick its own, and you choose what agents may do with it: nothing, read, or read and write.
How is Foreman different from Conductor?
Foreman is open source under Apache-2.0 and runs on Windows as well as macOS, while Conductor is a closed-source Mac app. Foreman also drives OpenCode and any ACP agent, and adds flows that loop until checks pass, AI employees and a scriptable command line.
How is Foreman different from T3 Code?
Both are open-source GUIs for coding agents. Foreman adds flows (agent graphs that loop until tests pass, with human gates), AI employees with a git-backed memory, a foreman CLI where every command takes --json, phone approvals and remote sandboxes.
Can I script Foreman or use it in CI?
Yes. The foreman command starts workspaces, sends messages, answers approvals, opens and merges pull requests and runs flows. Every command takes --json and exit codes are the same for every command.
Fork a flow. Send it back.
Foreman is three weeks old: 31 releases since 1.0.0, all in the open under Apache-2.0. The built-in flows and personas are plain files in the repo. Read them, star the project, fork it, and open a pull request when yours loops better.