Foreman runs on your machine and drives logged-in AI coding CLIs to do real software work — capturing, verifying, and reviewing every change it makes. This page installs it and explains how the system works.
Install
One command. You need macOS or Linux, Node.js 22+, git, and access to the private Foreman repository — ask Greg to add your GitHub account as a collaborator first.
This clones Foreman into ~/foreman, installs dependencies, builds the CLI, and links the foreman command onto your PATH. Prefer a smoother login? Install the GitHub CLI and run gh auth login before you start.
Make sure ~/.local/bin is on your PATH. npm install compiles native modules, so it can take a few minutes.
What Foreman is
Foreman is a local-first orchestrator for AI coding work. It launches a logged-in CLI worker (Codex, Claude Code) inside a real pseudo-terminal, hands it a structured task packet, watches until it stops, then captures the full transcript and git diff, runs your verification command, and writes the outcome to a local SQLite store at .foreman/foreman.db.
Everything that matters — your code, your logged-in tools, your history — stays on your machine. The cloud surface you are looking at now is a read-only mirror and an action-request board; it never holds your repository.
How a build runs
Work is planned, then decomposed into the maximum number of independent lanes so workers can run in parallel. Each task moves through the same loop:
Plan & decomposeA plan is split into parallel lanes and tasks, each with explicit file scope and acceptance criteria. Tasks are tiered Quick / Standard / Complex so ceremony scales to risk.
Execute in a PTYForeman sends the task packet into a worker CLI and drives it through a real terminal — no screen-scraping, no GUI tricks. It detects when the worker stops (process exit, idle timeout, or a completion marker).
Capture & verifyForeman records the transcript and git diff, then runs the declared verification command. Exit code 0 is a pass; anything else is a fail. Every artifact is persisted and queryable by run id.
Review & remediateA passing build is not automatically a finished one — it then goes through review (below).
Parallelism is the default, but execution workers are capped at 3 at once for stability; the planner may still split work into many more lanes.
How reviews work
Verification proves the machine checks pass. Review proves the change is actually good. Foreman layers several gates, each stricter than the last:
Writer → Reviewer → FixerAfter a writer worker makes a change, a reviewer worker reads the diff and produces evidence-based findings — file, location, issue, evidence, impact, recommended fix, and severity. Findings route to a fixer worker, which addresses them, and Foreman re-verifies.
Quality gateA same-session quality review confirms the change actually meets the acceptance criteria. When it is on, passing verification is necessary but not sufficient — the task only completes after the quality review/fix loop finishes clean.
Phase reviewWhen a phase of work closes, an integrated review runs across the whole phase diff. The phase only closes — and gets its done tag — once open Critical and High findings are resolved and checks are green.
Grill gateFor complex planning, an adversarial "grill" interrogates the plan and its decision points. Its report becomes a mandatory gate, so risky plans cannot slip through unexamined.
Local control, cloud visibility
Once installed, pair your local Foreman with this workspace (foreman cloud pair) and keep it connected (foreman cloud connect). The cloud then shows live board state, agent liveness, and any action requests — but every action is confirmed locally, on your machine, by you. Foreman never reaches into your repo from the cloud.
