Foreman: a gated TUI supervisor for headless Claude Code agents

The problem Foreman addresses is supervision, not code generation

A coding agent in a shell loop will happily edit files, run tests and report success. The README states the premise directly: running an agent in a while loop is easy, and running one you can trust to merge is not. Foreman positions itself as the supervisor between the two. It is aimed at engineers who already have the claude CLI installed and authenticated and who want a repeatable delivery sequence rather than an open-ended chat session. The pipeline named in the repository description is plan, ADR/PRD, issues, TDD build, e2e. Design phases get a human review gate. The build phase runs with what the README calls guardrailed autonomy. That split is the whole design argument: the parts where a wrong decision is expensive stay manual, and the parts where the work is mechanical run unattended under caps. Anyone expecting Foreman to write a feature from a one-line prompt without touching a keyboard has misread the tool. The keyboard is central: the README describes the entire workflow as driveable from a Textual terminal UI with a documented keymap.

How the orchestrator, the CLI and the target repository fit together

Foreman does not embed a model client. According to the README it spawns the locally installed claude CLI in headless stream-json mode, parses the event stream that comes back, and uses those events to drive the pipeline. That choice has a concrete consequence: the agent's own capabilities, authentication and version are whatever the local claude binary provides, and Foreman's job is to read and react rather than to call an API. State lives in human-readable files committed inside the target repository. There is no database. The README claims crash safety on that basis: kill the process mid-build and it recovers from disk. The quickstart shows where that state lands, with foreman init scaffolding .foreman/ and installing the foreman-* skills into .claude/skills/. Parallel workers get their own git worktree, and the README says each is footprint-gated by a declared touches set so workers do not collide. That is a static conflict-avoidance scheme, not a merge resolver. Two workers whose touches sets overlap are presumably kept apart by the orchestrator rather than reconciled afterwards, and the README does not describe what happens when a declared footprint turns out to be wrong.

The gates, the hash seal and the deny hook

The review gate is more specific than a pause button. The README describes a hash-sealed approval that auto-reverts if a document changes after approval. So an approved ADR or PRD is tied to its content, and editing it invalidates the approval rather than silently carrying it forward. The guardrails are described as enforced by Foreman rather than by the agent's own restraint: per-run turn, cost and time budgets, a daily cost ceiling with a hard stop, and a PreToolUse deny hook that blocks workers from writing their own verification. That last one is the most interesting claim in the README. An agent that can edit the test file it is being graded against is not being graded. Blocking that write at the tool-call layer, before execution, is a different mechanism from instructing the agent not to do it in a prompt. The dashboard example in the README shows the budget surface in the status bar, with a turn counter and a running cost for the active issue. The README does not document what the default budget values are, nor whether the daily ceiling is per repository or global across repositories.

Getting it running: commands and configuration

The quickstart gives four steps. Install with pipx install . or uv tool install ., which exposes a single foreman command. Change into the target repository and run foreman init, which scaffolds .foreman/ and installs the foreman-* skills into .claude/skills/. Run foreman demo to exercise the full pipeline against a throwaway sample repo using a mocked agent backend and canned stream-json, so nothing is spent. Then run foreman with no argument, which the README says is the same as foreman tui. There is also foreman --demo for the live TUI against the sample repo. Other subcommands listed are foreman status, foreman init --force to re-create config and reinstall skills and agents, foreman build to resume or continue an autonomous build, foreman retro to cluster recurring failures into gated skill and prompt patch drafts, and foreman bench to replay the eval set and report success-rate, cost and turn deltas. Requirements are Python 3.11 or newer, the claude CLI installed and authenticated (the README suggests checking claude --version), git, and Linux or WSL2. Configuration is described as living in a foreman.config.yaml file, though the README excerpt here does not enumerate its keys, so the exact schema should be read from the repository rather than guessed.

The retro and bench loop is the part with the sharpest edges

The README describes an evals flywheel: every run is outcome-labelled, and foreman retro clusters failures into gated skill and prompt patches that must pass foreman bench before they can land. This is the most opinionated piece of the design. Instead of a human editing prompts by feel, failures are grouped and turned into candidate patches, and the bench replay acts as the admission test. The weakness is the same as in any eval-driven loop: the quality of the labels and the representativeness of the replay set determine whether a passing patch is actually an improvement. The README does not say how many runs are needed before retro produces anything useful, how the eval set is constructed, or what happens when a patch passes bench and regresses behaviour the eval set does not cover. Treat the flywheel as a mechanism the project provides, not as evidence that the mechanism has been validated on your codebase. It also implies a maintenance cost: the eval set becomes an artifact you own and have to keep current as the repository changes.

Limitations and cases where Foreman is the wrong tool

Platform support is narrow. The README states Linux or WSL2, developed and tested on Ubuntu under WSL2. There is no Windows-native or macOS claim in the material, so treating it as cross-platform would be an assumption. The dependency on the claude CLI is hard: Foreman spawns it, so a machine without an authenticated claude binary gets nothing, and the orchestrator inherits whatever behaviour that binary has in headless stream-json mode. The state model, files committed inside the target repository, is a deliberate trade-off. It gives crash recovery and reviewability through ordinary git history, and it also means Foreman writes into your repository's working tree, including .claude/skills/ and .foreman/. On a repository with existing conventions in those paths, or with hooks that react to new files, init is a change to your project layout, not a side effect. Worktree isolation depends on the declared touches set being accurate; a worker that edits outside its declared footprint is a failure mode the README's conflict story does not address. Finally, the licence field for this repository reads NOASSERTION even though the README carries an MIT badge and links to ./LICENSE. Those two signals disagree, and until the file itself is read, the terms are unresolved.

Alternatives and how their approach differs

The nearest comparison is a plain shell loop around the claude CLI, which is exactly the baseline the README sets up. A loop gives you no budget enforcement, no approval gate tied to document content, and no recovery state beyond whatever you script yourself; it also lets the agent rewrite its own tests, which the PreToolUse deny hook exists to prevent. A second alternative is running Claude Code interactively and driving the pipeline by hand. That keeps a person in every phase, including the build, which removes the cost-cap problem at the price of the unattended build that Foreman is built around. A third is a general CI-driven agent pipeline built on GitHub Actions: it runs on hosted runners, is not tied to a local claude binary, and produces its own logs, but it has no TUI, no worktree-per-worker model on your machine, and no hash-sealed approval concept in the design phases. Foreman's distinguishing choice across all three is that the orchestrator, not the agent, holds the constraints: budgets, the daily ceiling, the deny hook and the gate state all sit in Foreman's process and in files on disk.

Who should adopt it, and what to check first

Adopt Foreman if you already run Claude Code on Linux or under WSL2, you want the design phases reviewed by a person and the build phase capped by turn, cost and time budgets, and you are comfortable with the orchestrator committing its own state files into your repository. Do not adopt it if you need Windows-native or macOS support, if you cannot install and authenticate the claude CLI, or if you require a permissive licence confirmed before you depend on the code. Before committing, run foreman demo to see the mocked pipeline end to end, then foreman init in a scratch clone rather than your main working tree so you can inspect exactly what lands in .foreman/ and .claude/skills/. Read the LICENSE file, because the repository metadata and the README badge do not agree on the terms. Then check foreman.config.yaml in that clone for the default per-run and daily budget values, since those are the numbers that decide how much an unattended build can spend before the hard stop fires.

Editorial conclusion

Adopt Foreman if you already run Claude Code on a Linux or WSL2 machine and want the design phases reviewed by a person while the build phase runs with cost and turn caps. Do not adopt it if you need Windows-native support, a permissively licensed dependency set, or an orchestrator that works without the claude CLI installed and authenticated. Before committing, verify the actual licence terms in the LICENSE file, check that .foreman/ and .claude/skills/ do not collide with existing repository layout, and run foreman demo to confirm the mocked backend covers the phases you intend to gate.

Official sources

1. Issues
2. README
3. Releases
4. VisionForge-OU/foreman on GitHub