Getting started

Install Foreman on macOS, connect Claude Code and Codex, and run your first supervised session.

Foreman supervises agent CLIs you already have. It does not include model access, and it is not an API client — it runs the official claude and codex binaries as subprocesses, signed in to your own accounts. If you have never installed either, the setup wizard can install Claude Code for you.

Requirements

• macOS on Apple Silicon. There is no Windows or Linux build.
• Claude Code, Codex, or both — with your own Anthropic or OpenAI account.
• Git, for anything involving diffs, branches or fan-out.

1. Install

Download the .dmg from the releases page, drag Foreman to Applications, and open it. Updates arrive in-app after that; you won't need to come back here.

2. Connect your agent CLIs

On first run, Foreman checks the machine and shows you what it found. Two checks matter:

Claude CLI — whether the claude binary exists and is on your shell PATH. Three outcomes:

• Not found: the wizard offers Install Claude Code, which runs the official installer. It drops the binary in ~/.local/bin.
• Found but not on PATH: the wizard offers Add to ~/.zshenv, which appends the export line for you. It guards against duplicates, so running it twice is safe.
• Found and on PATH: you'll see the resolved path.

Claude auth — whether you are signed in, read from claude auth status.

There is an important subtlety here. claude auth status never touches the network: it reports whether credentials exist on disk. A login whose refresh token has since died still prints a cheerful email and plan right up until a turn fails with a 401. So Foreman also exercises the credential with a real, tiny turn before it shows you a green tick. A check that passes has actually worked, not merely been read.

If you are signed out, the wizard walks you through claude auth login and polls until it completes.

The wizard's automated checks cover Claude only. Codex is managed from the same UI — install, login, version checks — but it is not part of this diagnostic. If you use Codex, verify it separately from the agents screen.

3. Open a project

Point Foreman at a folder on disk. It reads the git state, and the project appears as a box on the canvas. Everything else — sessions, terminals, diffs, review — hangs off that project.

The canvas is the default view on purpose. It is a map rather than a list: each project is a box, each session inside it a card carrying live status, diff stats and cost. When you are running one agent that distinction doesn't matter. At five it is the whole product.

4. Start your first session

Create a session in the project, pick the agent (Claude Code or Codex) and the model, and send a task.

While it runs, the things worth knowing:

• The agent asks in the chat, not in a terminal prompt. Tool calls arrive as approval cards you accept or deny. If the agent proposes a plan, nothing is edited until you approve it. When it needs a decision, you get option pills instead of having to write a paragraph.
• Autonomy is per session, from ask-every-time through to unattended. Set it to match how much you trust the task, not how much you trust the agent.
• Run on decides who pays. Interactive sessions default to the subscription you already have. Scheduled, bulk and fan-out runs default to your metered API key, which keeps unattended bursts off your subscription's rate limits. You can override it per session.
• The context meter on each session shows compaction coming before it silently eats your context. When it gets close, hand the session off rather than letting it compact — Foreman distils it into a digest you edit and carries it into a fresh session.

5. Review the work

Nothing merges without you. Open the diff, read it line by line, and comment on any line to send it straight back to the agent — no terminal round-trip. If you'd rather have a first pass done for you, run an AI review of the diff at the model and effort you choose; findings arrive as line comments you can edit, delete or forward.

Where to go next

• The canvas — reading the map once you have more than a couple of sessions.
• Permissions & plan review — what each mode does, and which to pick for a task.
• Parallel fan-out — race one task across four agents and keep the best attempt.
• Session messaging — sessions that hand work to each other.
• Project review — audit the whole codebase in one pass.
• Checkpoints — find the turn that broke it and get back to before it did.
• Troubleshooting — when a CLI can't be found, or auth looks fine but every turn fails.