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.

Stars
★ 362
Last updated
4mo ago
License
NOASSERTION
Primary language
Python

At a glance

How it runs
CLI
Works with
Platform-specificClaude Code
Cost
Free software; you pay for model usage
Setup effort
Medium · a few setup steps
You'll need
Python 3.11+Claude Code CLI (authenticated)gitLinux / WSL2 (tested path)Shell / CLINetwork accessLocal filesystem
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.

  1. An engineer maintaining a mature codebase who wants humans to hold the design gates while guardrailed agents parallelize the TDD implementation
  2. A team needing auditable delivery: every run's evidence, verification and review state are files committed in the repo
  3. 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
  4. A Claude Code user tired of prompting turn by turn who wants loops that prompt Claude instead
  5. 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
  6. 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 install
  • pipx 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 backend

Drive 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 deltas

Configure 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?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Good
79/ 100 5-point scale 4.0 / 5
Trust 21/29
Reliability 11/14
Adaptability 15/18
Convention 14/18
Effectiveness 12/13
Verifiability 6/8
Why each dimension lost points
Trust21 / 29 · 3.6/5

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.

Reliability11 / 14 · 3.9/5

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.

Adaptability15 / 18 · 4.2/5

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.

Convention14 / 18 · 3.9/5

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.

Effectiveness12 / 13 · 4.6/5

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.

Verifiability6 / 8 · 3.8/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 22, 2026 Reviewed revision 92d7f7971ca4
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/foreman.svg)](https://followagents.com/en/agents/foreman)
<a href="https://followagents.com/en/agents/foreman"><img src="https://followagents.com/badge/foreman.svg" alt="FARS review"></a>

FAQ

Does trying it cost tokens?
No. foreman demo and foreman --demo run the entire pipeline on a mocked backend (canned stream-json) with zero token spend. Only real feature work against your repo spawns the claude CLI.
Do I need a database or a server?
No. Every bit of state is a human-readable file committed inside your target repo under .foreman/. There is no daemon and no database — kill Foreman mid-build, restart, and it recovers from disk.
Is my repo safe from a runaway agent?
Workers run in isolated git worktrees under per-run turn/cost/time caps and a daily cost ceiling with hard stop, and are hook-blocked from writing their own verification.json. Foreman never trusts the agent's self-report — it re-runs the gates itself. For unsupervised runs, use the strictest permission_mode (and ideally a container).
Which models does it use?
Whatever you configure per role in .foreman/config.yaml — model_planner, model_worker, model_evaluator, model_auditor — plus an effort knob for the planner; different stages can run different models. Execution always goes through the claude CLI.
Does it work outside Linux?
It is developed and tested on Linux/WSL2 (Ubuntu). The README says it should run anywhere the claude CLI, git and Python 3.11+ are available, but Linux/WSL2 is the only tested path.
Is Foreman open source?
The source code is public on GitHub (VisionForge-OU/foreman), but the repository does not declare a recognised licence, so the rights to reuse or modify it are unclear. Ask the author or check the README before building on it.
Is Foreman still maintained?
Development has slowed: the latest commit on GitHub is from 2026-06-29, within the last six months but not the last 30 days.
Who makes Foreman?
Foreman is published on GitHub by the account VisionForge-OU. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts