Foreman CLI
Foreman watches coding agents and decides whether to continue, steer, stop, retry or verify their work, so a person need not.
- 825 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Launches coding agents that change the repository and decides by itself whether to continue them.
- Sends diffs and output to an external decision model.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/thruwire-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.
- Launches coding agents that change the repository and decides by itself whether to continue them.
- Sends diffs and output to an external decision model.
This is third-party code. Review the repository files before installing.
What it does
Foreman, a Python asyncio runtime, places a fast decision model above slower coding agents. It launches Codex, OpenCode, Hermes or Deep Agents Code as workers, and attaches to Pi sessions and assistants through hooks. The model assesses the original job, the diff, output and test results. From that assessment Foreman decides to continue, steer, stop, retry, verify or finish. Checks such as `implementation_complete`, `tests_sufficient`, `worker_stuck` and `needs_human` are configurable. It works with TypeSafe AI's Jev model and the OpenAI Decisions API.
Who it is for. Engineers who run coding agents on long jobs and want a second layer to watch for looping, drift and a false "done".
Good fit when
- An agent is stuck in a loop repeating the same edit.
- A ticket is declared done but tests are weak, and an independent assessment is needed.
- Work drifts from the original job and must be pulled back.
- Ten workers carry different jobs and one place should give the overall picture.
Not a fit when
- A short edit where reading the diff yourself is simpler.
- Diffs and output must not go to an external decision model.
- A deterministic check is required: the scores are probabilistic.
Example request
foreman run --repo ./my-project --job "Add request retries on network errors"Limitations
Assessments need access to a decision model: a `TYPESAFE_API_KEY` for Jev or a configured OpenAI adapter. Compact excerpts reach the assessment: up to 20,000 characters of diff, output tails and `AGENTS.md` instructions, so code goes to an external provider. Live steering into a running turn works only with the Codex App Server, and other backends fall back to stop or retry. The Pi bridge installs separately, as `foreman-core` alone is not enough. Decision quality depends on configured checks and thresholds and is not guaranteed.
How to disable. Stop running jobs and uninstall the package with `python -m pip uninstall foreman-core`. Remove the hooks from the assistant settings and saved run states by hand.
FAQ
How do I run a job?
Run `foreman run --repo ./my-project --job "..."`. The worker is chosen with the `FOREMAN_WORKER_BACKEND` variable, for example `opencode`.
How do I see past runs?
`foreman runs --repo ./my-project` shows the list and `foreman inspect <run-id> --repo ./my-project` opens details.
Can it attach to a Codex session?
Yes, through hooks: `foreman hook --client codex` takes an event as JSON on stdin. A ready Codex plugin is in the thruwire marketplace.
Does the model see the whole repository?
No. It gets compact observations: git status, a bounded diff, file names, output tails and `AGENTS.md`.
Which decision models are supported?
Jev from TypeSafe AI and the OpenAI Decisions API. The latter needs the adapter: `pip install 'foreman-core[openai]'`.
Discussion
No questions or reviews yet.
Related
CLI toolsAgentForeman coordinates coding agents: a chairman clarifies the task, workers execute and the result comes with evidence.
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
Argus runs long engineering and research tasks with four roles, where a reviewer reads results but edits nothing.
A team of AI agents from one request: it plans the task, writes code in parallel branches, tests, reviews and opens a pull request
One agent launches others in the background: Claude Code, Codex, Copilot CLI, Grok Build and Pi, with a model chosen per stage.
A CLI that keeps an existing agent on a long task: plan a step, run it, verify the result in the real environment and checkpoint progress
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Foreman (this card) | no | 825 | ||
| Ralph Orchestrator | no | not required | 3,203 | loops an agent until done; Foreman independently assesses completeness and tests and intervenes by decision |
| Claude Squad | no | 8,790 | manages several agent sessions; Foreman watches the quality of a single session's progress |
README in short
The README explains the idea of semantic supervision, pluggable workers, responsibilities and checks. Installation, run commands and environment variables follow.