Skip to content

Describe it. Get a blueprint. Then build.

An AI agent workflow builder that draws the plan before the crew starts

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. Its flows turn “who does what” into a plan you can read, run and review in a pull request.

  • macOS & Windows
  • Apache-2.0
  • No account
  • Flows: experimental
A flow's graph of steps, loops and a gate, with the assistant under it
Fig. 1 The real flow studio: a built-in flow's steps, loops and gate, with the assistant under it.

Sheet A-101 Try it here

Draw the blueprint

Say who does what. The plan redraws as you go: every step a room, every loop a dimension with its bound, your gate a door. Then press Run it and walk the crew through. Simulated here, step for step as a flow runs in Foreman.

Start from a built-in flow

⁠, ⁠, ⁠, ⁠, ⁠.

Tap any underlined part to change it.

A flow of your own. Closest built-in: research-then-implement. Ask the assistant and it drafts this file for you.

Ready · 7 rooms · 3 loops · 1 gate

IN · {{task}}OUT · done01planarchitect · read-onlyTURN · CLAUDE CODE02implementdeveloper · edits the worktreeTURN · CLAUDE CODE03checksnpm test · tsc · lintCHECKS · NO AGENT04reviewqa-engineer · read-onlyREVIEW · CLAUDE OR CODEX05pr-checkyou · open a draft PR?GATE · YOU06prdraft · Foreman pushes and opens itPR · NO AGENT07ciwaits for CI: green or failedWAIT · ON = "CI"≤ 4 roundson failed · 45 min≤ 2 roundson findings≤ 2 roundson failed CIsent backJOB
IN · {{task}}OUT · done01planarchitectTURN · CLAUDE CODE02implementdeveloperTURN · CLAUDE CODE03checksnpm test · lintCHECKS · NO AGENT04reviewqa-engineerREVIEW · CLAUDE OR CODEX05pr-checkyou decideGATE · YOU06prdraft · no agentPR · NO AGENT07ciwaits for CIWAIT · ON = "CI"≤ 4 roundson failed≤ 2 roundson findings≤ 2 roundson failed CIsent backJOB

.foreman/flows/my-blueprint.toml Simplified for this page

# .foreman/flows/my-blueprint.toml · simplified for this page
name = "My blueprint"
description = "The architect plans, the developer builds, the checks run until green, at most 4 rounds, the QA engineer reviews until clean, and I approve before a draft PR."

[inputs]
task = "The issue to resolve: its link or its words"

[start]
step = "plan"

[steps.plan]
kind = "turn"
persona = "architect"          # read-only: plans, never edits
prompt = "Research how to do this and write a plan. Don't change any files yet. {{task}}"
context = ["task", "tree"]

[steps.implement]
kind = "turn"                  # code steps run on Claude Code
persona = "developer"
loadout = 1
prompt = "Implement the plan."
context = ["plan.answer"]

[steps.checks]
kind = "checks"                # the repo's approved check commands, never an agent

[steps.fix]
kind = "turn"
same_tab = "implement"
prompt = "Address what failed or what you were sent back for, and run the checks again."
context = ["checks.results"]

[steps.review]
kind = "review"                # read-only: Claude Code or Codex
persona = "qa-engineer"
                               # its default loadout 3 is Codex
context = ["diff"]

[steps.address]
kind = "turn"
same_tab = "implement"
context = ["review.findings"]

[steps.pr-check]
kind = "gate"                  # you: Continue, Send back or Stop
show = ["diff", "checks.results", "review.findings"]
ask = "Open a draft PR?"

[steps.pr]
kind = "pr"                    # Foreman pushes and opens it, no agent
draft = true
body = "{{ledger}}"

[steps.ci]
kind = "wait"
on = "ci"

[steps.fix-ci]
kind = "turn"
same_tab = "implement"
prompt = "CI failed on the pull request. Fix it, commit and push."

[edges]
plan      = "implement"
implement = "checks"
checks    = { passed = "review", failed = "fix" }
fix       = "checks"
review    = { clean = "pr-check", findings = "address" }
address   = "checks"
pr-check  = { continued = "pr", sent-back = "address", stopped = "done" }
pr        = { opened = "ci" }
ci        = { green = "done", none = "done", failed = "fix-ci" }
fix-ci    = "ci"

[loops.fix-until-green]
over = ["checks", "fix"]
at_most = { iterations = 4, minutes = 45 }
iteration = "same-tab"         # or "compact-when-full" or "fresh-with-summary"

[loops.review-until-clean]
over = ["review", "address", "checks"]
at_most = { iterations = 2 }

[loops.ci-until-green]
over = ["ci", "fix-ci"]
at_most = { iterations = 2 }

[after]
workspace = "keep"             # keep | archive | delete-unchanged
Project
atlas
Flow
my-blueprint
Drawn by
the assistant
Checked by
you
Revisions
  1. A first drawn

Scale: 1 step = 1 room · persona hats drawn for this page

Site log fix-login-redirect

  1. 00:08architect: a 3-step plan · the cookie is set after the redirect in src/auth/session.ts
  2. 00:45developer: moved the redirect after setSession() · +12 −3
  3. 01:22checks: ✕ auth/redirect.test.ts › keeps returnTo after sign-in
  4. 01:59developer (fix, same tab): kept returnTo on the refresh path · +4 −1
  5. 02:36checks: ✓ 214 tests · types · lint
  6. 03:13qa-engineer: clean, no findings
  7. 03:50pr-check: waiting for you · open a draft PR?

Illustrative run of the sentence above. In Foreman the Flow tab draws it live, and the gate waits in Needs you.

Legend

  • A room is a step: a turn, checks, a review, a gate or a PR
  • A loop, with its bound and the fact that sends it round
  • Sent back from your gate, with your note
  • Your gate is a door: nothing passes until you open it
  • The job, walking from room to room on a run

Sheet A-102 Describe it

How does the assistant draft a flow from a sentence?

Describe who does what and Foreman's assistant drafts the flow, plus a persona for any role that has none, on a Run card. Nothing is saved or run until you click Run.

  1. Say it plainly. Name the roles, the models if you care, and where you want to look.
  2. Read the drawing. In the flow studio its proposals show as changes on the graph, applied only if you want them.
  3. Click Run, or don't. The card carries the whole file: foreman flow add --toml "…".

The assistant runs on Claude Code today, the one agent whose turn can be held to the assistant's own tools.

Assistant Illustrative

Fable researches, Opus implements, Sonnet writes the PR text, and ask me before implementing.

Drafted research-implement-pr: 5 steps, 1 loop, 2 gates. The checks loop at most 4 rounds; you look after the research and before the PR.

Run this?

foreman flow add --toml "name = \"Research, implement, PR\" …"

CancelRun

nothing saved yet

Sheet A-201 The crew

Which personas can a flow step use?

Ten ship with Foreman, from architect to research-reviewer. A persona is a role with limits: what it may write, what it's shown and how it ends. The limits on writes are enforced, not suggested.

Crew schedule10 personas · built in

The ten personas Foreman ships, with their role and where each may write
MarkPersonaRoleMay write
architectPlans the change without making it, from the task and the tree.Nothing: read-only
developerMakes the change and gets the checks passing.The worktree
qa-engineerReviews the change against what was asked; finds problems, never fixes them.Nothing: read-only
designerReviews what the change looks like, from the diff and before-and-after screens.Nothing: read-only
product-managerDecides whether and what to build, never how; writes the requirements.docs/features/** only
ux-designerTurns requirements into a design specification; writes no code.docs/features/** only
security-reviewerReviews the change for security problems; never fixes them.Nothing: read-only
docs-writerUpdates the documentation for what the diff changed; never code.docs/** only
researcherStructures and writes a research report on an idea, and revises it in place.docs/research/** only
research-reviewerReviews a research report for soundness, alone.Nothing: read-only

Write your own in .foreman/personas/*.md, reuse a Claude subagent from .claude/agents/, or ask the assistant to draft one. A persona hat colour is this page's drawing convention.

Sheet A-301 Details

Why do the loops stop on facts, not on an agent saying it's done?

Because “done” from an agent isn't evidence. A flow's edges branch only on facts Foreman records: the checks passed or failed, a review came back clean or with findings, a gate was continued, sent back or stopped.

  1. Detail 1

    Every loop has bounds

    A loop names its steps and its limits: iterations, minutes, cost (only Claude reports cost) or a context window past a threshold. A bound that ends a loop ends the run as stopped, never as completed.

  2. Detail 2

    Gates are where you decide

    A gate stops the run in Needs you with the diff, the check results or a file to read. Continue, Send back with a note, or Stop: in the window, on your phone, or with foreman approve <id> --continue.

  3. Detail 3

    Who runs which room

    Steps that write code run on Claude Code, the one agent Foreman runs unattended. Review and decide steps can also run on Codex, read-only and attended. Checks and the PR step run no agent at all.

Sheet A-401 Specifications

Where does a flow live, and how do you start one?

A flow is a TOML file in your repository under .foreman/flows/, so a change to how your team works is a diff someone reviews in a pull request. Personal flows stay in Foreman and ask for a repository when they start.

  • Automations Pick the flow, press Run, fill in its inputs.
  • New workspace Start with: Message · Template · Flow · Issue or PR.
  • A schedule Hourly to monthly, on Claude Code, while Foreman runs.
  • A terminal foreman flow run fix-until-green --wait

Follow a run on the workspace's Flow tab: the run as a diagram through four lenses, Run, Context, Memory and Data.

Open Add a security reviewer to fix-until-green atlas #87

.foreman/flows/fix-until-green.toml +9 −1

 [steps.review]
 kind = "review"
 persona = "qa-engineer"
+
+[steps.review-security]
+kind = "review"
+persona = "security-reviewer"
 
 [edges]
-review = { clean = "ship-check", findings = "address" }
+review = { clean = "review-security", findings = "address" }
+review-security = { clean = "ship-check", findings = "address" }

kenji approved: “Security reads every change to auth from now on. Good.”

A flow run's diagram in the middle of the workspace, with its chat beside it
Fig. 2 A run on the Flow tab, in the middle of the workspace with its chat beside it.

Sheet index Built in

Which flows come built in?

Eleven, each with bounds on every loop and a gate before anything leaves your computer. They're read-only; copy one to make it yours, or run it as it is.

  1. F-01

    Fix until green fix-until-green

    Implement, run checks, fix what fails, review, stop when the review is clean, then ask before shipping.

  2. F-02

    Research then implement research-then-implement

    An architect plans, you check the plan, a developer implements and fixes until the checks pass, then QA reviews.

  3. F-03

    Test first, then make it pass test-first

    A developer writes failing tests and the checks show they fail; then makes them pass. QA reviews; you look before it ships.

  4. F-04

    Issue to draft pull request issue-to-draft-pr

    Resolve the issue until the checks pass and QA is clean; after you look, Foreman opens a draft PR, and CI failures go back until green.

  5. F-05

    Second opinion, then pick second-opinion

    An architect plans; two developers on different loadouts each build it in a workspace of their own; you pick; QA reviews; you look.

  6. F-06

    Two reviewers must agree two-reviewers

    QA, then a security reviewer, read the same tree. Any finding goes back, round again until both are clean, then you look.

  7. F-07

    Keep a long-lived branch fresh keep-branch-fresh

    Meant for a schedule: merge origin/main into the branch, resolve conflicts, fix what fails; you decide whether it is pushed.

  8. F-08

    Flaky test triage flaky-test-triage

    Runs your saved flaky-tests command; a developer decides flaky, real failure or clean, then quarantines with a note or fixes.

  9. F-09

    Document what changed document-what-changed

    A developer makes the change, a docs writer updates the docs for the diff, QA checks they match, you look.

  10. F-10

    Is this feature worth building? worth-building

    A researcher writes a report; three rounds of two independent reviews on different models and a consensus; then you read both.

  11. F-11

    From an idea to a feature idea-to-feature

    A product manager writes requirements, a UX designer the design, a developer builds until green, you look, QA reviews against both.

Drawing set On site

What else is on site?

Flows sit on top of everything else Foreman does: a worktree per agent, automations, auto-fix for CI, remote control from your phone, integrations, sandboxes and AI employees.

A-1

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.

The foundation

A-2

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.

Templates · schedules

A-3

Auto-fix CI and auto-review

Opt in and Foreman sends a failing CI log to your agent within a budget you set, and a read-only reviewer reads each finished diff. Checks can run after every turn, and a chat that hits a usage limit resumes by itself.

Opt-in · with a budget

A-4

GitHub, GitLab, Linear, Slack, Langfuse

Open, merge and auto-merge pull requests, watch CI and reviews, start work from a Linear issue, send Slack notifications and read Langfuse traces. Each connection gets the agent access you choose: nothing, read, or read and write.

GitHub · GitLab · Linear · Slack · Langfuse

A-5

Remote sandboxes: E2B, Daytona, Vercel, Docker

Run a workspace's worktree and agent in a sandbox on your own E2B, Daytona, Vercel Sandbox or Docker account. Provider keys never enter the sandbox, and turns keep going after you close the app. Experimental.

  • E2B
  • Daytona
  • Vercel Sandbox
  • Docker

A-6

AI employees

Give an organization employees with a role in plain words, a hard hat and access you approve. They work in fresh workspaces, remember through a git memory repository and hand work to each other.

15 jobs + Priya

A-7

Run it from anywhere, over your own Tailscale

Pair a phone with a QR code and answer a flow's gates, approvals and questions, live. Same Wi-Fi connects directly; away from home it goes over your own Tailscale network, with no Foreman relay.

Today: pair your phone with a QR code and add the phone view to your Home Screen.

The Automations library of templates and commands, with schedules beside it
Fig. 3 Automations: the templates Foreman ships, and schedules beside them. With Flows on it gains Flows and Personas tabs.

Schedule B Other sites

How is Foreman different from Conductor and T3 Code?

Foreman is open source under Apache-2.0 and runs on Windows as well as macOS, while Conductor is a closed-source Mac app. Of the three, only Foreman lists flows that loop until the checks pass, with gates where you decide.

A dash means not listed on their site

Foreman compared with Conductor and T3 Code
FeatureForemanConductorT3 Code
Open sourceApache-2.0NoMIT
macOSYesYesYes
WindowsYesMac onlyYes
One git worktree per agentYesYesYes
AgentsClaude Code, Codex, Cursor, OpenCode, any ACP agentClaude Code, Codex, CursorClaude Code, Codex and more
Flows that loop until checks pass, with human gatesYes——
AI employees with git-backed memoryYes——
Scheduled automations and auto-fix CIYes——
Your own cloud sandboxes (E2B, Daytona, Vercel, Docker)Experimental——
Scriptable CLI, --json on every commandYes——
Approve from your phoneYes—Yes
No account, no telemetry uploadYes——
From each project's own site as of November 2026. “—” means it isn't listed there, not that it's missing. Spot a mistake? Tell us.

Sheet S-1 Groundwork

Get started in a minute

Download the app, point it at a git repository, then give each task its own workspace, or a flow.

  1. Download Foreman

    Free for macOS (Apple Silicon) and Windows. You need Git on your PATH.

    Download Foreman
  2. Add a repo, sign in an agent

    Any git repository. Sign in Claude Code, Codex, Cursor or OpenCode in Settings → Agents with your own login or key.

  3. Create workspaces, then a flow

    One workspace per task, each a worktree on its own branch. Turn on Settings → Experimental → Flows to run one.

Run a built-in flow from a terminal
foreman flow run fix-until-green --input task="make the tests pass" --wait

# Loop until the checks pass. Gates answer with foreman approve. CLI reference

Sheet Q Site meeting

Questions developers ask

Something missing? Open an issue or read the guide.

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.

The drawings are open. Come build.

Foreman is three weeks old and has shipped 31 releases since 1.0.0 on 27 October, all in the open under Apache-2.0. Star it to hear about the next one, fork it, or pick up a first issue. A flow you'd want built in is a fine first pull request.