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):