Install

This page is for whoever puts Foreman on a project for the first time: what the machine and the project need, how the install goes, which Claude sign-in the story sessions use and how to move to a later release. Once Foreman is installed, Your first story takes over.

Foreman runs on macOS and Linux. On a Windows PC it runs inside WSL2: set that up first, with Foreman on Windows, then come back here.

In Claude Code, run:

/plugin marketplace add finefactory-ai/foreman#v0.11.0
/plugin install foreman@foreman

The source and every release are at github.com/Finefactory-ai/foreman.

Then, in your project, run /foreman:init. It looks at your stack and opens the Set up page (foreman setup). The page walks each step, from foreman.config.json to the sign-ins, and takes each key on its own card, so you never edit an env file by hand. With no browser, the same steps run in the chat through foreman setup next, and keys go in with foreman keys set NAME, which reads the value without showing it. For a pack project, such as Salesforce, /foreman:init asks the pack’s questions in the chat first. It ends with foreman doctor. The Salesforce pack is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org.

Workflows need a paid Claude plan or the API. On Pro, turn them on in /config.

Licence

Foreman is free to use, change and share, at work included, under the Functional Source License (FSL-1.1-ALv2). You may not offer it, or something built from it, to others as a commercial product or service that replaces Foreman or does much the same job. Two years after a release is published, that release also becomes available under the Apache License 2.0. Foreman claims no rights in the code it writes in your projects. This is a summary; the LICENSE file that comes with Foreman governs.

What you need

foreman doctor checks every item below that a program can check, and The Set up tab shows the same checks grouped by step, with a Test it button on each. The full list of checks is on Doctor checks.

Name	What Foreman needs	How doctor checks it
Claude Code	Installed, with claude on the PATH. Foreman runs its agents in Claude Code, through the plugin.	claude on PATH runs claude --version; a failure is a FAIL that says to install Claude Code and open a new terminal.
A paid Claude plan or the API, with workflows on	Foreman’s pipeline is a Claude Code workflow. Workflows need a paid plan or the API; on Pro, turn them on in /config.	workflows always warns, because the doctor cannot detect this.
A Claude sign-in	A Console API key, a subscription token or the claude.ai login on the machine. The next section says which one the sessions use.	claude sign-in names the sign-in in use and warns when it is a subscription.
Node 22 or later	The foreman command and the supervisor run on Node (engines.node >= 22).	The supervisor starts on the Node that ran foreman run; when that Node stops answering, as after a Homebrew upgrade, it picks the first that does. background service warns when the service points at a Node that is gone or does not start.
git, with a remote	The project is a git repository with a remote named origin, or whatever remote in foreman.config.json says.	git remote runs git remote get-url <remote>.
The GitHub CLI, signed in	Foreman pushes each story to a branch, opens a pull request and merges it through gh.	gh signed in runs gh auth status; the fix is gh auth login, to an account that can push to the repository.
A GitHub repository	The remote is on GitHub, and the base branch is protected so only checked pull requests reach it.	branch protection warns when protection is off, when the repository’s plan does not allow it (a private repository on the free plan), or when it cannot be checked. Never a FAIL.
The project’s own tools and checks	Each tool the configured adapters and ship steps need, and every check in checks with when: "always" passing on this machine.	tools runs command -v for each tool; check: <run> runs each always-check with sh -c; docker compose runs docker compose version when env.adapter is docker.
macOS or Linux	Foreman runs on macOS and Linux, and on Windows inside WSL2: see Foreman on Windows. The background service hands the run to launchd on a Mac or systemd --user on Linux.	background service says “no service manager on this computer” where there is neither; foreman run still runs in the background without the service.

Foreman never asks for a database, a hosted account or anything beyond the project’s own tools. Everything else it needs, such as the Jira app keys or the Resend key, is tied to an option you turn on, and the doctor asks for it only then.

Which Claude sign-in the sessions use

foreman doctor says which Claude sign-in the sessions use: a Console API key (ANTHROPIC_API_KEY, billed per token), a subscription token (CLAUDE_CODE_OAUTH_TOKEN, from claude setup-token), or the claude.ai login on the machine. When both variables are set, the API key wins. A subscription is for your own projects; selling Foreman, or running it for others, needs an API key.

Foreman follows Claude Code’s own order and stops at the first that applies. The claude sign-in check (Set up › Claude sign-in) names what it found and reads names only, never a value.

Name	What it means	What doctor says
A cloud provider: CLAUDE_CODE_USE_BEDROCK (Amazon Bedrock), CLAUDE_CODE_USE_VERTEX (Google Vertex AI) or CLAUDE_CODE_USE_FOUNDRY (Microsoft Foundry), set to anything but 0, false, no or off	The sessions go through that provider, billed by your cloud account.	ok
ANTHROPIC_AUTH_TOKEN	A gateway or proxy token, billed by whoever runs the gateway.	ok
ANTHROPIC_API_KEY	A Console API key, billed per token. When CLAUDE_CODE_OAUTH_TOKEN is set too, the key wins.	ok
CLAUDE_CODE_OAUTH_TOKEN	A subscription token, which counts against your plan’s limits.	warn: a subscription is for your own projects only
The login on this machine, read with claude auth status --json only when no variable decides	A Console key stored by Claude Code counts as the API key. A claude.ai login counts against your plan’s limits.	ok for a stored key; warn for a claude.ai login; FAIL when nothing is signed in; warn when the status cannot be read

The two variables are read from the environment first, then from .env.foreman, Foreman’s own keys file at the project root (foremanEnvFile in the config). The project’s env file (.env.local) is never read for them: that file is linked into every story workspace, and foreman doctor warns (foreman keys placement) until foreman keys migrate moves them out. Save a key on Set up › Claude sign-in, whose two cards are Console API key and Subscription, with a third card, Already signed in on this computer, when Claude Code is signed in there; or run foreman keys set ANTHROPIC_API_KEY or foreman keys set CLAUDE_CODE_OAUTH_TOKEN. A Console key must start with the Console key prefix and a token with the token prefix; a value pasted under the wrong card is refused with a line that names the right one. Test it asks Anthropic whether it takes the key; for the token it asks Claude one short question, which uses a few tokens.

With both set, the sessions use the API key’s credits first. When they run out, or the key reaches the usage limit set on it in the Console, Foreman switches every later session to your subscription (the token, else the claude.ai login), runs the story that hit it again, and tells you once. That is claude.fallback: "subscription", the default; "none" pauses the run instead. It never switches back by itself: after topping up the credits, or once the key’s access returns, run foreman claude use-key, or press Use the API key again on the Set up tab.

The switch is recorded in <stateDir>/claude-signin.json, with the time and the reason, and never a key’s value. While it stands, foreman doctor reads “Since <date> the platform credits ran out, so sessions use your subscription”, or names the usage limit and when access returns when Claude Code said, and Waiting on you carries the same note. When no subscription sign-in can be found, Foreman pauses instead and says why: set CLAUDE_CODE_OAUTH_TOKEN or run claude auth login, top up or raise the limit, then press Resume. foreman claude use-key refuses when no ANTHROPIC_API_KEY is in the environment or in .env.foreman (“add the key first”), and otherwise answers “Sessions use the Console API key again from the next story”, or “Already using the Console API key”. The claude block holds the one key, fallback.

When the subscription itself reaches its usage limit, or the account is out of credit, Foreman pauses and says when it will try again: at the reset time Claude printed (the Friday reset, say), else in an hour. Then it asks Claude one cheap question, and carries on by itself, with one note in the feed, as soon as Claude answers; if not, it asks again every 30 minutes. Resume still starts it sooner, and your own pause (foreman pause) is never lifted this way. See When things go wrong.

Moving to a later release

To move to a later release, change the marketplace’s tag. claude plugin update stays on the tag the marketplace was added with. From a terminal, outside your project (removing the marketplace uninstalls the plugin, and inside a project it also edits that project’s settings):

claude plugin marketplace remove foreman
claude plugin marketplace add finefactory-ai/foreman#v0.11.0
claude plugin install foreman@foreman

Afterwards, run foreman doctor in the project. plugin installed and enabled fails when the plugin is missing for the project or installed but turned off, and plugin fresh warns when the installed copy is not the code the run loads, naming both versions. A run that is going does not need stopping: when Foreman’s own code changes under it, the supervisor restarts itself on the new code within a few seconds and carries on, the stories in progress keep running through the restart, and free slots start new stories straight after it. Each release names its fixes in the changelog, and the settings you changed stay where they were, in foreman.config.json and .foreman/settings.json.