Settings

Most of what you might change between runs is a setting: the number of workers, the build rounds, the CI timeout, the feature switches, the JQL and more. foreman settings list shows each one, its value, where the value comes from, and when a change takes effect.

foreman settings list [--group run|models|features|learning|release|jira|notify|console] [--json]
foreman settings get workers
foreman settings set workers 2 [--team]
foreman settings reset workers [--team]
foreman features on|off followUps [--team]

A setting has two layers on top of its default:

• Team: foreman.config.json, committed, so everyone on the project gets it. --team edits the file in place and refuses a value that would make it invalid. Commit the change afterwards.
• Local: .foreman/settings.json, this computer only. This is where set writes without --team.

A local value wins over the team’s. A local value that isn’t valid is ignored, and foreman doctor warns about it by name.

Some options are not settings. session.extraTools, such as ["mcp__acme__query"], adds tool names that story sessions may use. A pack may give it a default, and a list in foreman.config.json replaces the pack’s list. The local settings and the dashboard cannot change it.

Story sessions are lean: they load Foreman, the plugins the project’s pack needs and nothing else from your own Claude Code set-up. Every session runs with --strict-mcp-config, so it starts no MCP server it is not given. Sessions also run without the tools that schedule a later wake-up (ScheduleWakeup, CronCreate): a wake-up still waiting when a session prints its result would keep it running. session.mcpServers, such as ["acmeDb"], names the servers from the project’s .mcp.json that story sessions load (default none); a name that .mcp.json does not define stops foreman run, and foreman doctor says so. Tools of those servers still need their names in session.extraTools.

session.userSettings (default false) decides whether story sessions read your user-level Claude Code settings. Off, they leave out your user-level CLAUDE.md and its imports, auto memory, hooks, skills, agents, plugins and MCP servers, and turn off the plugins the project’s own settings enable, except Foreman and the pack’s. They keep the user settings that decide how a session runs where the project’s settings do not set them: the model, effort, thinking, attribution, environment, permissions, sandbox and sign-in settings. The sign-in itself is unchanged. Set it to true to load your user settings, hooks, CLAUDE.md and memory too; plugins other than Foreman and the pack’s stay off, and MCP servers still come only from session.mcpServers.

foreman report shows each day’s average first-turn context (“first turn 21 k”), so you can see what a session starts with.

The dashboard (foreman dashboard) has a Settings tab with the same settings and the same two layers. Each row shows where its value comes from. After a team change, the tab says the config file has changed but isn’t committed yet. It also has a Waiting on you tab, which lists everything the run needs from you with a button for each action; the tab shows the count of what you can act on now, and owner tasks still waiting on open blockers fold under Later. When the architect finds a story needs another done first, Foreman asks you to approve the depends_on change. With features.autoApplyDependsOn on (off by default) it adds it at once, puts the story back to todo and tells you under FYI, with Undo and Keep. When a shipped story leaves minor findings, foreman learn asks whether to create a follow-up story for them. With features.autoCreateFollowUps on (off by default) it creates each one at once instead (with priority Low on Jira, where the project allows it) and tells you in one note under FYI, with Undo and close them, which closes the ones not started yet, and Keep them. features.followUpsOfFollowUps still decides whether a follow-up’s own findings get a follow-up at all. While follow-up proposals wait on you, the standby line says how many. foreman learn runs after each shipped story as well as on standby and when the run stops, so the proposals exist while other stories still build. When you answer a question or task a story stopped on, Foreman puts that story back to todo with your answer for the architect, within seconds, even while other stories build. A story left In Progress with nothing running it is named in foreman status and on Waiting on you.

When a change takes effect:

• Next story: almost everything, including workers, rounds, the feature switches, the release timeouts and the Jira settings. Foreman reads the settings again before each pick.
• Next run: features.keepAwake.
• Restart: slots, console.port and console.host.

If foreman.config.json stops being valid while a run is going, the run carries on with the last valid config. It logs one warning, sends one notification, and shows “config invalid since HH:MM: <reason>; running on the last good config” under Waiting on you and in foreman status. Meanwhile the dashboard and foreman status keep showing the stories from the last good config. Fix the file and the run uses it from the next pick. When Foreman’s own plugin code changes under a run, the run 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. When Foreman builds the repo its plugin runs from, the run brings each merged story into that checkout by itself, if the checkout is on the base branch with no uncommitted changes. Otherwise it leaves the checkout alone and shows one warning that the new code waits for you to pull.

Foreman also tells you when a run is going but not getting anywhere. If it has a story it can build and a free slot but starts nothing for 10 minutes, hits the same error on every loop for 5 minutes, or a story shows no activity for 20 minutes (no stage change, no output in its session log, no CPU use), it shows one “Not building for N minutes: <reason>” item under Waiting on you, and foreman status reads “running, but stuck: <reason>”. It sends one notification, and the item clears by itself when work moves again.

A stage that runs longer than 45 minutes while its session is still active is slow, not stuck. It shows as an FYI under Waiting on you and in foreman status, for example “slow: ACME-1 in its fix round for 1 h 45 min (129 steps)”, with no notification. Set the limits with watchdog.idleMinutes, watchdog.errorMinutes, watchdog.activityMinutes and watchdog.progressMinutes.

When the run reaches standby with things waiting on you, it logs one event and sends one standby notification that counts them and says what an answer starts, for example “Standby: 3 follow-up proposals and 1 owner task wait on you; finishing ACME-300 starts ACME-301.” Nothing is sent when nothing waits, and the email is not sent again while its text is the same. An owner task that has held a story for more than watchdog.ownerTaskHours (default 24, fractions allowed) is told once, in an owner-task notification that names the story it holds. Foreman counts the hours from when it first saw the task holding something back.

When the Claude API rate-limits or is down, Foreman waits and carries on. The waits grow, 15, 30, 60 and then 120 minutes, and stay at 120: a limit or outage never pauses the run, and a story that finishes (or any other ending that is not a limit) starts the 15 minutes again. While it waits, Waiting on you and foreman status show an FYI such as “The Claude API is limited or down (wait 2); Foreman tries again at 14:05 by itself.” A story that had already committed shows “held until the API is back (retry at HH:MM)” and resumes by itself when the wait ends or the pause is lifted. Resume carries it on sooner. A story held by a failed release is different: it waits for “I’ve fixed it”.

Only a story the pipeline rejected counts toward the pause after three that did not ship in a row. A story that stops to wait on you (a question, an owner task, a depends_on proposal) is neither a miss nor a success, so a story waiting on you never counts toward the auto-pause. A crash, a watchdog stop, CI that never started, a conflict Foreman could not settle, or a test file that would not load counts as the environment instead. Three of those in a row make Foreman wait 15 minutes, then 30, then 60, each time with an event that names them and says it was the environment, not the stories. The run pauses only after those waits, saying the same. Learned traits are not rolled back for a failure the environment caused.

A session that has printed its result but is still running a minute later (for example, waiting on a tool server that never closes) is ended with a warning, and its result stands. watchdog.outliveMinutes sets the wait. So is a session still running a minute after its story was ended with foreman story end, for example because a pipeline it started is still going. The warning names the story, the slot and the story are freed at once, and the result it recorded stands.

A story that makes no progress for 2 hours before its commit (no stage change, no agent starting or finishing, and no step by any agent) is stopped and started again, and the warning names the last progress seen, for example “last step 3 h 02 min ago by foreman:builder”; so is one with no activity at all for 30 minutes. A story that keeps progressing is not stopped for its length alone, only at the hard limit of 4 times the build limit, and then its slot waits for you with Resume, Restart, Skip and Take over. A story started again after a stop carries on from its last finished stage: its plan is kept, and while its folder is unchanged, so are its build and the tests and reviews already approved. foreman report shows how many stories the watchdog stopped and the tokens and agent time spent redoing work. Set the limits with watchdog.buildMinutes and watchdog.quietMinutes.

The build limit and the hard limit never stop a session that has already ended its story, or whose story is done, retired or ready to promote, or whose pull request has merged. If such a session then shows no activity for the quiet limit, Foreman ends it without starting it again: its slot is freed and the result it gave its story stands. A session that is releasing its story gets 15 minutes past the build limit and the hard limit, so it is not stopped in the middle of a merge. When a session ends without a result, Foreman starts it again only if its story is not finished and its pull request has not merged. Otherwise it frees the slot, and when only the pull request merged it marks the story done first.

Every setting, in a table

These are the settings foreman settings list shows and the dashboard’s Settings tab edits, by group. “What it does” is each setting’s own description, the one the tab shows as its hint. “When it applies” is Next story (read fresh before each pick), Next run (read when the supervisor starts) or Restart (the run or the dashboard must restart). The feature switches are in the next section. Keys whose names look like secrets (token, secret, password, key) are never settings; they live in .env.foreman and the Set up tab’s key cards.

Run

Name	What it does	Default	When it applies
workers	How many stories build at the same time. foreman run --workers N overrides it for that run. 1 to slots.	1	Next story
slots	How many repo copies (git worktrees) Foreman keeps, one per story building. Workers can’t exceed it. 1 to 8; the Salesforce pack caps it at one slot per build org.	1	Restart
rounds	How many times the builder can fix what the tester or reviewers found before the story fails. 1 to 10.	3	Next story
watchdog.quietMinutes	Stops an agent session that has printed nothing for this many minutes, as it is probably stuck.	30	Next story
watchdog.buildMinutes	Stops a story with no stage change or agent finishing for this many minutes, and any at 4 times it.	120	Next story
claude.fallback	What sessions do when the Console API key runs out of credit: use your subscription (subscription), or pause (none).	subscription	Next story
checkRuns.maxParallel	How many full test runs may go at once across all slots. Unset, one per 8 cores, at least 1. 1 to 64.	unset	Next story

Agent models

One setting per role the project has, named roles.architect.model, roles.tester.model, roles.builders.<name>.model and roles.reviewers.<name>.model: the Claude model this agent runs on, one of haiku, sonnet, opus or fable. Unset, it uses the story session’s model; the tab’s dropdown calls that “Same as the story session”. Next story. See Agents and traits.

session.model is in the same group: the model of the story session itself, which moves the story between stages and ships it, and does not change any agent’s model (foreman settings set session.model sonnet). Unset, the Claude CLI’s own default applies.

Each reviewer also has an engine row, roles.reviewers.<name>.engine, written as engine:model, such as antigravity:claude-opus-4-6-thinking. Setting it writes the reviewer’s engine block (its name and model; a minutes already there is kept), and emptying it removes the whole block. With an engine set, the reviewer’s model row is the Claude model it falls back to when the engine cannot run; without one, it is the model the reviewer runs on. Next story.

Learning

Name	What it does	Default	When it applies
learning.auto	Foreman learns traits and skills from repeated mistakes by itself and says so in Waiting on you.	true	Next story
learning.apply	The agents get learned traits and skills from the next story. Off still learns but uses none of it.	true	Next story
learning.model	The Claude model that proposes learned traits: haiku, sonnet or opus.	haiku	Next story
learning.skillModel	The Claude model that writes learned skills: haiku, sonnet or opus.	sonnet	Next story
learning.window	How many stories using a learned item Foreman watches before keeping or rolling it back. At least 3.	5	Next story
learning.maxPerRole	The most learned traits one role can hold.	8	Next story
learning.maxSkills	The most learned skills Foreman keeps.	10	Next story
learning.maxEvaluating	How many learned items can be on trial at the same time.	2	Next story
learning.maxPerDay	The most learned changes Foreman makes in one day.	3	Next story
learning.maxUsdPerDay	The most the learner sessions may spend in one day: a daily spend cap, in US dollars.	a small daily cap	Next story
learning.redact	Words or patterns removed from findings before the learner sees them.	none	Next story

See How Foreman learns for what each one changes.

Release

Name	What it does	Default	When it applies
ship.ci.timeoutMinutes	How long to wait in total for the pull request’s checks to finish.	30	Next story
ship.ci.settleSeconds	How long checks must stay finished, with no new one, so a fast check cannot pass before the real CI.	90	Next story
ship.deploy-github.timeoutMinutes	How long to wait for the GitHub deployment to finish.	15	Next story
ship.watch.minutes	How long to watch for errors after a deploy. Shown only when ship.watch is configured.	10	Next story
ship.watch.everySeconds	How often the watch runs its command. Shown only when ship.watch is configured.	60	Next story
ship.smoke.urls	Live pages to load after a deploy, to check the site is up.	none	Next story
ship.pr.into	The branch pull requests merge into. Leave empty to use baseBranch, the branch stories start from. Never the pack’s production branch.	unset	Next story
ship.merge.keepBranch	Keeps the story branch after its pull request merges, instead of deleting it.	false	Next story

Jira

Shown only when stories.adapter is "jira"; neither layer may set them otherwise.

Name	What it does	Default	When it applies
stories.jql	The Jira search (JQL) that picks which issues are stories. Its ORDER BY sets the build order.	unset	Next story
stories.pollSeconds	How long Foreman reuses the story list before asking Jira again. 0 asks every time.	60	Next story
stories.ownerLabel	Issues with this label are tasks for you. Foreman never picks them.	foreman-owner	Next story
stories.transitions	The Jira transition for started, blocked, review, failed, shipped. An event left out moves nothing.	none	Next story

Notify

Name	What it does	Default	When it applies
notify.to	Where notifications are emailed. Leave empty to use FOREMAN_NOTIFY_EMAIL, then your git email. Shown only when notify.adapter is "email-resend".	unset	Next story

Console

Shown only when console.adapter is "dashboard" (the default).

Name	What it does	Default	When it applies
console.port	The port the dashboard runs on. 1 to 65535.	4317	Restart
console.host	The address the dashboard listens on. The default is the loopback address, which keeps it on this computer only.	this computer only	Restart

Watchdog keys that are not settings

The other watchdog limits are config keys in foreman.config.json only, each a positive number of minutes (or hours): watchdog.idleMinutes (10), watchdog.errorMinutes (5), watchdog.activityMinutes (20) and watchdog.progressMinutes (45) for the progress watchdog, watchdog.outliveMinutes (1) for a session still running after its result, and watchdog.ownerTaskHours (24) for the owner-task reminder. See foreman.config.json.

Feature switches

A switch is a boolean setting under features. foreman features on|off <name> [--team] flips one, as does foreman settings set features.<name> true|false, and the Settings tab lists them under Features with the label and description below. Every switch takes effect from the next story, except keepAwake, which takes effect when the run next starts.

Name	Label	What it does	Default
features.learnTraits	Trait proposals	When one finding keeps sending stories back, foreman learn suggests a trait. You approve each one.	on
features.followUps	Follow-up proposals	foreman learn suggests a new story to fix the minor findings a shipped story left behind.	on
features.followUpsOfFollowUps	Follow-ups of follow-ups	Also suggest follow-ups for stories that were themselves follow-ups. Off stops them chaining.	off
features.autoCreateFollowUps	Create follow-ups without asking	Creates each follow-up story at once and tells you, with an Undo. Off asks you first.	off
features.dependsOnProposals	depends_on proposals	Proposes a depends_on a story is missing. You approve each, unless Apply depends_on proposals is on.	on
features.autoApplyDependsOn	Apply depends_on proposals	Adds a dependency the architect asks for at once and tells you, with an Undo. Off asks you first.	off
features.productionGuard	Production guard	Stops the tester and reviewers from reaching production servers while they check a story.	on
features.watchRollback	Watch and rollback	After a deploy, watches for errors and rolls back if any appear. Needs watch and rollback set up.	on
features.mergeableRecheck	Mergeable recheck	Just before release, checks again that the pull request still merges cleanly.	on
features.notifications	Notifications	Sends notifications through your notifier, for example email. Off writes them to the outbox only.	on
features.costMetrics	Run records	Records each story’s cost, rounds, time per stage and tokens per agent, for foreman report.	on
features.keepAwake	Keep awake	Stops a Mac from sleeping while the run is going.	on
features.jiraComments	Jira comments	Posts Foreman’s notes as comments on the Jira issue.	on
features.jiraTransitions	Jira transitions	Moves the Jira issue along its workflow as the story moves.	on
features.salesforceComments	Salesforce comments	Posts Foreman’s notes as private comments on the Salesforce Case.	on
features.salesforceStatuses	Salesforce statuses	Sets the Case status as the story moves.	on

One more entry sits in the Features group but is not a switch: features.jiraCommentDetail (label “Comment detail”), summary or full, decides whether Foreman’s story comments list each finding in full or only count them. Default summary, next story.

With watchRollback or mergeableRecheck off, the matching ship step is dropped from the release. With notifications off, every email goes to .foreman/outbox/ instead; see Notifications. The Jira switches matter only with the Jira story source, and the Salesforce ones only with Salesforce Cases as the source; see Stories from Jira and Stories from Salesforce.