Settings and switches

A setting is a key of foreman.config.json you can change without opening the file: from the command line with foreman settings, or in the dashboard’s Settings tab. A feature switch is a setting that is simply on or off. This page lists every one with its default and when a change takes effect. Read Settings first for the idea; come here when you need the exact name or limit.

Every setting has two layers on top of its default. The team layer is foreman.config.json itself, committed, so everyone gets it; --team edits it in place and refuses a value that would make the file invalid. The local layer is .foreman/settings.json, this machine only, a flat object of name to value; this is where set writes without --team. A local value wins over the team’s. A local value that is not valid, or that names a setting this project does not have, is ignored and foreman doctor warns about it by name.

Applies says when a change counts:

• next-story: read fresh before each pick, so the next story to start uses it.
• next-run: read when the supervisor starts; the current run keeps the old value.
• restart: the dashboard server or the slots must restart. foreman stop, then run again.

Only the keys below are settings. A name that looks like a secret (token, password, apiKey and the like) is never one: secrets go in the env file. Keys such as session.extraTools, the watchdog limits other than the first two, and every adapter option that is not listed here are changed in the file only; see foreman.config.json.

A few settings exist only for some projects. The Jira ones appear only when stories.adapter is jira; the watch ones only when ship.watch is configured; notify.to only with the email-resend notifier; the dashboard host and port only with the dashboard console. A hidden setting cannot be set on either layer.

The commands

foreman settings list [--group run|models|features|learning|release|jira|notify|console] [--json]
foreman settings get <name>
foreman settings set <name> <value> [--team]
foreman settings reset <name> [--team]
foreman features                      # lists the switches
foreman features on|off <name> [--team]

list prints each setting’s name, value, source (default, team or local) and when it applies. set prints what it changed, and after a team change reminds you to commit; when a local value still wins on this machine it says so and names the reset that drops it. On the command line a boolean takes true, on, yes, false, off or no; a list takes comma-separated text or a JSON list; a map takes a JSON object such as {"started":"In Progress"}. foreman features on followUps is shorthand for foreman settings set features.followUps true. The full flags are on Every command.

Settings

Run

Name	What it does	Default	Applies
workers	How many stories build at the same time. foreman run --workers N overrides it for that run. From 1 to slots.	1	next-story
slots	How many repo copies (git worktrees) Foreman keeps, one per story building. Workers cannot exceed it. From 1 to 8; the Salesforce pack allows at most one per build org.	1	restart
rounds	How many times the builder can fix what the tester or reviewers found before the story fails. From 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. Above 0.	30	next-story
watchdog.buildMinutes	Stops a story with no stage change or agent finishing for this many minutes, and any story at four times it. Above 0.	120	next-story
claude.fallback	What sessions do when the Console API key runs out of credit: subscription uses your subscription, none pauses.	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. From 1 to 64.	unset	next-story

Agent models

One setting per role the project has, made from its roles block: roles.architect.model, roles.builders.<name>.model for each builder, roles.tester.model, and roles.reviewers.<name>.model and roles.reviewers.<name>.engine for each reviewer. session.model is in the group too. The dashboard lists them under Models. A reviewer’s model lives inside the roles.reviewers array in the file, so its setting name is not its path there; the team layer writes it in the right place. Setting one on the team layer when your file has no roles block copies that whole part of the block from the resolved config first, so a pack project keeps its pack builders. See Agents and traits.

Name	What it does	Default	Applies
roles.architect.model	The Claude model the architect runs on. Unset, it uses the story session’s model. One of haiku, sonnet, opus, fable.	unset	next-story
roles.builders.<name>.model	The same, for the builder of that name.	unset	next-story
roles.tester.model	The same, for the tester.	unset	next-story
roles.reviewers.<name>.model	The same, for the reviewer of that name. With an engine set, it is the model the reviewer falls back to when the engine cannot run.	unset	next-story
roles.reviewers.<name>.engine	The other CLI this review runs through, as engine:model, such as antigravity:claude-opus-4-6-thinking. Setting it writes the reviewer’s engine block (name and model; minutes is kept). Emptying it removes the whole block. The engine must be antigravity.	unset	next-story
session.model	The model of the story session itself, which moves the story between stages and ships it. It does not set the agents’ models. Unset, the Claude CLI’s own default applies. One of haiku, sonnet, opus, fable.	unset	next-story

Learning

How Foreman learns explains the words.

Name	What it does	Default	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. One of haiku, sonnet, opus.	haiku	next-story
learning.skillModel	The Claude model that writes learned skills. One of haiku, sonnet, 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. At least 0.	8	next-story
learning.maxSkills	The most learned skills Foreman keeps. At least 0.	10	next-story
learning.maxEvaluating	How many learned items can be on trial at the same time. At least 0.	2	next-story
learning.maxPerDay	The most learned changes Foreman makes in one day. At least 0.	3	next-story
learning.maxUsdPerDay	A daily spend cap for the learner sessions, in US dollars. At least 0.	set by Foreman	next-story
learning.redact	Words or patterns removed from findings before the learner sees them.	[]	next-story

Release

Name	What it does	Default	Applies
ship.ci.timeoutMinutes	How long to wait in total for the pull request’s checks to finish. Above 0.	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. Above 0.	90	next-story
ship.deploy-github.timeoutMinutes	How long to wait for the GitHub deployment to finish. Above 0.	15	next-story
ship.watch.minutes	How long to watch for errors after a deploy. Above 0. Only when ship.watch is configured.	10	next-story
ship.watch.everySeconds	How often the watch runs its command. Above 0. 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.	[]	next-story
ship.pr.into	The branch pull requests merge into. Leave empty to use baseBranch, the branch stories start from. Must be a plain branch name on either layer, and never the Salesforce pack’s productionBranch: nothing merges into production.	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. See Stories from Jira.

Name	What it does	Default	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. At least 0.	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. Only those five keys, each non-empty text.	{}	next-story

Notify

Name	What it does	Default	Applies
notify.to	Where notifications are emailed. Leave empty to use FOREMAN_NOTIFY_EMAIL, then your git email. Only with the email-resend notifier.	unset	next-story

Console

Only with the dashboard console.

Name	What it does	Default	Applies
console.port	The port the dashboard runs on. From 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.	the loopback address	restart

Feature switches

Every switch is a boolean setting named features.<name>; foreman features on|off <name> and the dashboard’s Features group change them, and foreman features alone lists them. All apply from the next story except keepAwake, which applies from the next run. One entry in the group, jiraCommentDetail, is a choice rather than a switch and is listed at the end. Settings says what turning each one off looks like in practice.

Name	What it does	Default	Applies
learnTraits	Trait proposals. When one finding keeps sending stories back, foreman learn suggests a trait. You approve each one.	true	next-story
followUps	Follow-up proposals. foreman learn suggests a new story to fix the minor findings a shipped story left behind.	true	next-story
followUpsOfFollowUps	Also suggest follow-ups for stories that were themselves follow-ups. Off stops them chaining.	false	next-story
autoCreateFollowUps	Creates each follow-up story at once and tells you, with an Undo. Off asks you first.	false	next-story
dependsOnProposals	Proposes a depends_on a story is missing. You approve each, unless autoApplyDependsOn is on.	true	next-story
autoApplyDependsOn	Adds a dependency the architect asks for at once and tells you, with an Undo. Off asks you first.	false	next-story
productionGuard	Stops the tester and reviewers from reaching production servers while they check a story. The hosts come from ship.productionHosts, else the smoke URLs and the Supabase project.	true	next-story
watchRollback	After a deploy, watches for errors and rolls back if any appear. Needs ship.watch and ship.rollback set up; off leaves the watch step out of the release.	true	next-story
mergeableRecheck	Just before release, checks again that the pull request still merges cleanly. Off leaves the mergeable-recheck step out.	true	next-story
notifications	Sends notifications through your notifier, for example email. Off writes them to the outbox only.	true	next-story
costMetrics	Run records. Records each story’s cost, rounds, time per stage and tokens per agent, for foreman report.	true	next-story
keepAwake	Stops a Mac from sleeping while the run is going.	true	next-run
jiraComments	Posts Foreman’s notes as comments on the Jira issue.	true	next-story
jiraTransitions	Moves the Jira issue along its workflow as the story moves.	true	next-story
salesforceComments	Posts Foreman’s notes as private comments on the Salesforce Case.	true	next-story
salesforceStatuses	Sets the Case status as the story moves.	true	next-story
jiraCommentDetail	Whether Foreman’s story comments list each finding in full or only count them: summary or full. Not a switch, so foreman features does not take it; use foreman settings set features.jiraCommentDetail full.	summary	next-story

The two Salesforce switches belong to the Salesforce pack, which is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org, and the Gearset path has not run against a live Gearset pipeline.