Skip to main content
Config lives in two files. Project wins.
ScopePath
Global~/.soulforge/config.json
Project.soulforge/config.json

​
Full example

{
  "defaultModel": "anthropic/claude-sonnet-4-5",
  "thinking": { "mode": "adaptive" },
  "repoMap": true,
  "semanticSummaries": "ast",
  "diffStyle": "default",
  "chatStyle": "accent",
  "toolTimeout": 2,
  "compaction": {
    "strategy": "v2",
    "triggerThreshold": 0.7,
    "keepRecent": 4
  },
  "taskRouter": {
    "spark":      "anthropic/claude-haiku-4-5",
    "ember":      "anthropic/claude-sonnet-4-5",
    "compact":    "google/gemini-2.5-flash"
  },
  "agentFeatures": {
    "desloppify": true,
    "tierRouting": true,
    "dispatchCache": true,
    "targetFileValidation": true
  },
  "retry": { "maxAttempts": 5, "baseDelayMs": 3000 }
}

​
Fields

​
Model

FieldDefaultWhat it does
defaultModel"none"Active model ID. "none" (default) forces picker on launch.
thinking.mode"off""off", "adaptive", "enabled"
thinking.budget—Tokens when mode: "enabled" (1024, 2048, 5000, 10000, 20000)

​
Display

FieldDefaultWhat it does
diffStyle"default""default", "sidebyside", "compact"
chatStyle"accent""accent", "bubble"
vimHintstrueShow Vim keybinding hints
nerdFonttrueNerd Font icons (off shows ASCII)

​
Intelligence

FieldDefaultWhat it does
repoMaptrueBuild the codebase graph on launch
semanticSummaries"ast""ast", "llm", "off"
toolTimeout2Tool call timeout in minutes. 0 disables.

​
Compaction

See compaction for what these do. 
"compaction": {
  "strategy": "v2",
  "triggerThreshold": 0.7,
  "resetThreshold": 0.4,
  "keepRecent": 4,
  "maxToolResults": 30,
  "llmExtraction": true
}

​
Retry

For 429s and transient errors. Delays double each attempt. 
"retry": { "maxAttempts": 5, "baseDelayMs": 3000 }

​
Task router

Assign different models to different jobs. See the task router recipe for tuning tips. 
"taskRouter": {
  "spark":      "anthropic/claude-haiku-4-5",
  "ember":      "anthropic/claude-sonnet-4-5",
  "webSearch":  "anthropic/claude-haiku-4-5",
  "desloppify": "anthropic/claude-haiku-4-5",
  "verify":     "anthropic/claude-haiku-4-5",
  "compact":    "google/gemini-2.5-flash",
  "semantic":   "anthropic/claude-haiku-4-5",
  "default":    null
}
SlotRuns when
sparkRead-only research agents
emberCode-writing agents
webSearchWeb search agent
desloppifyCleanup pass after code edits
verifyAdversarial review after code edits
compactContext compaction
semanticRepo map one-line summaries
defaultFallback for background tasks
Resolution: taskRouter[slot] → taskRouter.default → active model.

​
Agent features

"agentFeatures": {
  "desloppify": true,
  "tierRouting": true,
  "dispatchCache": true,
  "targetFileValidation": true
}
FeatureWhat it does
desloppifyRun cleanup agent after code agents
tierRoutingAuto-route trivial tasks to cheap model
dispatchCacheShare file reads across dispatches
targetFileValidationRequire file paths on dispatch tasks
Toggle in the TUI with /agent-features.

​
Providers

Pick keys and add custom providers on the dedicated pages:

​
Auth & key storage

Keys go to your OS keychain when available, with a file fallback otherwise.
PlatformBackend
macOSLogin Keychain (security), service soulforge
Linuxlibsecret via secret-tool (GNOME Keyring, KWallet)
Linux without secret-tool~/.soulforge/secrets.json, mode 0600
WindowsDPAPI (crypt32.dll) — %LOCALAPPDATA%\SoulForge\secrets.dat, user-scoped
Windows without DPAPIPlain JSON under same dir — set SOULFORGE_KEY_PRIORITY=env to skip disk
Windows (WSL)Same as Linux above
soulforge --set-key <provider> <key> writes to whichever backend is active. Inspect with soulforge --list-providers.

​
Lookup order

{ "keyPriority": "env" }
ValueOrder
"env" (default)env var → keychain → file
"app"keychain → file → env var
Use "app" when shell-exported keys keep overriding stored ones.

​
Pass a key per-launch

Env vars work for the TUI too — useful for one-off sessions or CI: 
LLM_GATEWAY_API_KEY=sk-... soulforge
ANTHROPIC_API_KEY=sk-ant-... soulforge
Nothing is persisted. There is no --key flag — the TUI only reads stored keys and env vars.

​
Remove a key

/keys inside the TUI lists every provider with delete shortcuts. Or delete from the keychain directly (security delete-generic-password -a soulforge -s anthropic-api-key on macOS).

​
Instruction files

Auto-load project rules from AI-tool markdown files: 
{ "instructionFiles": ["soulforge", "claude", "cursorrules"] }
KeyFileDefault
soulforgeSOULFORGE.mdon
claudeCLAUDE.mdoff
cursorrules.cursorrulesoff
copilot.github/copilot-instructions.mdoff
cline.clinerulesoff
windsurf.windsurfrulesoff
aider.aider.conf.ymloff
codexAGENTS.mdoff
opencode.opencode/instructions.mdoff
ampAMPLIFY.mdoff
Toggle in TUI with /instructions.

​
Privacy

Block files from the agent: 
/privacy add .env
/privacy add secrets/**
Built-ins already cover .env, .pem, credentials, id_rsa, .npmrc, .netrc, shadow, passwd.

​
Environment variables

VariableDefaultPurpose
SOULFORGE_NO_REPOMAPunsetSkip the repo-map scan at startup.
SOULFORGE_MAX_OUTPUT_TOKENS64000Per-step output cap for all agents (forge + subagents + web-search). Raise for reasoning models that hit finish_reason=length.
SOULFORGE_PRESETSunsetComma-separated preset specs to load on boot. Set automatically by --plugin <spec> flags. See presets.
SOULFORGE_KEY_PRIORITYenvKey lookup order. env = env→keychain→file, app = keychain→file→env.
SOULFORGE_NO_PROMPTunsetSkip first-run addon wizard (set to 1). Useful in CI.
SOULFORGE_DEBUG_APIunsetDump per-step API requests to ~/.soulforge/api-export/.
SOULFORGE_DEV_UIunsetShow dev-only slash commands (/ui-demo, etc).
SOULFORGE_ENABLE_GHOSTTYunsetForce-enable the embedded floating terminal on Windows (off by default — see Windows notes).
SOULFORGE_HEARTH_SOCKET<configDir>/hearth.sockOverride the Hearth IPC socket path.
SOULFORGE_HEARTH_APPROVAL_TIMEOUT_MS300000Approval timeout for remote tool calls.
SOULFORGE_HEARTH_DENY_READ_REMOTEunsetBlock read-only tools from remote surfaces (set to 1).
SOULFORGE_PROXY_VERSIONlatestPin a CLIProxyAPI version when installing the proxy addon.
SOULFORGE_AUTO_INSTALL_ADDONSunsetComma-separated addons to install automatically (proxy,neovim).

​
Hooks

Covered on the hooks page. Short version: SoulForge reads hooks.{Event} from all 5 config sources (Claude Code’s three + SoulForge’s two), fires all matches.

​
Storage

/storage shows per-component disk usage (repo map, sessions, plans, memory, input history, binaries, fonts) with one-click cleanup.

​
Scope priority

Session → Project → Global. Changes via commands land in whatever scope the command targets. Use /model-scope to move the active model between project and global.