Skip to content

ENG-142 One project, start to ship

From a Linear issue to a pull request, with a whole AI crew.

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

The route

How does an AI crew take a Linear issue to a pull request?

In Foreman it takes seven moves: draw the way of working as a flow, staff it, give the agents the Linear issue, build each part in its own git worktree, send the slow tests to a sandbox, put upkeep on a schedule, and have reviewers read the result before a draft pull request opens.

This page follows one made-up issue, ENG-142, through all seven. Every module below is live. Use them in order and the docket fills in; skip around and it still keeps count.

fix-until-green · 6 steps · 2 loops · 1 gate
A flow run's diagram in the middle of the workspace, with its chat beside itThe drawing's stamp. Press to stamp it again.
  • I build it, then fix it until the checks pass.
  • I read every change for holes. I never patch them.
  • I find problems. Fixing them isn't my job.
  • Nothing ships until I open the gate.
Fig. 1A run of Fix until green on the Flow tab, completed, with the workspace and its chat beside it.

01 Draw it Experimental

How do you tell an AI crew the way to work?

Draw it as a flow: a graph of agent steps with loops that run until the checks pass and a gate where you decide. issue-to-draft-pr is one of 11 flows that ship with Foreman: it resolves the issue until the checks pass and QA is clean, waits for you, then opens a draft PR itself.

  • Settings → Experimental → Flows
  • Every loop has a bound
  • Branches on facts, not on an agent's word

Try it: tap an underlined word to redraw the plan, or press Run it and answer the gate.

Start from a built-in flow

⁠, ⁠, ⁠, ⁠, ⁠.

Tap any underlined part to change it.

Matches the built-in flow issue-to-draft-pr.

Ready · 6 rooms · 3 loops · 1 gate

IN · {{task}}OUT · done01implementdeveloper · edits the worktreeTURN · CLAUDE CODE02checksnpm test · tsc · lintCHECKS · NO AGENT03reviewqa-engineer · read-onlyREVIEW · CLAUDE OR CODEX04pr-checkyou · open a draft PR?GATE · YOU05prdraft · Foreman pushes and opens itPR · NO AGENT06ciwaits for CI: green or failedWAIT · ON = "CI"≤ 4 roundson failed · 45 min≤ 2 roundson findings≤ 2 roundson failed CIsent backJOB
IN · {{task}}OUT · done01implementdeveloperTURN · CLAUDE CODE02checksnpm test · lintCHECKS · NO AGENT03reviewqa-engineerREVIEW · CLAUDE OR CODEX04pr-checkyou decideGATE · YOU05prdraft · no agentPR · NO AGENT06ciwaits for CIWAIT · ON = "CI"≤ 4 roundson failed≤ 2 roundson findings≤ 2 roundson failed CIsent backJOB
.foreman/flows/issue-to-draft-pr.tomlSimplified for this page
# .foreman/flows/issue-to-draft-pr.toml · simplified for this page
name = "Issue to draft pull request"
description = "Skip the plan, 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 = "implement"

[steps.implement]
kind = "turn"                  # code steps run on Claude Code
persona = "developer"
loadout = 1
prompt = "{{task}}"

[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]
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
issue-to-draft-pr
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:08developer: moved the redirect after setSession() · +12 −3
  2. 00:45checks: ✕ auth/redirect.test.ts › keeps returnTo after sign-in
  3. 01:22developer (fix, same tab): kept returnTo on the refresh path · +4 −1
  4. 01:59checks: ✓ 214 tests · types · lint
  5. 02:36qa-engineer: clean, no findings
  6. 03:13pr-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. Flows are experimental: turn them on in Settings → Experimental → Flows.

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

02 Staff it

Who should work on a passkey sign-in?

Hire from the fifteen job templates Foreman ships. Ravi builds and Uma specs the screens; sign-in code also wants a QA engineer and a security engineer, and whoever you hire here shows up at the review in chapter 7.

  • A hard hat and a role in plain words
  • Push and draft PRs without waiting since 1.2.4
  • Slack posts and Linear changes held for you

Try it: hire Quinn (QA engineer) and Omar (security engineer) from Open roles.

Open roles 15

Engineering

Design

Product

Data

Writing

Marketing

Customers

Hat rule A hat says who, never state. If a job's colour is taken, the new hire wears the least-worn colour instead.

Slack posts and Linear changes start held for you. Since v1.2.4 an employee pushes and opens draft pull requests on its own; this switch is the one-line rule that holds those too.

Your team 4

  • You

    The person · one of the team

    Approve each plan and each hire, and anything you've asked the team to hold.

  • Priya Lead

    Program manager

    Plans every project, proposes who it needs, reviews each part and accepts the result.

    Starts
    When you @Priya
    Access
    Writes project filesNo shellSlack · held
  • Ravi

    Staff software engineer

    Builds and fixes features, with tests, on its own branch.

    Starts
    When you askWhen assigned in Linear
    Access
    Write · atlasNo shellPush & PR · allowedSlack & Linear · held
  • Uma

    Staff UX designer

    Reviews screens and flows, specifies what to build and draws it as mocks.

    Starts
    When you askWhen review is requested
    Access
    Write · atlasNo shellPush & PR · allowedSlack & Linear · held

03 Tool up

How does the crew get the Linear issue?

Connect Linear and Foreman reads its issues for New workspace, so foreman run issue ENG-142starts a workspace from one. What the agents themselves may do in Linear is up to you: nothing, read, or read and write.

  • Keys stay in Foreman's encrypted storage
  • Foreman doesn't move the issue; Linear's GitHub integration does

Try it: tap the Linear level on the pegboard to hang it on the belt.

  1. GitHub
  2. Linear
  3. Slack
  4. Langfuse
  5. MCP
  6. Sandboxes
  7. GitLab

Connections belong to the repository, so every new workspace in atlas starts with this belt.

7 of 7 tools on the belt

Pulled ENG-142: “Add passkey sign-in to atlas”, with its description and comments.Hang Linear on the belt and ENG-142 comes in from Linear.

foreman run issue ENG-142

04 Build it

How do four agents build one feature without collisions?

Give each part its own agent in its own git worktree on its own branch. They edit the same repository at the same time without touching each other's files, and you sign off each diff.

  • apiWebAuthn register and verify endpoints
  • sign-inThe "Sign in with a passkey" button
  • e2eEnd-to-end tests in three browsers
  • docsThe sign-in docs and the changelog

Try it: tap a hat, then Sign off each lane when it says ready for review.

Work orders
  1. 01api

    Open lane · waiting for a hat

    passkey-apiClaude Code

    +86 −12 · ready for review

  2. 02sign-in

    Open lane · waiting for a hat

    passkey-buttonCodex

    +41 −6 · ready for review

  3. 03e2e

    Open lane · waiting for a hat

    passkey-e2eCursor

    +120 −0 · ready for review

  4. 04docs

    Open lane · waiting for a hat

    passkey-docsOpenCode

    +18 −2 · ready for review

4 worktrees open · 4 signed off

Away from the desk? Answer from your phone

Agents sharing a folder: none. Each agent works in its own git worktree.

05 Send it off-site Experimental

Where should the slow end-to-end tests run?

In a sandbox, if you like: as an experiment, a workspace's worktree and agent can run on your own E2B, Daytona, Vercel Sandbox or Docker account. Close the laptop and the turn keeps going until it finishes or reaches the provider's session limit.

  • Needs a GitHub remote
  • Claude Code, Codex, OpenCode · not Cursor
  • Provider keys never enter the sandbox

Try it: OpenCode has the tests. Press Create on E2B, then Close the laptop.

New workspace · atlas

Workspace

Runs on

Sandbox
E2B
Size
vCPU
Starts from
A fresh clone, set up when it’s made
Sleeps after
20 min idle
Agent sign-in
OpenCode’s own keys

On E2B a session ends after 60 minutes. Foreman continues the turn when you’re around; with Foreman closed, the agent stops at the limit and the workspace sleeps.

Remote workspaces run on E2B. Experimental.

This computer

Foreman · atlasZzz

Vault

  • Provider keystays here
  • GitHub tokenstays here
  • Agent sign-instays here
Property line · provider keys stop here
  1. Clone from GitHub The repository comes from its GitHub remote. GitHub’s token goes in as that one command’s environment.
  2. Install the agent host Foreman puts its small agent host in the sandbox, so the agent can run there without your computer.
  3. Set up The install script and the repository’s setup steps run, as they would in a local worktree.
  4. Run The agent takes the turn in the sandbox. Your computer only coordinates.

Session · not started

Turn · waiting to ship

  1. Pick a workspace and a container, then Create. Closing the laptop quits Foreman: remote turns go on in their sandboxes until they finish or reach the session limit, and their chats catch up when you open Foreman again.

This month · no sandbox time yet

06 Keep it fresh overnight

How do you keep the project fresh overnight?

Put a saved prompt on a schedule. Passkeys lean on a WebAuthn library, so weekly-deps updates the dependencies and runs the tests every Monday at 02:00, on Claude Code, in a fresh worktree. With Flows on, a schedule can run the keep-branch-fresh flow instead.

  • Runs while Foreman runs, even with no window
  • A sleeping computer isn't woken
  • A run more than 5 minutes late is skipped

Try it: pin weekly-deps, set it to weekly at 02:00 and file the slip.

The seven templates that ship 7

Saved prompts yours · blanks written out

Blanks fill in order: foreman run fix-a-bug "the login page loops". A scheduled run can't stop to ask, so only templates without {{blanks}} go on a schedule. Repository templates live in.foreman/templates and travel with the code.

Schedule slipNo. 0042

weekly-deps on atlas

Every
in Europe/London
Runs on
Claude Code, a Sonnet by default
Max
30 minutes5 to 480
After
Approved
its text, the repo's setup, checks and MCP servers

Runs every Monday at 02:00 (Europe/London) · stops after 30 minutes · keeps the workspace

foreman schedules add weekly-deps --repo atlas --every weekly --on mon --at 02:00 --tz Europe/London

07 Review it

Who reviews sign-in code before it ships?

Two reviewers who must agree. A QA reviewer reads the change against what was asked, a security reviewer reads the same tree for injection, secrets and unsafe defaults, any finding goes back, and you look last. That is the built-in two-reviewers flow.

No security engineer on the team, so the table deals a one-reviewer hand. Hire Omar in chapter 2 and it deals the security pass.

The job

Loadout for fix flaky tests

  1. DeveloperClaude CodeAgent · Anthropic

    Writes the fix. Flow steps that change code run on Claude Code, the one agent Foreman runs unattended.

  2. ReviewerCodexAgent · OpenAI

    Reads the diff read-only, inside its own sandbox. A flow’s review steps can run on Codex.

  3. Review personaqa-engineerFlow persona · reviewer

    What the reviewer wears: it finds what breaks, never fixes it, and ends with findings.

  4. At the gateYouThe foreman · one of one

    Quarantine the test, keep the fix, or send it back with a note. Nothing ships before you look.

Plays as the built-in flow flaky-test-triage. Flows are experimental and off by default: Settings → Experimental.

Run them side by side in Foreman, each in its own worktree.

08 Ship it

What lands at the end?

A draft pull request on its own branch, with every change read as a diff, the checks run and both reviews clean. In issue-to-draft-pr Foreman opens the draft itself after your gate, and sends CI failures back to the developer until green. Merging stays with you.

foreman pr create atlas --draft
foreman pr merge atlas --auto --yes

# Open a draft by hand, or auto-merge when the checks pass.

DraftIllustrative

Add passkey sign-in #142

eng-142-passkeys → main · opened by Foreman after your gate

  • 4 parts built in 4 worktrees, each signed off
  • End-to-end suite finished in an E2B sandbox
  • Reviews: QA and security, both clean
  • Linked to ENG-142 in Linear

Waiting on the chapters above.

Also on site

Can you sign it off from your phone?

Yes. Pair a phone with a QR code and answer approvals, plans and flow gates, steer agents and comment on diffs, live. On the same Wi‑Fi it connects directly, and anywhere else over your own Tailscale network, with no Foreman relay.

  • Phone · today

    The gate in chapter 1, from the train

    Watch, Operate or Full control for each device. The phone answers gates and picks; it reads terminals but can't type into them.

    Native iPhone and Android apps are on the way.

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

  • AI employees

    A memory with a commit for every run

    Every organization remembers in its own private git repository. Each run's notes land as one commit saying who wrote them, and your code repositories stay clean.

  • On a budget

    Auto-fix CI and auto-review

    Opt in and a failing CI log goes back to the agent: two fixes per commit, five per PR. A read-only reviewer can read each finished diff.

  • Command line

    Every chapter, from a terminal

    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.

    foreman flow run fix-until-green --input task="make the tests pass" --wait

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. Next to T3 Code, Foreman adds the parts of this page past chapter 4: flows that loop until checks pass, AI employees, schedules and your own sandboxes.

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.

Your own project

Get started in a minute

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

  1. Download Foreman

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

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

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

  3. Create workspaces

    One per task, each a fresh worktree on its own branch. Review the diffs, then open the pull request.

Or start ENG-142's first part from a terminal
foreman run fix-a-bug "the login page loops after sign-in" --repo atlas --wait

# Start a workspace from a template and wait for the turn. CLI reference

Toolbox talk

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 next issue could be yours.

Foreman is three weeks old and has shipped 31 releases since 1.0.0 on 27 October, built in the open under Apache-2.0. Star it to hear about the next one, fork it, or pick up a good first issue and take it from start to ship yourself.