forge.toml reference

forge.toml is the only file forge reads for configuration. It is hand-authored; two paths write it - the settings page’s save and the settings MCP tools (settings__index and settings__get read it, settings__set and settings__unset write it) - and both writers go through the same catalogue, validation and validated-temp-file writer, with an agent’s edit held for the reader’s approval before it applies. Nothing else in forge does. A change is picked up while forge runs: the server watches this one file, re-reads it whole, and applies what can take effect without a restart. A running session keeps the account it spawned on, its model, mode, cwd and child environment; its credential is resolved per request, so a re-minted token reaches it. Everything a subsystem reads per use takes the new value, and the table below says what waits for a restart.

Two directories in the config directory belong to forge: the skills it ships. The handoff skill lands at <config_dir>/skills/handoff/SKILL.md, and the wizard at <config_dir>/skills/wizard/SKILL.md, with the bash library its stages ride beside it at template.sh. Forge installs both at boot, compares every file byte for byte, and rewrites only what differs, so an unchanged copy is left untouched. Only a temporary file the installer itself left behind, or a name the skill retires, is ever removed; anything else you put in those directories is left alone. They are forge’s own; forge.toml stays yours.

Where it lives

<config_dir>/forge/forge.toml

<config_dir> is $CLAUDE_CONFIG_DIR when that variable is set to a non-empty value, and $HOME/.claude otherwise. If $CLAUDE_CONFIG_DIR is unset and the home directory cannot be resolved, forge refuses to launch rather than substituting a path derived from the directory it was launched from.

If the file is absent, forge exits with:

forge.toml not found at <path>; create it with at least one [[orgs]]
entry containing one [[orgs.projects]] entry

The shape

Two things are required: at least one org, and at least one account. Orgs hold projects. Accounts are the provider endpoints and credentials forge can spawn a session under. An org names the subset of accounts its projects are allowed to use.

Everything else is optional.

[[orgs]]

An array of tables. At least one is required, or the load fails with no [[orgs]] entries in forge.toml.

browser_profile names the browser every project in the org drives. The key is the org and the name joined - browser_profile = "work" under name = "Busytools" is the profile Busytools/work - and its cache and logins live under the server’s browser/profiles/Busytools/work/cef. A name is 1 to 64 characters of letters, digits, dot, dash or underscore, and a bad one fails the load naming the key and the value. A project’s own browser_profile keeps the same name inside its org and overrides the org’s.

accounts is the account subset every project in this org may spawn under. Rules enforced at load:

• An empty list (accounts = []) fails with has an empty accounts = [] list.
• A name that matches no [[accounts]] entry fails, and the error lists the valid names.

fallback_accounts is walked after the org’s accounts: a fallback declaring the project’s model outranks a saturated or bailed primary, and the primary is taken again once it heals. The names also carry as the fallback pin on the accounts subject. The list is validated at load exactly like accounts: a name matching no [[accounts]] entry fails the boot, naming the account and the valid names. An account may appear in both lists; it is then a primary only.

accounts and fallback_accounts must also agree on any env that changes the shape of a request, not only where it is sent. A child’s env is frozen when its session spawns and the gateway never respawns it, so after a rotation the next account is handed a request shaped for the account the session started on. The live example is CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: OpenRouter sets it and Zai leaves it unset, both declare glm-5.3-flash, and OpenRouter rejects the beta shape the flag suppresses. A project declaring glm-5.3-flash in an org holding both would spawn on Zai and then fail every rotation onto OpenRouter; the way out is to change one of the two declarations and start that session again.

[[orgs.projects]]

Project names are the argument forge <PROJECT> takes, and the key per-project settings hang off.

[[accounts]]

An array of tables. At least one is required, or the load fails with no [[accounts]] entries in forge.toml.

All accounts share one claude config directory, so MCP servers, plugins and settings are declared once for every account; what varies per account is exactly the flat block above.

model_aliases covers the case where the name the gateway sees is not the name you configured. Long-context models are the usual reason: the claude CLI is handed claude-opus-5[1m], and the request body it then sends carries the plain claude-opus-5. Matching the body’s model against models alone would refuse that request, so the plain spelling is declared as an alias of the marker. A request naming any member of a model’s set - the declared name or any alias of it - matches the account, so one account serves both spellings. forge never interprets the names; an alias is matched as data.

provider has no default. Accounts that omit it are named together in one load error listing the accepted values, so a first run does not surface them one restart at a time. Silence is the dangerous answer here: a mislabelled account probes the wrong endpoint and then cannot reach a usable state, which stops forge starting.

The line has to sit above the account’s [accounts.env] table. TOML scopes every key after a table header into that table, so a provider written below one is read as an environment variable and the account still counts as missing it.

"anthropic" accounts may omit base_url: the gateway constant is their upstream. "codex", "openrouter" and "zai" require it, and an account declaring any of them without a base_url fails the load naming the account and the missing key.

For "openrouter" the base url must be the API root, https://openrouter.ai/api, and an account whose base does not end in /api fails the load. The bare host is the trap worth naming: forge probes {base}/v1/key, and https://openrouter.ai/v1/key answers 200 with a web page rather than a 404, so nothing downstream could tell it apart from a real reply.

The split is billing, not auth. "codex" is a base-url account whose proxy serves the same windowed body Anthropic does, so it reads as a subscription with rolling windows. "zai" is a subscription too: its usage is probed at the monitor host derived from the base url’s host root and read as rolling 5-hour and weekly credit windows. "openrouter" is pay-per-token: there is no window, so its usage is money spent over a period rather than a percentage of a plan. A key may carry a spending cap set from the provider’s dashboard, and where it does forge reads the spend against it as a percentage too; an uncapped key has no denominator, and forge says so rather than showing an empty bar.

Unknown keys in an [[accounts]] block are rejected, so a near-miss like providers fails the load instead of loading and doing nothing.

[env]

A flat table of string keys to string values, stamped onto every spawned claude subprocess. Absent means empty.

[env]
CLAUDE_CODE_AUTO_COMPACT_WINDOW = "950000"

[models."<name>"]

Optional per-model tables, keyed by the exact spelling a project’s model pins - that is the name the read matches on, not what accounts declare - so one entry serves every project pinned to that model. Absent means no parameters are stamped and the claude CLI’s own resolution stands. A table naming a model no project pins loads, but warns at boot: the entry is read by the projects’ pins, and no pin carries that name.

[models."deepseek-v4.1-flash"]
auto_compact_window = 983040

auto_compact_window is stamped onto the spawned child as CLAUDE_CODE_AUTO_COMPACT_WINDOW. Set it below the model’s real context, leaving the compact query room to fit: compaction fires near a window’s top, and the compact request itself needs headroom beyond that for the completion budget and the prompt it carries - a window allowed to reach the model’s context can fire a compact request the context cannot hold, and the claude CLI exits with the session, which is what this key keeps out of reach. The value is yours to pick because forge does not know a model’s real context: leaving a sixteenth of the context as headroom (a 983040 window for a 1,048,576-token model) is measured to fit with room over. An env layer that names CLAUDE_CODE_AUTO_COMPACT_WINDOW itself replaces the table’s value.

A value that is not a positive integer fails the load: models "name" in forge.toml ... sets auto_compact_window = 0, which is not usable; it must name a positive window in tokens. Unknown keys inside a [models."<name>"] table are rejected, so a mistyped key fails the load instead of quietly applying nothing.

[handoff]

When a session’s context is nearly full, forge replaces it with a fresh session that continues from a brief: the work carries on, and the successor’s transcript opens with that brief, drawn as the handoff procedure. The trigger runs on by default, at the end of a turn, so a long session stops before its first compaction rather than after it.

[handoff]
enabled = true
at_percent = 85
after_compactions = 1

An absent table is exactly the defaults above. at_percent is a share rather than a token count because the denominator is the CLI’s own ContextUsage.max_tokens, which already reflects the model and any lowered auto_compact_window - 85% of a 200k window is 170k, and 85% of a 1M window is 870k, which is the same rule at a different limit.

The compaction count is a backstop, not the trigger: a turn that crosses the window before it ends compacts first, and the count is what hands that session over at the next turn boundary. A session that reaches two compactions is the alarm the handoff record exists for.

A project can carry its own table, and every key is optional - it sets the one it disagrees on and inherits the rest:

[[orgs.projects]]
name = "companies"
path = "~/Projects/companies"
# this project's sessions run unattended for days; let them finish
[orgs.projects.handoff]
enabled = false

A share outside 1..100 fails the load: the handoff table at the top level in forge.toml ... sets at_percent = 0, which is not usable; it must name a share of the context window between 1 and 100. So does after_compactions = 0, which would swap the seat on every turn. A project’s refusal names the project rather than the top level. Unknown keys inside a [handoff] table are rejected.

Per-project keys (inside [[orgs.projects]])

The per-project settings live directly on each [[orgs.projects]] entry, beside name and path. The entry rejects unknown fields, so a mistyped key fails the load loudly instead of quietly applying nothing.

permission_mode stamps a permission mode onto every session the project spawns, overriding the launcher’s per-session default. A project that does not set the key gets auto stamped rather than the launcher default, so its sessions run one mode consistently however the org’s accounts rotate. The accepted values are the CLI’s mode names, "default", "acceptEdits", "plan", "dontAsk", "auto" and "bypassPermissions", plus the legacy aliases "ask", "deny", "accept_edits", "dont_ask" and "bypass_permissions"; anything else fails the load listing them. The mode the session actually runs is what the CLI reports back on connect, and the /mode picker offers bypassPermissions only on sessions launched into it; the CLI refuses a mid-session switch to bypass.

document_roots

[[orgs.projects]]
name = "companies"
path = "~/Projects/companies"
document_roots = ["~/Madness"]

Extra roots the document read accepts beyond the session’s own tree, so a project’s documents can live outside its repo. The documents__hand_off tool, the viewer’s document read and the tree review placement all consult the seat’s project’s roots; the file-index walk does not, because it lists the session’s tree.

The check canonicalizes both sides and resolves symlinks before comparing, so a symlink whose target exists and sits out of every root refuses like any other escape - a dangling one reports the document missing, exactly as it does in-tree - and a path inside a root reads exactly as an in-tree path does. A path outside the tree and outside every root keeps the refusal it always had: the path resolves outside the session's tree: <path>.

Each entry is an absolute path, ~ (your home directory) or a ~/ path. Anything else fails the load naming the key and the entry: project 'companies' in forge.toml at ... sets document_roots entry 'Madness', which is not absolute; every entry must be an absolute path, ~ or start with ~/, because a relative root would resolve against whatever directory the read happened in.

env_file

The file is parsed as KEY=value lines. Blank lines and lines starting with # are skipped. One matching pair of surrounding single or double quotes is stripped from the value; an unmatched quote stays part of the value.

Failures here are non-fatal and warn rather than refusing to boot:

• A relative path is skipped entirely. Only absolute or ~/ paths are read, because a relative path would resolve differently depending on where forge was launched from.
• A missing or unreadable file contributes no keys.
• A line with no = is skipped; the rest of the file still applies.

The inline env table on the project entry wins over env_file per key.

[gateway]

The inference listener that spawns resolving to a project are pointed at.

Environment layering

Three layers merge per key, narrowest winning:

[env]  <  [accounts.env]  <  [[orgs.projects]] env

A project’s env block attaches to the most recent [[orgs.projects]] header - place it directly under its own entry.

The global and account layers merge at load. The project layer is applied at spawn rather than earlier, because one account serves many projects and merging sooner would leak one project’s keys into every other project on that account.

One carve-out applies to project spawns: after those layers compose, the gateway re-stamps four keys over the result - ANTHROPIC_BASE_URL (the listener with the session’s routing segments), the CLAUDE_CODE_API_BASE_URL slot, the account’s credential variable, and ANTHROPIC_API_KEY (forced empty) - so no layer can point a child away from the listener while it holds only the dummy credential.

One key is reserved by forge: CLAUDE_CONFIG_DIR. Setting it in any env layer overrides forge’s own stamp. The value still applies, since forge.toml is treated as trusted, but forge logs a warning naming the key.

A base-url account’s endpoint and credential are its flat base_url and token keys, mapped onto the CLI’s variable names at load. [accounts.env] carries only provider-behaviour extras - timeouts, context caps, fallback switches. A base-url or credential key declared in an env layer is dropped at load, so it can reach neither the child nor the pool the usage probe and the forward leg read: the flat keys own them. Setting ANTHROPIC_BASE_URL or ANTHROPIC_AUTH_TOKEN at the project layer instead desynchronises forge’s own accounting, because the usage probe, plan detection and the account pool all read the account map.

An "anthropic" account’s flat token - minted by claude setup-token - is its credential. The usage endpoint refuses setup tokens (they lack the user:profile scope), so a valid token is probed with a minimal billed messages call instead - its response headers carry the 5-hour and 7-day usage windows at roughly nine tokens per account per usage poll; a rejected token renders as an auth failure whose repair is a re-mint. A replaced token is read by the next probe and reaches a running session on its next request.

Only key names, never values, are recorded in forge’s per-spawn log line. These tables hold tokens.

Notifications

Notifications are the client’s own: a windowed client raises them through its host (a system banner, a dock badge, whatever the platform does), and there is no forge.toml key for any of it. The server raises nothing itself - it has no window to put a banner on.

On macOS the first alert after install raises the system’s notification permission prompt, and the OS drops that notification while the prompt is up. So the first ask from a fresh install is silent, and every later alert arrives normally.

A browser tab has no host process of its own, so the page asks the browser for its notification permission from the first click or keypress after an ask arrives - Firefox and Safari refuse a request made without one. A refusal is respected silently and never retried, and a page the browser offers no notifications to (an insecure origin, or a browser without the API) stays silent the same way. Either way the answer is outside forge: the browser’s own site settings for the address the client is served from, or that address being https or localhost.

There is no [ui] section either: the spinner and repaint keys the terminal drew with retired with the terminal crate, and no key replaced them. A forge.toml still carrying the section fails the load as an unknown section; see the list under “Unknown keys”.

[dictate]

Optional. Absent means dictation is off, which is also what an explicit enabled = false means.

An unrecognised key here fails the load rather than being ignored: a mistyped models_dir would otherwise fetch three gigabytes to the wrong volume with nothing said about it. device is the one exception - a declared ghost: the microphone is always the reader’s, so the key is warned about and ignored rather than obeyed, and a config still setting it keeps loading.

The models live where forge runs; the microphone is wherever the reader is: a client captures on its own machine and streams the audio to forge, where the pipeline recognises it. styling, structure and context are defaults rather than state: they reach every client in the greeting, and a client that captures holds the values in force itself, per seat, so its panel’s reset row returns to these.

With enabled = true, forge fetches, verifies and loads the models on the preflight screen before forge hands over. A first run downloads 3.07 GB, resumable and SHA-256 verified; a later run re-hashes only a file that has changed since its digest was recorded, about a second for the pair, and checks an unchanged one with a stat. Then the weights load. Pressing esc during a download keeps what has landed and quits.

A role’s model is resolved fresh each boot, in this order: the transcribe_model / cleanup_model key when set, else the last runtime pick made on this machine (kept in the state store beside forge’s other machine-local state, not here), else the compiled default for this binary. Setting a key never clears the pick, so removing the key returns the role to the last runtime choice rather than to the compiled model.

A key names a variant, not a path (granite-speech-5.0-470m-turboctc): this file syncs across machines and a path is per-machine. The variant resolves through the machine’s installed models first - a local file, no network - and then through the runtime’s catalogue, whose per-model doc carries the download URL. A variant that resolves through neither fails the boot, naming the key and the variant:

[dictate] transcribe_model names granite-470m, which is neither an installed model nor a catalogue entry

A variant that resolves but is not on disk yet is fetched by the boot preflight, the way the compiled defaults already are, and records as installed.

A key pins the role: the runtime cannot change it, and the models page refuses an activation for it, naming the key:

[dictate] transcribe_model pins this model in forge.toml; remove the key to change it here

Downloads and benchmarks stay allowed on a pinned role - a pinned role can still pull candidates down and bench them; only the running model cannot change without editing this file.

The compiled model files themselves are not configurable. Each carries a URL, a byte length and a digest, and a hand-edited one is a file nothing can verify. A model named by the keys above, or downloaded from the models page, is checked against the feed’s own byte length and the engine’s own load instead: those files publish no digest, and nothing forge prints calls one verified.

[tts]

Optional. Absent means the speaking role is off, which is also what an explicit enabled = false means. It is the other direction of the voice area [dictate] opens: a take becomes text, and a reply becomes speech.

An unrecognised key here fails the load, as one in [dictate] does: a mistyped models_dir would otherwise leave the engine looking in a directory that has no model, and the failure would surface at the boot prewarm rather than when the key is saved. language is the one exception - a declared ghost: the voice id is the language choice, and the model’s 54 voices cover eight languages, so there is nothing for the key to set. It is warned about and ignored rather than obeyed, and a config still setting it keeps loading.

The speaking model is Kokoro-82M, published by hexgrad as hexgrad/Kokoro-82M. forge installs the ONNX export that onnx-community/Kokoro-82M-v1.0-ONNX publishes, pinned to the revision the install reads: one ONNX file plus the style files for the model’s 54 named voices. The weights are Apache-2.0. The compiled default is the int8 export (kokoro-82m-int8). The local benchmark scores a model over the bundled public corpus for round-trip word error, first audio, real time factor and the peak resident set above its own baseline; the models page draws the figures a run leaves.

Rendering is in process: forge runs the ONNX session through ort and the G2P pipeline through Misaki with its bundled espeak-ng. Kokoro renders a whole clip rather than streaming inside one, so a say is split into sentences and each sentence’s audio arrives when it finishes rendering. The output is 24 kHz mono 16-bit, Kokoro’s own rate, and a model whose rate differed would be resampled once in the engine.

The model installs from the models page or the settings page’s speaking card. Every file is fetched at one pinned revision and checked against the LFS sha256 the Hub publishes; a digest that disagrees leaves nothing behind. The engine checks the whole set again before it loads it, so a truncated or substituted file is refused by name. The engine loads once at boot when [tts] is on and stays resident for the process’s life; a failed load is retried by the first say.

[huggingface]

Optional. The token a gated repository needs.

An unrecognised key here fails the load, as one in [tts] does.

[gotify]

Optional. Absent means the Gotify integration stays dormant.

Both are mandatory once the section is present; neither has a default.

[systemone]

Optional. Absent or enabled = false means the decision tools (systemone__ask_noul, systemone__ask_choice, systemone__ask_score) are not injected into any session.

base_url and model are mandatory once the section is enabled; a missing one refuses the load naming the key - the message reads [systemone] `base_url` is required when `[systemone]` is enabled (or the same sentence for model) - and timeout_ms = 0 refuses with [systemone] `timeout_ms` must be greater than zero. A key the endpoint itself rejects surfaces as a tool error naming api_key; forge never substitutes another credential.

What the endpoint takes: up to 255 options in a choice question, 2 to 10 levels in a score question, and a whole request - state, instructions and the question together - inside the live context, which OpenRouter lists as 32000 tokens for these models. Upstream describes the shape as 32k of state under a 64k request; the live 32000 is what to size against, with the state kept well inside it. It serves about 100K tokens/s at 80 requests/s and bills $0.042 per million input tokens, rates upstream notes can change without notice; the default 30s timeout_ms has ample headroom.

[vault]

Optional. Absent means the vault family (vault__search, vault__get, vault__create, vault__update, vault__trash, vault__restore, vault__totp_code, vault__attachment_get, vault__attachment_put and the four vault__folder_* tools) is not injected into any session. The family is also gated per agent through mcp_families, like every other toggleable family. Adding the section does not put the family into sessions that are already running: a session’s tool catalogue is fixed when it spawns, so a live session gains the tools only from a new spawn.

The two account keys are mandatory once the section is present. A missing one refuses the load naming the key: [vault] `url` is required when `[vault]` is present (or the same sentence for email). Setting the section from a session means sending both keys in one settings__set call: a single-key write leaves a half section the loader refuses, and that refusal comes back before the reader is asked to approve anything. An unknown key in the table refuses the load like every other section, and url must be an https:// URL: an http:// one refuses the load with [vault] `url` must be an https:// URL; http is refused. There is no built-in default, because forge.toml is the one source of truth for the account.

idle_minutes is optional and omitted means no idle lock, which is what forge did before the key existed. A number of minutes locks the shared session on the first vault read after that much time without one, and the next vault call asks for the master password or a device gesture again; 0 refuses the load with [vault] `idle_minutes` must be at least 1; omit it for no idle lock, because a zero bound would lock instantly and no one means that. The settings page’s vault card draws the state and offers the manual lock, whichever way the session was locked.

One session serves every agent and every session. It holds the derived keys in memory only, zeroized, and never stores the master password: the first vault call after a forge start parks a card whose masked field carries the password over the local answer channel, and one unlock serves every card parked behind it. A call the server rejects with 401 tries the refresh token, and only a failed refresh locks the session and makes the next held call ask again; idle_minutes adds the unused-session lock above. A reload that changes this section rebuilds the session, which locks it; a reload that leaves the section alone keeps it unlocked.

Every vault operation is held for the reader’s approval and appends one line to <app-support>/vault/audit-<config-dir-store-key>.jsonl - when, who, which tool, which item and field, the decision and the outcome, never a value. The file rotates at 10 MB into .1 through .6, so the six most recent chunks and the current file are kept.

[[slack]]

Optional, and repeatable: one entry per Slack workspace. Absent or empty means the Slack connector stays dormant.

workspace and token are mandatory once an entry is present. Three mistakes fail the load rather than booting a connector that cannot work: an empty workspace, an empty token, and two entries sharing a workspace label. An unknown key inside an entry is rejected, so a near-miss fails loudly.

A workspace becomes a project’s workspace only when a scope binds it:

[[orgs]]
name = "Work"
accounts = ["Work"]

  # Every project in the org acts in this workspace.
  [orgs.slack]
  workspace = "Work Slack"

  [[orgs.projects]]
  name = "service"
  path = "~/Projects/service"

  # This project acts in a different one.
  [orgs.projects.slack]
  workspace = "Service Alerts"

Each [orgs.projects.slack] block attaches to the MOST RECENT [[orgs.projects]] header, like every other nested table there. A project’s binding wins over its org’s; a project with neither leaves the Slack tools refusing with the key to add, not asking for an argument.

A binding that names no [[slack]] label fails the load, naming the label it asked for and the ones that exist:

forge.toml at <path> is otherwise invalid: [[orgs]] slack: no [[slack]] workspace named 'acme'; configured: Service Alerts, Work Slack
forge.toml at <path> is otherwise invalid: [[orgs.projects]] slack: no [[slack]] workspace named 'acme'; configured: Service Alerts, Work Slack

A session whose project binds nothing (and whose org binds nothing) answers every Slack tool with the keys to add:

no Slack workspace is bound to Work/service; add [orgs.slack] workspace = "<label>" to the org, or [orgs.projects.slack] workspace = "<label>" to the project in forge.toml

A binding to a [[slack]] entry added since the last start has no token loaded yet, and names the way out instead of pretending the key is missing:

the [[slack]] workspace 'Work Slack' is bound but not live; a [[slack]] entry added or renamed since boot needs a forge restart

There is no default binding: a project that names nothing is left unbound rather than picking up the only configured workspace, because two orgs may share one Slack install and an implicit choice would post as the wrong one.

A binding governs the tools, not delivery: a stored subscription keeps delivering into the project that created it, whatever the project later binds, because the record is the explicit statement of where those messages go. So removing a binding stops a project acting in that workspace without silencing what it already watches, and rebinding a project leaves the previous workspace’s subscriptions delivering: slack__list shows only the newly bound workspace’s records, while the old ones stay listed in the Inspector’s Slack section for the project, where their ids are the handle slack__unsubscribe takes.

The token is a credential, so it lives here rather than in the state store beside the subscriptions. forge proves it with auth.test at boot and logs the team and user it resolves to, or the failure; a workspace whose token fails keeps its conversation sweeps running but its mention stream stays down - the sweeps cannot recognise <@U...> without it - and forge retries the proof in the background until it succeeds.

[plugins]

Optional. Absent means plugin auto-update is off, which is also what an explicit auto_update = false means. Manual updates from the plugins pane (u, or the per-plugin Update action) are not affected by this section.

When the run fires, the plugins pane reports what updated, from which marketplace, and what it skipped; forge remembers the previous version so the plugin’s actions overlay can offer “Roll back to previous version” afterwards. Rollback needs the recorded pre-update marketplace ref, which in turn needs the marketplace to be git-backed, and the ref to still be fetchable; a rollback that does not actually move the plugin to the recorded version keeps the record so it can be retried.

Like [dictate], an unrecognised key here fails the load rather than being ignored. Keys an older forge read here (trusted_marketplaces, pins) are rejected the same way: remove them.

The task board’s chase

Fixed behaviour, not configuration. There is no [tasks] section: forge.toml refuses one - and any key like stale_hours - as an unknown key, and the chase has no switch: the sweep runs every 30 seconds, always. What it asks, and on what clock, is a constant in the code:

• The no-movement window is 4 hours. A row with no update for that long draws the no movement mark; a ready row with no owner, and a dependency or resource wait, ask the lead every 30 minutes once they pass it. The estimate is what arms the chase for a row that has one; this is the fallback for rows that have none. A wait parked by design carries neither mark and draws no stall ask; un-parking restores both from its age again.
• A row past its estimate asks its owner once, and a restated estimate arms the nudge again; a wait that resolved asks its waiter once to resume it.
• A row past 1.5x its estimate tells the lead every 5 minutes while it stays over. The escalation is authority: rescope, reassign, take over, or restate the expectation.
• A failed row, one whose owner is gone, an epic still owing its retro, and one ready to close each tell the lead every 30 minutes while the state holds.
• A worker holding no row is named when it drifts, again every 5 minutes while it stays drifted, and at once after it accounts and drifts again.
• Each row waiting on the user, untouched for 30 minutes, gets one nudge of its own per wait episode - one message per row, naming the row’s ask, and never a repeat while that wait holds. A row the lead acts on (attested, withdrawn or parked by design) leaves the set, and a row that leaves waiting and comes back is a new episode with a new nudge. A tick that finds every seat asleep spends nothing: the nudge waits for a live lead.

[server]

The socket: one WebSocket served from the process that already owns the sessions, so a client costs a listener rather than a second scheduler. On by default, so a restart leaves it serving.

The server starts no subsystem of its own - no cron scheduler, no connector, no second gateway - so the cost of a client is the listener and the messages. The socket carries the whole view surface: the home and every session, a snapshot of each on subscribe and every update after it, with a client’s commands going back the other way. No page is served from here. A client is its own program and draws everything itself; the socket hands it data. A bind that fails is fatal on the headless binary: with no view of its own it would serve nothing.

[browser]

The server’s browser: how often a host encodes frames, how good they are, and how long a profile nobody uses stays up. Absent means every default.

[terminal]

The terminal one per seat: the shell it runs, how much scrollback the model keeps, and when an idle one closes. Absent means every default.

[client]

Which of the sets forge ships a client draws with. Absent means every name unset, which is the built-in.

[documents]

The ceiling on one document a session hands the reader through the documents__hand_off tool, and on one file’s content at a revision the review page reads for a between-hunk expansion (file_content): both read under this key. Absent means the default.

A row’s motion is not configurable. The client animates its own: the marks move by state - the working mark turns in 900ms and the starting one in 1500ms, and that difference is how a reader tells them apart.

An unset name is not an error and not a fallback: it means the built-in. A name forge does not ship fails the load with the key and the value in the message (ClientNameUnknown, client mark = "anvilish" ... names nothing forge ships; this key picks by name, never by path), because a setting that is quietly ignored reads as the key not working. Like the port checks, none of them run while the socket is disabled.

mark, theme and font are a client’s settings rather than the server’s, and the socket carries them to a client on connect, so a client never reads forge.toml for itself and the file stays the one source of truth. The server draws none of them: the socket serves no page.

[usage]

How often the background poller refreshes account usage. Absent means the default.

[sessions]

What happens when a durable seat - a project’s own agent, or a worker with a stored row - loses its subprocess while it is supposed to be up. Absent means the defaults, which bring the seat back by itself.

A durable seat is a project’s own agent or a worker with a stored row. An ad-hoc session has no row of its own, so opening its seat is what wakes it. A despawn, a close and a forge shutdown never heal: the stop owns the seat, and the boot re-spawn owns the return after a restart. /exit typed into a durable seat does heal - a durable seat is up until it is despawned.

A worker death that heal answers is delivered to its project’s agent as one peer message, whatever the attempt then does: the time in IST with UTC in parentheses, the diagnostic, the attempt and its outcome. A death the stop paths own - a despawn, a close, a shutdown, an ad-hoc seat - sends nothing. A delivery to a sleeping agent parks and lands when it wakes, like any peer message. A lead has no agent above it, so its project’s row draws restarting (N of M) while it is between attempts, then the seat’s own live state once it is back, or the failure with its diagnostic at the cap.

heal_attempts, heal_backoff and heal_stable are read at each death, so an edit applies to the next seat that dies.

Unknown keys

Every table rejects unknown fields, so a mistyped key fails the load and names itself rather than parsing clean and meaning something else - a misspelled fallback_accounts would otherwise read as “no fallbacks”. That covers the top level, [[orgs]], [[orgs.projects]], [[accounts]], [models."<name>"], [handoff] and [orgs.projects.handoff], [[slack]], [gotify], [systemone], [gateway], [dictate], [tts], [huggingface], [plugins], [server], [browser], [terminal], [client] and [sessions].

Two retired keys are declared ghosts rather than unknown keys, so a stale forge.toml still boots and warns instead of failing: [dictate] device and [tts] language.

Every other retired key and section is refused like any unknown key, naming itself as the load fails: resume_lead, [web], [workers], [projects.<name>], [selection] and [ui]. [web]’s listener keys (enabled, port, bind) are [server]’s and its drawing keys (mark, theme, font) are [client]’s; forge carries no alias for the old name.

A complete example

# Applies to every spawned session, unless a narrower layer overrides
# the same key.
[env]
CLAUDE_CODE_AUTO_COMPACT_WINDOW = "950000"

[[orgs]]
name = "Personal"
accounts = ["Personal", "Scratch"]

  [[orgs.projects]]
  name = "forge"
  path = "~/Projects/forge"

  [[orgs.projects]]
  name = "notes"
  path = "~/Projects/notes"

[[orgs]]
name = "Work"
accounts = ["Work"]

  # Every project in the org acts in this Slack workspace; a project's
  # own [orgs.projects.slack] overrides it.
  [orgs.slack]
  workspace = "acme"

  [[orgs.projects]]
  name = "service"
  path = "~/Projects/service"
  max_workers = 4
  env_file = "~/.config/service/secrets.env"

  [orgs.projects.env]
  SERVICE_MCP_URL = "https://mcp.example/service"

  # This project's sessions run unattended for days; finish the work
  # rather than swapping the session under it.
  [orgs.projects.handoff]
  enabled = false

# The automatic session handoff: on at 85% of the window, with the first
# compaction as the backstop.
[handoff]
at_percent = 85

[[accounts]]
display_name = "Personal"
token = "personal-setup-token"
models = ["claude-opus-5", "claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Work"
token = "work-setup-token"
models = ["claude-opus-5", "claude-sonnet-5"]
provider = "anthropic"

# Talks to a local endpoint: the flat base_url and token keys carry
# the endpoint and credential; [accounts.env] stays for
# provider-behaviour extras only.
[[accounts]]
display_name = "Scratch"
provider = "codex"
base_url = "http://localhost:18765"
token = "scratch-token"
models = ["claude-sonnet-5"]

  [accounts.env]
  CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"

[dictate]
enabled = true
normalizer = true
max_capture_minutes = 30

[gotify]
url = "https://gotify.example"
client_token = "CxxxxxxxxxxxxxxxA"

[[slack]]
workspace = "acme"
token = "xoxp-xxxxxxxxxxxx"
poll_seconds = 5
dm_poll_seconds = 150
thread_idle_days = 14
stale_after_hours = 24

[plugins]
auto_update = true

[server]
enabled = true
port = 8790
bind = "127.0.0.1"

[client]
mark = "panes"
theme = "dark"

[documents]
max_size_mib = 10

Reloading an edit

forge watches <config_dir>/forge/forge.toml itself, never the directory: nothing else in that tree can trigger a reload. An atomic save (a temporary file renamed over the path) and a sync tool’s incoming change both count, because the watch is re-armed on the path after every event. About half a second after a burst of writes the server reads the whole file and validates it.

A file that does not parse is rejected whole: one warning names the path and the error, and the last good config stays live. No partial application. Once a file is accepted, the config forge holds is the file; the table below says which parts a running forge adopts and which wait for a restart.

Each key carries one of three classes, and the settings page draws the same class the reload reports:

• live - read on the key’s next use.
• next session - read when a session or a connection opens.
• restart - built once at boot; an edit needs a restart.

A fourth display state, not read yet, marks a key the loader accepts and nothing consumes. The catalogue in crates/forge-workspace/src/settings.rs is the one source for all four, and a test fails when a key the loader accepts has no class.

A running session is never reconfigured. Its account (except when the gateway’s own rotation moves it off an exhausted one), model, permission mode, cwd and child environment stay what they spawned with; the credential itself is resolved per request, so a re-minted token for that same account applies at once. To pick up a changed variable or account, close that session and start it again.

What forge does at startup

forge <PROJECT> opens the named project. The name must match a project’s name exactly.

Preflight runs first on every route. It resolves every [[accounts]] entry and, when [dictate] is on, fetches and loads the dictation models, then hands over to wherever you were headed: the project picker for forge, straight into that project’s chat for forge <PROJECT>. It is shown once per run.

When [dictate] is on, boot also reads the cached model catalogue and refreshes it in the background - fetching the feed the dictation-models page reads - when the cache is older than a day or absent. That refresh never holds the boot path: it lands as an update on the page’s own subscription, and a forge.toml with dictation off fetches nothing.

Nothing spawns until every account has settled, because the walk that picks a session’s account reads each one’s state.

A bailed account does not stop forge from starting. Ready and Bailed both count as settled, so preflight completes: the row names the failure and the pollers keep re-probing it. The walk still keeps a bailed account as a last resort, and picks one when nothing else in the pin declares the project’s model - which is why the project row stays clickable. Fix that account’s auth, or remove its [[accounts]] block; the edit applies to new work, and an auth repair reaches a running session on its next request. The screen names both.

On a launch with no project named, every project whose lead was left open still spawns its lead session in the background, resuming the session forge stored for it unless the launch passed --new, but none of them is focused: you pick one from the picker to enter chat. A project closed from the pane stays shut, and a project whose lead never spawned has nothing to reopen.

The first launch on a build that stores this state seeds every existing lead row as open, because rows written before it carry no state. That one launch therefore reopens every project whose lead had ever spawned, including a project that had been closed by an earlier build; from then on the state is explicit. A lead whose last turn was cut off is handed one restart note as its first turn, telling it to read the project handoff and the task board and to continue where it left off; a lead that was parked is resumed with nothing, and a --new launch sends no note at all.

What was open is therefore what is warm when you arrive; it is not what you land on.

The socket comes up on [server] bind:port during the same boot, unless [server] enabled is false.

Config versus state

forge.toml is the config half. forge re-reads it on a change, and its writers - the settings page’s save and the settings MCP tools - go through one path: a temp file in the same directory, validated by this loader, renamed over the path, with an agent’s edit held for the reader’s approval first. Nothing else in forge writes it, which keeps it safe to sync between machines.

Everything mutable lives in one embedded redb database per config dir, at <app-support>/stores/<hash-of-config-dir>.redb (a SHA-256 of the config dir’s path, so a second config dir on the machine owns its own state; the single-instance lock keys on a separate digest): durable crons and the schedules their fired prompts came from (the pairing a reloaded chat row titles itself by), Gotify subscriptions, Slack subscriptions, the sweep watermarks and the own-post ledger beside them, the session identity per project and label - the lead’s and every worker’s, which is what brings a worker back after a restart - review threads, the per-account usage cache, cached model pricing, and the usage scan’s per-file token summaries.

Dictation keeps four things outside the database, all machine-local and never synced: each take’s audio and transcripts, as plain files under <app-support>/dictate-diagnostics/ - voice recordings outside the database - the read-aloud set the models page records under <app-support>/dictate-read-aloud/, which is the one corpus a bench can score on words that are known, the record of verified model digests under <app-support>/dictate-digests/, which is what lets a boot over unchanged models skip re-hashing them, and the last fetched model catalogue under <app-support>/dictate-catalogue/, which is what lets the models page read the feed when the network is gone.

<app-support> is ~/Library/Application Support/forge on macOS and $XDG_DATA_HOME/forge on Linux.

The single-instance lock lives under the same base, at <app-support>/locks/<hash>.lock, where the hash is derived from the config directory path.

Neither belongs in a synced config directory. The database churns constantly and redb’s binary file cannot be merged by a file syncer. The lock is worse: flock binds to the inode rather than the path, so a sync tool that replaces the file by rename would swap the lock out from under a running forge on another machine, and a second instance could then start against the same config directory.

One forge process owns one config directory. A second is normally refused at boot, naming the holder’s PID when it can read one. The guard is best-effort: if the lockfile cannot be created or locked, forge warns and starts anyway. See Single instance per config directory.