foreman
An MIT-licensed orchestrator TUI that supervises headless Claude Code agents through a gated plan → ADR/PRD → issues → TDD → e2e delivery pipeline
Most agentic coding tools sell autonomy; Foreman sells supervision, and that is the right call if you actually merge the output. The guardrails that matter here are the boring ones — a daily cost ceiling with a hard stop, approvals that auto-revert when a design doc shifts, and worktree isolation gated by a declared touches set. It is free under the MIT license, so the real entry cost is buying into ADRs, issue tickets, and TDD gates, plus a Linux/WSL2 setup and an authenticated claude CLI. If you want a cloud agent platform or a model-agnostic loop, look elsewhere.
Verified 10h ago · liveness 66/100 · cite: rightaichoice.com/tools/foreman
- Developers already running Claude Code who want governed, gated project workflows instead of raw prompt loops
- Teams that need human review gates plus an in-repo audit trail for AI-written code
- Open-source maintainers who want automated build pipelines kept behind gated approvals
- Engineering orgs piloting agentic delivery with hard per-run and daily cost controls
- Teams that want a no-setup, cloud-hosted agent platform
- Teams standardised on non-Anthropic models, since Foreman drives headless Claude Code
- macOS or Windows users unwilling to run under WSL2
We scan live Reddit threads, YouTube comments, X posts, G2 reviews and other communities — and hand you an honest verdict in under a minute.
- Honest verdict, not marketing
- Real pros & cons from real users
- Attributed quotes with receipts
3 free scans · no card needed
Skip Foreman if you want an agent that runs fully autonomously without pausing at ADR, PRD, and issue gates for human sign-off, or if you are committed to a non-Anthropic model stack.
Foreman itself is MIT-licensed at no cost, but every real run spends tokens through your own authenticated claude CLI, so your Anthropic bill is the actual operating cost — foreman --demo is the zero-token way to try
Foreman is free under the MIT license at any team size, which undercuts hosted agent platforms that charge per seat or per run. Your real budget line is Claude API spend through your own authenticated claude CLI, controlled by per-run budgets and a daily ceiling. Compare it against a managed agent service where the platform markup is bundled into the subscription: Foreman is cheaper on software and more exposed on inference.
In short
foreman — An MIT-licensed orchestrator TUI that supervises headless Claude Code agents through a gated plan → ADR/PRD → issues → TDD → e2e delivery pipeline. Best for Developers already running Claude Code who want governed, gated project workflows instead of raw prompt loops, Teams that need human review gates plus an in-repo audit trail for AI-written code, Open-source maintainers who want automated build pipelines kept behind gated approvals. Free to use.
What's new in foreman
Checked todayAcross the latest 2 updates: 2 changelog entries.
Repository README documents the Boris-style orchestrator TUI
The README describes the gated plan → ADR/PRD → issues → TDD build → e2e pipeline, hash-sealed approvals that auto-revert, per-run and daily budgets, worktree isolation, and the evals flywheel.
CHANGELOG.md maintained in the repository root
The project keeps a dedicated CHANGELOG.md alongside DECISIONS.md and CONTRIBUTING.md; the scrape captured the file's presence but no individual dated entries.
What people actually say about foreman — is it worth it?
We ran a structured research pass across product reviews, community discussions, and post-purchase forum threads to surface the patterns vendors won't publish themselves. Below: the recurring strengths, the hidden costs people mention most, and the cohort that consistently regrets adopting this tool.
5 mentions across 5 sources (Hacker News, YouTube, Product Hunt, GitHub, Lemmy), 58 more we could not attribute · researched Oct 16, 2026.
Weighted by the 63 posts each of 5 sources contributed.
- +Gated plan → ADR/PRD → issues → TDD → e2e pipeline enforces process rather than trusting agent behaviour
- +Hash-sealed approvals auto-revert if a design document changes underneath them — a genuinely novel safeguard
- +Per-run turn, cost, and time budgets plus a daily hard ceiling put hard stops on runaway spend
- +PreToolUse deny hook stops workers from writing their own verification — closes an obvious cheating loophole
- +Parallel workers get isolated git worktrees with a declared touches set to prevent file collisions
- −Essentially no independent community feedback — one HN post, no reviews, no issue tracker evidence
- −Linux/WSL2-only with Python 3.11+ and authenticated claude CLI — macOS and Windows users excluded
- −Tightly coupled to Claude Code; no support for other agent CLIs or local models
- −The fixed TDD-centric pipeline will clash with teams that don't practice TDD
- −Support and patch cadence are unverifiable from public data — a real risk on a solo project
- • Claude Code API/CLI token spend is billed separately by Anthropic — foreman budgets it but does not pay for it
- • Parallel workers multiply token spend; a loosely configured daily ceiling can still allow four-figure monthly bills
- • Time cost of writing YAML config and adapting a repo to the fixed pipeline
- • Linux/WSL2 requirement may mean provisioning a new dev environment for macOS users
Viability Score
How well maintained and how widely used is foreman? Built from what the vendor actually publishes (docs, changelog, tutorials, integrations, pricing), whether the site is live, and how much real users discuss it. How we calculate this
Last calculated: October 2026
How we score →Key Features
- Supervises headless Claude Code agents from a keyboard-driven Textual TUI
- Gated pipeline: plan → ADR/PRD → issues → TDD build → e2e
- Human-in-the-loop review gates on every design phase
- Hash-sealed approvals that auto-revert if a design doc changes
- Per-run turn, cost, and time budgets enforced by the orchestrator
- Daily cost ceiling with a hard stop
- PreToolUse deny hook blocks workers from writing their own verification
- Worktree isolation for parallel workers, gated by a declared touches set
- Crash-safe state as human-readable committed files — no database
- Demo mode runs the full pipeline on a mocked backend at zero token cost
- Evals flywheel: outcome-labelled runs, foreman retro clusters failures into gated patches
- foreman bench replays the eval set and reports success-rate, cost, and turn deltas
- Vendored foreman-* skills installed into .claude/skills/ by foreman init
- YAML configuration via config.sample.yaml
- CLI commands: foreman init, build, status, retro, bench
About foreman
Foreman is an MIT-licensed agentic orchestrator with a Textual terminal UI that turns your locally installed claude CLI into a supervised delivery worker. It spawns claude in headless stream-json mode, parses the event stream, and forces work through a fixed sequence: plan, ADR/PRD, issues, TDD build, e2e — with a human review gate on every design phase and a hash-sealed approval that auto-reverts if a design document changes underneath it. The enforcement lives in the orchestrator, not the model: per-run turn, cost, and time budgets per worker, a daily cost ceiling with a hard stop, and a PreToolUse deny hook that blocks workers from writing their own verification. Parallel workers each get their own git worktree, footprint-gated by a declared touches set so two agents cannot collide on the same files. All state is human-readable files committed inside the target repo — no database — so killing a run mid-build and restarting recovers fully from disk. It is aimed at developers already running Claude Code who want governed, gated workflows instead of raw prompt loops, and at teams that need an in-repo audit trail for AI-written code. Setup is narrow: Python 3.11+, an authenticated claude CLI, git, and Linux or WSL2. The repository (VisionForge-OU/foreman) carries 444 stars, 116 forks, and 14 commits at the time of the scrape.
Behind the Verdict
Foreman's premise is that the orchestrator, not the model, should hold the guardrails — and the implementation backs that up in concrete ways. The PreToolUse deny hook stops a worker from writing its own verification, which is the failure mode that quietly ruins most TDD-with-agents experiments. Budgets are enforced per run on turns, cost, and time, with a separate daily ceiling that hard-stops work rather than warning. Hash-sealed approvals mean a design document that changes after sign-off invalidates the approval and the run reverts, so you cannot approve an ADR and then have the build proceed against a different PRD. Operationally, the design choices are conservative in a useful way. The pipeline is fixed — plan → ADR/PRD → issues → TDD build → e2e — with human gates on every design phase, and everything is committed as human-readable files in your repository with no database, so a killed run recovers from disk. Parallel workers get separate git worktrees and a declared touches set that gates their footprint, which is the practical answer to two agents editing the same file. Configuration is a config.sample.yaml, and the CLI exposes foreman init, build, status, retro, and bench. The evals flywheel is the part competitors usually skip. Every run is outcome-labelled, foreman retro clusters recurring failures into skill and prompt patches, and those patches must pass foreman bench — which replays the eval set and reports success-rate, cost, and turn deltas — before they land. You can also exercise the whole pipeline at zero token cost with foreman --demo against a throwaway sample repo on canned stream-json, which is the cheapest way to walk every gate before spending real budget. The trade-offs are real. You bring your own authenticated claude CLI, so Foreman is tied to headless Claude Code and is not model-agnostic. Platform support is Linux/WSL2, which puts macOS and Windows users behind an emulation layer. Everything runs from a keyboard-only Textual TUI with YAML configuration, so effective use assumes terminal and git comfort. And the gated workflow is a process commitment, not a toggle — runs pause for sign-off rather than operating fully autonomously, and the orchestrator will halt work when a budget ceiling is hit. At 444 stars and 116 forks with 14 commits, this is an active early-stage open-source project, not a vendor with a support contract.
Researching foreman? Get your full AI stack in 60 seconds.
Free, no signup — tell us your goal and get tools matched to your budget & existing stack.
Real-world workflow fit
Concrete scenarios for the personas foreman actually fits — and what changes day-one when you adopt it.
You run foreman init against an existing repository, which scaffolds .foreman/ and installs the foreman-* skills into .claude/skills/, then walk the whole plan → e2e pipeline once with foreman --demo on canned stream-json at zero token cost.
Outcome: You see every review gate and every state file before spending a token of real budget, then switch to live runs knowing exactly where it will pause for you.
A feature request goes in as a plan; Foreman drafts the ADR and PRD, pauses for your sign-off, generates issues, then runs the TDD build with a PreToolUse deny hook stopping workers from writing their own verification and a daily cost ceiling capping spend.
Outcome: The team merges agent output with an in-repo audit trail of pipeline checkpoints and hash-sealed approvals, and a design doc edited after approval auto-reverts the run instead of silently drifting.
Two workers are dispatched on separate parts of the repo, each in its own git worktree with a declared touches set, while per-run turn and time budgets bound each one.
Outcome: File collisions are blocked by the footprint gate rather than resolved after the fact, and killing a run mid-build recovers fully from the human-readable files committed in the repo — no database to reconcile.
Use Cases
- Run a gated delivery pipeline from planning through e2e testing using headless Claude Code agents pointed at your repo
- Generate ADRs and PRDs from a repository with human review before any build work starts
- Supervise TDD workflows with a PreToolUse deny hook so workers cannot write their own verification
- Onboard a new or existing project by having Foreman create issues, ADRs, and test stubs from a high-level plan
- Keep an in-repo audit trail of AI-generated changes via pipeline stage checkpoints and hash-sealed approvals
- Run parallel workers in isolated git worktrees without footprint collisions
- Exercise the full pipeline at zero token cost with foreman --demo before committing real budget
- Cluster repeated failures into skill/prompt patches via foreman retro and gate them with foreman bench
Models Under the Hood
as of 2026-10-16
Limitations
- Foreman is tied to headless Claude Code — it spawns your locally installed claude CLI, so it is not model-agnostic and you bring your own authenticated claude CLI.
- Platform support is Linux/WSL2, which means macOS and Windows users run under an emulation layer.
- Everything is configured in YAML and driven from a keyboard-only Textual TUI, so effective use assumes terminal and git comfort.
- Human-in-the-loop review gates and hash-sealed approvals mean runs pause for sign-off rather than operating fully autonomously, and the gated plan → ADR/PRD → issues → TDD build → e2e workflow is a process commitment, not a toggle.
- Budgets are enforced by the orchestrator, which can halt work when a ceiling is hit.
- Requirements are Python 3.11+, git, and an authenticated claude CLI.
- The project is early-stage: the repository showed 444 stars, 116 forks, and 14 commits at the time of the scrape.
as of 2026-10-22
Verification history
We have re-verified foreman 11 times since . Each pass re-reads the vendor's own pages and re-checks every listed field against that evidence; passes where nothing had changed are marked as such.
- — re-verified summary, description, our verdict, our analysis, pricing model, pricing tiers, features, integrations, who it suits, who should skip it
- — re-checked, vendor evidence unchanged
- — re-verified summary, description, our verdict, our analysis, pricing model, pricing tiers, features, integrations, who it suits, who should skip it
- — re-verified summary, description, our verdict, our analysis, pricing model, pricing tiers, features, integrations, who it suits, who should skip it
- — re-verified summary, description, our verdict, our analysis, pricing model, pricing tiers, features, integrations, who it suits, who should skip it
- — re-verified summary, description, our verdict, our analysis, pricing model, pricing tiers, features, integrations, who it suits, who should skip it
Showing the 6 most recent of 11 verification passes.
Free to cite with attribution — this page re-verifies continuously.
12-month cost
Project the real annual outlay, including the implied monthly cost when only an annual tier is published.
Vendor list price only. Add-on usage, seat overages, and contract minimums are surfaced under Hidden costs & gotchas.
Plans compared
For each published foreman tier: who it actually fits, and what it adds vs. the previous tier. Cross-reference the cost calculator above for projected annual outlay.
Open Source (MIT)
$0
Ideal for
Solo developers and small teams already running an authenticated claude CLI on Linux or WSL2 who want gated, auditable agent delivery rather than raw prompt loops.
What this tier adds
Starting tier and the only tier: the full TUI and CLI under MIT at no cost, covering the gated pipeline, per-run and daily budgets, worktree isolation, zero-token demo mode, and the retro/bench evals flywheel.
Where the pricing makes sense
The company stage and team size where foreman's pricing actually pencils out — and where peers do it cheaper.
Foreman is free under the MIT license at any team size, which undercuts hosted agent platforms that charge per seat or per run. Your real budget line is Claude API spend through your own authenticated claude CLI, controlled by per-run budgets and a daily ceiling. Compare it against a managed agent service where the platform markup is bundled into the subscription: Foreman is cheaper on software and more exposed on inference.
Setup time & first value
How long it actually takes to get something useful out of foreman — broken out by persona, not the marketing-page minute.
Solo developer already on Claude Code: minutes to foreman init plus a zero-cost --demo walkthrough of every gate. Team tech lead: an afternoon to configure config.sample.yaml, agree ADR/PRD conventions, and set budgets. Platform engineer running parallel workers: a day to define touches sets and validate worktree isolation on a real repo. All paths assume Linux or WSL2 with Python 3.11+ and an
Switching to or from foreman
How to bring data in from common predecessors and how to get it back out — written for the switcher, not the buyer.
- →From an ad-hoc while-loop over claude: run foreman init to scaffold .foreman/ and install the foreman-* skills, then let the gated pipeline replace the hand-rolled loop.
- →From manual ADR/PRD writing: let the plan stage draft the design docs, then review and approve them at the human gate before issues are generated.
- →From a cloud agent platform: point Foreman at the same repository and keep the audit trail in-repo as committed human-readable files instead of in a hosted dashboard.
- ↗To a cloud agent platform: your in-repo pipeline artifacts (plans, ADRs, PRDs, issues) are human-readable files, so they travel with the repository rather than needing an export.
- ↗To a plain claude CLI workflow: stop invoking the orchestrator and drive claude directly; the .foreman/ directory and .claude/skills/ skills remain in the repo until you delete them.
Integrations
Resources & Guides
- Resourcegithub.com
Foreman · foreman
Helpful link from github.com
- Resourcegithub.com
README · foreman
Helpful link from github.com
- Resourcegithub.com
CHANGELOG · foreman
Helpful link from github.com
- Resourcegithub.com
CONTRIBUTING · foreman
Helpful link from github.com
- Resourcegithub.com
DECISIONS · foreman
Helpful link from github.com
- Resourcegithub.com
Config.Sample · foreman
Helpful link from github.com
- Documentationgithub.com
Docs · foreman
Full product docs from github.com
- Resourcegithub.com
Issues · foreman
Helpful link from github.com
Tutorials & Learning
YouTube returned 6 videos for “foreman”, and we withheld 6: 6 could not be judged, because “foreman” is a single word that other videos use for other things. We are showing none, because we could not prove any of them are about foreman.
Official links
Tools that pair well with foreman
Common stack mates teams adopt alongside foreman, with the specific reason each pairing earns its keep.
Ellipsis
Ellipsis runs Claude Code and Codex coding agents in managed cloud sandboxes, configured in YAML in your repo
Endor Labs
Agentic application security that governs AI coding agents and verifies reachable vulnerabilities before code ships
Claude Code
Claude Code is Anthropic's agentic coding assistant for multi-file repo work from the terminal, IDE, browser, or cloud.
Featured Head-to-Head Comparisons
Foreman vs Cognition Ai
These are not substitutes, they're two answers to the same question at different budgets. If you already run Claude Code locally and want process gates, hash-sealed approvals, and hard cost ceilings for free, Foreman is the sharper tool — but you own the setup. If your bottleneck is an enterprise backlog and you want ticket-to-merge-PR autonomy with Jira, GitHub, and PagerDuty wired in, Devin is the commercial answer and you'll pay a contract for it. Developers who just want inline suggestions should pick neither.
Foreman vs Poolside Ai
If you're an individual developer or small team already using Claude Code and want structured workflow governance, Foreman is free and powerful. For regulated enterprises needing custom on‑prem models, multi‑agent orchestration, and 256K context, Poolside AI is the right choice despite higher cost and vendor engagement.
Foreman vs Bito
You almost certainly aren't choosing between these. Foreman is a free, MIT-licensed governance harness for developers already running Claude Code who want plans, ADRs, TDD gates and hard cost ceilings enforced by an orchestrator instead of the model's good manners. Bito Governor sits in front of whatever agents you already run and squeezes 40-70% out of the token bill via complexity routing plus a code knowledge graph. If you have no agent pipeline yet, start with Foreman; if your agent pipeline is already expensive, Bito is the cost lever.
Alternatives to foreman
View allEllipsis
Ellipsis runs Claude Code and Codex coding agents in managed cloud sandboxes, configured in YAML in your repo
Endor Labs
Agentic application security that governs AI coding agents and verifies reachable vulnerabilities before code ships
Claude Code
Claude Code is Anthropic's agentic coding assistant for multi-file repo work from the terminal, IDE, browser, or cloud.
Frequently Asked Questions
Used foreman? Help shape our editorial sentiment research.