Foreman
A Boris-style orchestrator TUI that supervises headless Claude Code agents through a gated software-delivery pipeline, from plan to e2e, built for merges you can trust.
- Source repo
- VisionForge-OU/foreman
- Stars
- ★ 362
- Last updated
- 4mo ago
- License
- NOASSERTION
- Primary language
- Python
- FA score
- 79/100 · Good
At a glance
- How it runs
- Works with
- Platform-specificClaude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An engineer maintaining a mature codebase who wants humans to hold the design gates while guardrailed agents parallelize the TDD implementation
- Not a fit if
- Teams not using the Claude Code CLI or wanting other model providers as the runtime
- Users who need native Windows/macOS support without WSL2
- Developers who just want a single conversational prompt rather than a gated delivery pipeline
- Maintenance
- Commits in the last 6 monthslast commit 2026-06-29
- Source review
- 79/100 · Good
What does this agent do, and when should you use it?
Foreman (VisionForge-OU/foreman) is an MIT-licensed terminal orchestrator with a keyboard-driven Textual TUI that runs a software-delivery pipeline — plan → ADR/PRD → issues → TDD build → e2e — by spawning your locally installed claude CLI in headless stream-json mode. Design phases (plan, ADR/PRD) pass through human review gates whose approvals are hash-sealed with a SHA-256 of the document body and auto-invalidate on any edit; the build phase is constrained by the orchestrator rather than the agent's own good behaviour. All state is human-readable files committed inside the target repo (.foreman/, .claude/skills/, .claude/agents/) — no database, no daemon, fully recoverable from disk after a crash. Parallel workers run in isolated git worktrees gated by a declared touches set so they never collide, and a PreToolUse deny hook blocks workers from writing their own verification.json; Foreman runs the merge gate (evidence, acceptance_check, test/lint/typecheck, regression ratchet) itself. An evals flywheel rounds this out: foreman retro clusters recurring failures into skill/prompt patch drafts that must pass a foreman bench report before landing.
Running foreman init scaffolds a .foreman/ directory in the target repo and installs foreman-* skills into .claude/skills/. The workflow: press n to create a feature (writes request.md); p runs the planner agent producing plan.md; g runs the foreman-grill-docs skill to produce an ADR and PRD, self-answering what it can and surfacing the rest as 'Open questions for reviewer'; v opens the review screen where drafts are approved or sent back (drafts with open questions cannot be approved; hash-sealed approvals auto-revert when a body changes); s runs foreman-to-issues to slice the PRD into dependency-ordered, vertically-sliced issue files carrying acceptance_check, touches and prd_refs; c confirms the queue, then b starts the autonomous build loop (the 'Boris loop'): an initializer writes init.sh and feature-state.md, and each ready issue is implemented by a foreman-tdd worker in its own git worktree using red-green-refactor, running tests through the foreman-test wrapper and saving evidence under runs/<id>/evidence/. Foreman runs the merge gate itself: it verifies the evidence is real, the issue's acceptance_check passes, the full test/lint/typecheck pass, and the regression ratchet is green. A read-only evaluator (separate --agent, fresh context) then grades the diff on a 1–5 rubric; objections bounce to a fresh worker with a distilled failure report, and uncertainty or repeated disagreement escalates to the Attention queue. When all issues land, an e2e agent runs and a read-only auditor walks the PRD requirement-by-requirement; divergences draft a PRD amendment that re-enters the hash-sealed review gate. Guardrails include per-run max_turns/max_cost_usd/timeout_min, per-issue max_retries, max_parallel, a daily cost ceiling with hard stop, and the PreToolUse deny hook. foreman retro, foreman bench, and foreman status provide the evals flywheel, while foreman --demo and foreman demo replay the entire pipeline on a mocked backend (MockBackend) with zero token spend.
- An engineer maintaining a mature codebase who wants humans to hold the design gates while guardrailed agents parallelize the TDD implementation
- A team needing auditable delivery: every run's evidence, verification and review state are files committed in the repo
- A developer worried about runaway agents who wants a daily cost ceiling with hard stop, per-run budgets, and a merge gate Foreman executes itself
- A Claude Code user tired of prompting turn by turn who wants loops that prompt Claude instead
- Someone who wants to keep improving agent behaviour: use the retro/bench flywheel to turn recurring failures into gated skill/prompt patches that must pass benchmarks
- Anyone wanting to evaluate the whole workflow before spending a cent via foreman --demo's mocked backend
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pipx install . # or: uv tool installpipx install
- Config files
.foreman/config.yaml- Runtime
- Python 3.11+
- Install notes cover
- Linux · WSL
How do you install or deploy this agent?
Requires Python 3.11+, the claude CLI installed and authenticated (verify with claude --version), and git; development and testing target Linux/WSL2 (Ubuntu).
# Install (exposes a single `foreman` command)
pipx install . # or: uv tool install .The project is published on PyPI as foreman-orchestrator; you can also install from the repository itself.
git clone https://github.com/VisionForge-OU/foreman
cd foreman
pipx install .How do you use this agent?
# Point it at any repo
cd /path/to/your/repo
foreman init # scaffolds .foreman/ and installs foreman-* skills into .claude/skills/
# End-to-end with zero token spend
foreman demo # full pipeline on a throwaway sample repo via MockBackend
# Real work
foreman # launches the TUI (same as foreman tui)
foreman --demo # TUI against a mocked backendDrive everything by keyboard in the TUI: n new feature → p run planner → v review plan → g run grill (ADR+PRD) → v review docs → s slice to issues → c confirm queue → b start build; w for live worker logs, x for escalations, m for metrics, t for the retro patch gate.
CLI commands:
foreman status # vendored-skill + agent status + features
foreman init --force # re-create config and reinstall skills/agents
foreman build # resume/continue the autonomous build
foreman retro # cluster recurring failures → gated patch drafts
foreman bench # replay the eval set; report success-rate/cost/turn deltasConfigure models and limits per role in .foreman/config.yaml (model_planner, model_worker, model_evaluator, model_auditor, limits, run_budget, and more).
What are this agent's strengths and limitations?
- Gated, not self-policed: approvals are hash-sealed with SHA-256 and auto-revert, and the merge gate (evidence + acceptance_check + test/lint/typecheck + regression ratchet) is executed by Foreman itself, never trusted to the agent
- Crash-safe and auditable: all state is human-readable files committed in the repo — no database, no daemon, recovers from disk
- Real enforcement of guardrails: per-run turn/cost/timeout budgets, daily cost ceiling with hard stop, a PreToolUse deny hook blocking workers from writing their own verification, heartbeat locks against double-claiming
- Built-in evals flywheel: outcome-labelled runs, a metrics pane, and retro patches that only land with a bench report
- Zero-cost trial: foreman --demo / foreman demo replay the full pipeline on a mocked backend, and the test suite runs fully offline
- Runtime lock-in to Claude Code: core operation depends on a locally installed, authenticated claude CLI; no other model backend
- Platform constraints: docs name Linux/WSL2 (Ubuntu) as the developed and tested path; other systems are only 'should run'
- Ongoing token costs in real use: planner, grilling, building, evaluating and auditing all consume claude API usage, and retro/bench are long, token-heavy runs
- Installation requires building from source/local checkout (pipx install .) rather than a single package-manager name; GitHub metadata shows License NOASSERTION, so consult LICENSE/NOTICE yourself
- Learning curve: the gated pipeline, touches conflict sets, and multi-role model configuration in config.yaml take time to master
How does this agent compare with similar options?
The README positions Foreman explicitly against naively running a coding agent in a while loop — 'running one you can trust to merge is not easy'. Compared with driving Claude Code directly, Foreman adds a gated pipeline, worktree-isolated parallel builds, a merge gate the orchestrator executes itself, and an evals flywheel on top of the same claude CLI runtime.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Foreman This agent | 79 · Good | CLIFree + model costs | ★ 362 | 4mo ago | Python | Claude Code |
| Open Swarm | Insufficient evidence | — | ★ 826 | 1mo ago | JavaScript | Claude API |
| MoAI Development Harness | 61 · Some gaps | CLIFree + model costs | ★ 1.3k | 9d ago | Go | Claude Code |
| GameDesignOS: A Local-First Operating System for AI-Assisted Game Design | 71 · Some gaps | CLIFree | ★ 459 | 3mo ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Safety design stands out for this category: human review gates, hash-sealed approvals that auto-invalidate on doc edits, a PreToolUse deny hook blocking workers from writing their own verification state, worktree isolation, and per-run/daily cost ceilings. user_confirmation earns full marks — all design phases are human-gated and `foreman run` requires explicit --auto-approve. least_privilege and rollback score 2: worktrees and hooks are real, but the claim that the hook is 'proven to hold under acceptEdits' is asserted without the hook source or proof in the packet; the rollback path for commits/merges to the target repo is one line only. sensitive_data_handling is 1: AGENTS.md warns against committing transcripts with secrets, but the product has no mechanism for API keys or sensitive transcript data. external_effects 2: it spawns the local claude CLI and commits/merges into the user's repo — honestly described in the README but unverified by execution.
self_consistency is full marks: the README keymap, phase names, and file layout align tightly with cli.py, tui/app.py, and the tests. dependency_availability 2: minimal deps (textual, pyyaml) but a hard dependency on an authenticated local claude CLI, tested only on Linux/WSL2. failure_messages 2: the CLI gives clear messages for uninitialized repos, missing --slug, missing --auto-approve; the TUI has a notify error channel, but failure paths beyond HeadlessError have limited evidence.
audience_and_scenarios full marks: the target user is explicit and the mock backend serves a zero-cost trial scenario. trigger_precision full marks: the four SKILL.md files specify trigger conditions, injected inputs, and output contracts precisely (when to escalate, when to stop, no own summary). capability_boundaries 2: Phase 3 and sandboxing are declared unimplemented, but capability limits beyond permission-mode/container advice are thin. environment_fit 2: CI matrix covers Python 3.11–3.13, yet the project admits it is developed and tested only under WSL2/Ubuntu.
information_architecture, install_notes, naming_stability, and license are full marks: thorough README, quickstart, forced foreman-* namespacing, MIT with NOTICE attribution. examples_and_faq and versioning_changelog score 2: the FAQ covers cost/database/models, but CHANGELOG.md, DECISIONS.md, NOTICE, and config.sample.yaml are referenced yet absent from the packet, so their content cannot be verified; known limitations appear only as a roadmap (score 1) with no dedicated statement of runtime limits or known bugs. maintenance_responsibility 2: solid CI/publish workflows (tag check, Trusted Publishing) but an individual author with no stated maintenance commitment.
output_usability full marks: the TUI keymap is fully documented and all state is human-readable on-disk files. marginal_value full marks: 'trustworthy enough to merge' is a real differentiator via review gates, a regression ratchet, and an evals flywheel. cost_benefit 2: the design itself spends substantial tokens (grill, retro, bench, multiple workers); the demo mitigates trial cost, but the benefit is asserted with no public benchmark data.
claim_traceability 2: strong claims ('proven to hold under acceptEdits', 'crash-safe', 'fully recovers') cannot be traced to proof inside the static packet. cross_source_corroboration 2: the README corroborates with cli.py, tui/app.py, and dogfood tests on keymap, phases, and budget logic, but the missing CHANGELOG/NOTICE/DECISIONS leave some claims dangling. fact_inference_separation full marks: SKILL.md files clearly label adaptation sources and modifications; the roadmap cleanly separates implemented from planned.
- This is a static review: all runtime claims (hook blocking, crash recovery, cost ceilings) are unverified by execution.
- The product commits and merges into your real repository and makes real paid calls to the claude CLI — first use should be in a throwaway repo or container.
- Sensitive-data handling is nearly absent: claude transcripts may contain secrets; only contributor guidance warns about this, with no redaction or isolation mechanism in the product.
- Tested only on WSL2/Ubuntu per the project's own statement; cross-platform availability is unknown.
- CHANGELOG.md, NOTICE, and DECISIONS.md are missing from the review packet; related claims cannot be verified.
- Publisher is unverified (license metadata NOASSERTION); confirm the supply chain yourself before enterprise adoption.
FAQ
Does trying it cost tokens?
Do I need a database or a server?
Is my repo safe from a runaway agent?
Which models does it use?
Does it work outside Linux?
Is Foreman open source?
Is Foreman still maintained?
Who makes Foreman?
Thanks — we use this to improve the page.