Foreman CLI
Terminal orchestrator for Claude Code: runs a feature from plan, ADR and PRD to a TDD build and e2e, with human gates and autonomous worktree builds
- 443 ★ on the repository
- Last commit
Broad access
Why this level
- Autonomous worker agents write code, run tests and merge branches in your repository
- Runs spend money and tokens from your Claude subscription, so limits must be set beforehand
- foreman init writes skills and agents into .claude/ and state files into .foreman/
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/foremanDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Autonomous worker agents write code, run tests and merge branches in your repository
- Runs spend money and tokens from your Claude subscription, so limits must be set beforehand
- foreman init writes skills and agents into .claude/ and state files into .foreman/
This is third-party code. Review the repository files before installing.
What it does
Foreman is a Textual terminal UI that spawns your installed claude CLI in headless stream-json mode and drives a feature through a pipeline: plan, ADR and PRD, issue slicing, TDD build and end-to-end verification. State lives in plain files inside the target repository, with no database, so Foreman recovers from disk after a crash. Design phases keep a human in control. A planner writes plan.md, the foreman-grill-docs skill challenges the plan against the code and drafts an ADR and PRD, and you approve (a) or request changes (r) in the interface. Approval is sealed with a SHA-256 hash and reverts if the document body changes. Once ADR and PRD are approved, foreman-to-issues slices the PRD into small issues with a runnable acceptance check, and you confirm the queue. An autonomous loop follows. Each ready issue runs in its own git worktree, in parallel when their touches do not overlap. A worker agent follows foreman-tdd to write code and save evidence, and Foreman itself decides the merge: acceptance check, tests, lint, types and a regression ratchet. A separate-context evaluator then grades the diff from 1 to 5. Turn, cost and time budgets, a daily cost ceiling and a PreToolUse hook that blocks agents from writing verification.json are enforced by Foreman, not by the agent.
Who it is for. For developers who already use Claude Code and want to hand it a large feature through a loop with checkpoints and spending limits.
Good fit when
- A feature is too big for one conversation and has to be split into an ADR, a PRD and independent issues with checks
- You want parallel builds of several issues, each in its own worktree, without clashes on touched files
- You want a spending ceiling: a per-run budget, turn limits and a daily cap with a hard stop
- Merging should depend on test, lint, type and regression results rather than the agent's word
- You want to try it without cost first: foreman --demo runs the whole pipeline on canned data and spends no tokens
Not a fit when
- A change of a few lines: a loop with plan, ADR and PRD is overkill
- You have no installed and authenticated claude: Foreman launches exactly that
- You are not on Linux or WSL2: the developer tested only Ubuntu under WSL2
- You want a different agent in place of Claude Code: Foreman is built around claude and its event format
Example request
Run foreman in this repository and create a daily-plan feature: let it prepare the plan and PRD first and I will review themLimitations
Needs Python 3.11 or newer, git and an installed, authenticated claude. The developer built and tested Foreman on Ubuntu under WSL2.
- Running worker agents spends money and tokens from your Claude subscription or key. max_cost_usd, max_turns, timeout_min and the daily ceiling set the limits.
- Phase 3 (training data export, worker sandboxing, CLI-contract probes, a chaos suite) is marked planned on the roadmap.
- The license is MIT, and some bundled skills come from mattpocock/skills (MIT) and were reworked.
- Foreman's skills and agents are written into .claude/skills/ and .claude/agents/ of your repository.
How to disable. Remove the tool with pipx uninstall foreman-orchestrator. In a repository you can delete the .foreman/ directory and the foreman-* skills from .claude/skills/ together with the foreman-*.md agents from .claude/agents/.
FAQ
How do I install Foreman?
Run pipx install foreman-orchestrator, or pipx install . from a clone of the repository. Then run foreman init in your project: it creates .foreman/ and installs the foreman-* skills into .claude/skills/.
Can I try Foreman without spending tokens?
Yes. foreman demo runs the whole pipeline on a throwaway repository with a mocked agent backend, and foreman --demo opens the same interface. No tokens are spent.
What does it mean that approval is sealed with a hash?
Foreman checks the SHA-256 of a document body on every load. If you or an agent changed an approved document, the approval is revoked and the document needs a fresh review.
How does Foreman stop an agent from gaming the checks?
Foreman itself decides the merge from the acceptance check, tests, lint, types and regressions. A PreToolUse hook forbids worker agents from writing verification.json and issue files.
What are foreman retro and foreman bench?
foreman retro clusters recurring failures and drafts patches to skills and prompts. A patch lands only after a foreman bench report shows it does not regress the eval set.
Discussion
No questions or reviews yet.
Related
CLI toolsWorkflows for Claude Code: /do, /omo, /bmad-pilot and more commands, with Codex, Gemini or OpenCode writing the code through codeagent-wrapper
One runtime for Claude Code, Codex, OpenCode and more: a run counts as done only when checks the agent did not write pass
An environment for Claude Code that keeps context across sessions via hooks, ledgers and handoffs, orchestrates agents and saves tokens
A local dashboard for many Claude Code sessions: each job gets its own context and todo, agents spawn child agents and message each other
A terminal app for running several Claude Code, Codex, Gemini CLI and Aider sessions in parallel, each in its own tmux session and git worktree
An orchestrator for agents: the workflow is defined in code, every step is enforced, key points need human approval and decisions go into an immutable journal
Comparison with similar tools
Entries that share the main search query, and how they differ.
README in short
The page explains why an agent needs a supervisor: a pipeline with gates, real headless agents, state in files, worktree isolation, limits owned by the orchestrator and an evals loop. A token-free demo, a quickstart, a keymap for the interface and a detailed description of the two phases follow. Then come the roadmap, file layout, .foreman/config.yaml settings, the bundled skills and development rules.