foreman

Foreman

A Boris-style agentic orchestrator TUI that supervises headless Claude Code agents through a gated software-delivery pipeline — pointed at any repository.

plan → ADR/PRD → issues → TDD build → e2e

Why Foreman? · Demo · Quickstart · Guide · How it works · Roadmap · Contributing

"I don't prompt Claude anymore; I have loops that prompt Claude."

Foreman spawns the locally-installed claude CLI in headless stream-json mode, parses its event stream, enforces budgets, and drives your delivery workflow with a human-in-the-loop review gate for the design phases and guardrailed autonomy for the build. All state is human-readable files committed inside the target repo — no database; kill it and restart and it fully recovers from disk.

Table of contents

• Why Foreman?
• Demo
• 5-minute quickstart
• Guide — driving the TUI
• How it works
• Roadmap
• File layout
• Configuration
• The vendored skills
• Development
• Contributing
• FAQ
• Acknowledgements
• License

Why Foreman?

Running a coding agent in a while loop is easy. Running one you can trust to merge is not. Foreman is the supervisor in between: it keeps a human at the design gates, then hands the build to agents that are boxed in by the orchestrator, not by their own good behaviour.

• 🚦 Gated pipeline — plan → ADR/PRD → issues → TDD build → e2e, with human review gates on every design phase and a hash-sealed approval that auto-reverts if a doc changes.
• 🤖 Real headless agents — spawns the locally-installed claude CLI in stream-json mode, parses its events, and enforces per-run turn/cost/time budgets.
• 💾 No database — all state is human-readable files committed inside the target repo. Crash-safe: kill it mid-build and it recovers from disk.
• ⌨️ Keyboard-driven TUI — drive the entire workflow from a Textual terminal UI (full keymap below).
• 🧰 Worktree isolation — parallel workers each run in their own git worktree, footprint-gated by a declared touches set so they never collide.
• 🛡️ Guardrails Foreman enforces (not the agent) — per-run caps, a daily cost ceiling with a hard stop, and a PreToolUse deny hook that blocks workers from writing their own verification.
• 🔁 Evals flywheel — every run is outcome-labelled; foreman retro clusters failures into gated skill/prompt patches that must pass foreman bench before they can land.

Demo

foreman --demo        # launch the full TUI against a throwaway sample repo,
                      # driven by a mocked agent backend — ZERO tokens spent

foreman demo (non-interactive) and foreman --demo (the live TUI) run the entire plan → … → e2e pipeline on canned stream-json, so you can explore every gate and screen before spending a cent.

Dashboard at a glance (illustrative layout — run foreman --demo to see it live):

┌ Foreman ─────────────────────────────────── agentic delivery orchestrator ──┐
│ Features (n)            │ daily-plan — phase: building   cost: $0.41   ●2 wk │
│ ▸ daily-plan            │ Press b to (re)start · w workers · x attention     │
│   backlog-aging         │                                                    │
│                         │  Issue board                                       │
│ Vendored skills         │  queued     in_progress   done       merged        │
│  ✓ foreman-tdd     v4   │  ISS-004    ISS-002       ISS-001    ISS-003       │
│  ✓ foreman-grill…  v3   │             ISS-005                                │
│ Read-only agents        │                                                    │
│  ✓ foreman-evaluator    │  [ global activity log … ]                         │
├─────────────────────────┴────────────────────────────────────────────────┤
│ ⠹ ACTIVE  ISS-002 worker · turn 12/30 · $0.18 · running pytest             │
│ n New  p Plan  g Grill  s Slice  c Confirm  b Build  v Review  w Workers …  │
└────────────────────────────────────────────────────────────────────────────┘

5-minute quickstart

# 1. Install (exposes a single `foreman` command)
pipx install .            # or:  uv tool install .

# 2. Point it at any repo
cd /path/to/your/repo
foreman init              # scaffolds .foreman/ and installs the foreman-* skills
                          #   into .claude/skills/

# 3. See the whole thing work end-to-end with NO tokens spent
foreman demo              # runs the full pipeline against a throwaway sample repo
                          #   using a mocked agent backend (canned stream-json)

# 4. Launch the TUI for real work
foreman                   # (same as `foreman tui`)
foreman --demo            # launch the TUI against a throwaway sample repo

foreman status            # show vendored-skill + agent status + features for the repo
foreman init --force      # re-create config and reinstall the foreman-* skills/agents
foreman build             # resume/continue the autonomous build of a feature
foreman retro             # cluster recurring failures → gated skill/prompt patch drafts
foreman bench             # replay the eval set; report success-rate/cost/turn deltas
foreman --version

Requirements

• Python 3.11+
• The claude CLI installed and authenticated (claude --version)
• git
• Linux / WSL2 (developed and tested on Ubuntu under WSL2)

Guide — driving the TUI

Foreman is fully keyboard-driven. Launch it with foreman (or foreman --demo to try it with a mocked backend and zero token spend). Every screen also shows its keys in the footer; the reference below is the complete map.

The shape of a session

You spend almost all of your time on the Dashboard. It lists your features on the left, shows the selected feature's current phase + cost + a live issue board on the right, and tells you the single next key to press in its hint line. The other screens (Review, Workers, Attention, Metrics, Retro, Settings) are pushed on top with a single key and dismissed with Esc.

A feature moves through phases; the Dashboard hint tells you what to press at each:

Dashboard — global keys

The home screen. Select a feature with the arrow keys, then act on it.

New-feature modal (n)

A small form: type a title, Tab into the request box (description

• product requirements), then click Create (or Cancel). Submitting writes request.md and selects the new feature.

Review screen (v) — the design gate

Where you approve or push back on the plan, adr, and prd drafts. The top of the screen surfaces the grill's "decisions made on your behalf" digest and any open questions; the body renders the document; a comment box at the bottom is used as your answers to those open questions.

• A draft with open questions cannot be approved — answer them via a request-changes comment first, then re-run the grill/planner to revise.
• Approval is hash-sealed: editing an approved doc's body auto-invalidates its approval (a SHA-256 of the body is re-checked on every load).
• Requesting changes on a PRD amendment can spin off concrete fix issues — the notification tells you how many and to press b to build them.

Worker view (w) — watch the build

A sidebar of running workers (id [status] $cost turns) and a live, scrolling log of the selected worker's raw agent output, with a budget bar on top.

Attention queue (x) — rescue escalations

When a worker escalates (uncertainty, repeated evaluator disagreement, …) it lands here and the terminal bells. Select an escalation, read its detail, type your answer, and resume the worker — which picks up your answer in a fresh context.

Submit is Ctrl+S, not Enter, so Enter stays free for multi-line answers. The submit binding fires even while the answer box has focus.

Metrics pane (m)