Available on
Get started · What is this? · How it works · What you can do · Evidence
You finish a session with a fix, a side request and an issue still waiting. Next time, you need to know which one comes first and why. Foreman keeps that context in a roadmap beside your code.
Ask "what’s next?" and it recommends a task with its reason and a prompt checked against the project’s files. Completed work brings evidence back into the plan; acceptance stays a separate decision.
- Pick up where the last session stopped.
- Keep the task, its reason and its constraints together.
- Check stale plans against the code before acting.
- Keep acceptance of finished work separate from a successful test run.
The roadmap lives in your project. Foreman reads it, checks the relevant context and helps you choose what to do next. Optional lessons let later tasks learn from earlier work without creating a separate knowledge base.
| You say | You get |
|---|---|
| Add this to the roadmap | Requested work recorded with its reason and boundaries |
| Where are we? | Status, blockers and work waiting for acceptance |
| What's next? | A recommended task and a choice of where to run it |
| Check whether the plan still matches the code | A grounded review before choosing work |
| Craft a prompt for this | A checked handoff without requiring a roadmap entry |
Plain sentences like the ones above work in both assistants. If you would rather call Foreman by name, each assistant has its own way:
| You want to… | Claude Code | Codex |
|---|---|---|
| Ask in your own words | /foreman:foreman |
the foreman skill |
| Set up a roadmap for a project (once) | /foreman:init |
the init skill |
| Pick, add, correct or review work | /foreman:roadmap |
the roadmap skill |
| Check the plan against your code | /foreman:survey |
the survey skill |
| Write a one-off prompt with no roadmap entry | /foreman:craft-prompt |
the craft-prompt skill |
Foreman is one plugin for both assistants. Install it in the one you use; only the commands differ.
Requirements: Node.js and Git (tested with Node.js 22). Foreman is built and tested against Claude Code 2.1.x.
Inside Claude Code:
/plugin marketplace add V-Songbird/foundry
/plugin install foreman@foundry
Start a new session to load the plugin. Run /foreman:init once in the project.
Requirements: Node.js and Git (tested with Node.js 22), and a Codex host with plugin support.
codex plugin marketplace add V-Songbird/foundry
codex plugin add foreman@foundry
Review and trust its hooks with /hooks, then start a new Codex session. Ask Foreman to initialize the project, or select its installed init skill.
Existing roadmap data can be reused. Both assistants read and write the same ROADMAP.jsonl and .foreman/ files, so one project can move between them. Claude Code needs Foreman 2.7.0 or later to read entries that Codex wrote.
Foreman is for a solo developer. It does not become a team tracker, code-review service, unattended scheduler or workflow server. Your project keeps its own data. The optional ledger is off until requested; disabling it deletes no existing notes.
Foreman does the same job in both assistants. The host — the assistant Foreman runs inside — decides which events and tools Foreman can use, so a few things work differently:
| Claude Code | Codex | |
|---|---|---|
| Starting a tracked task | A hook opens the roadmap entry when Foreman's prompt becomes a task | The prompt opens the entry with an explicit start command |
Reminder when a task ends with its entry still open (taskCloseGate) |
The first attempt to finish stops until the entry is closed | After an explicit check finds the entry still open, Foreman asks Codex for one more turn |
| Direct edits of the roadmap file are blocked for | Edit and Write |
apply_patch, Edit and Write |
| Lessons appear when a file is touched with | Read, Edit and Write |
apply_patch, Read, Edit and Write |
| Offering untracked work Foreman noticed | After a commit | After a commit, in every handoff and before reporting completion |
| Advice based on how full the session is | When your auto-compact window is set (settings) | Not available: Codex does not report it |
| Stopping for your approval after each result of a task | Not available in Claude Code yet | On explicit request |
| Model recorded when a task closes | Family name, such as sonnet |
Exact model id |
On both hosts, a shell command can still write the roadmap file, and reading a file through the shell shows no lessons. A prompt copied out of one assistant carries that assistant's script paths, so craft it again in the other. Foreman in Codex covers the Codex side in detail.
Each result belongs to the named model and recorded run. Measurements belong to the model and setup that produced them, so each host keeps its own table. Missing measurements remain marked as unmeasured.
| Model | Setup | Correct tasks | Mean session cost |
|---|---|---|---|
| Claude Sonnet (proof-sn2) | Written task paragraph | 100% | $0.0757 |
| Claude Sonnet (proof-sn2) | Foreman | 100% | $0.0820 |
| Claude Opus (proof-op2) | Written task paragraph | 100% | $0.1627 |
| Claude Opus (proof-op2) | Foreman | 100% | $0.1746 |
Foreman tied the well-written paragraph on correctness and cost more: 8.3% on Sonnet and 7.3% on Opus. These are historical comparisons, not a claim about the current release or another model.
| Model | Setup | Correct tasks | Mean session cost |
|---|---|---|---|
| Not measured | Without plugin | Not measured | Not measured |
| Not measured | foreman | Not measured | Not measured |
Codex functional tests establish specific behaviors, not a speed, cost or correctness advantage over a baseline. Comparative performance remains unmeasured.
Results can vary between runs.
The task trail above illustrates the workflow. The recorded demo below comes from Claude Code; it is not a Codex measurement. Evidence and methodology.
Watch the recorded Claude Code demo
How it works · Settings · Roadmap schema · Ledger · Foreman in Codex · Codex handoff prompting
Research and validation · Benchmark instruments and retained evidence · Foundry
MIT — see LICENSE.