Configuration

Config lives in two files. Project wins.

Scope	Path
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

Field	Default	What 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

Field	Default	What it does
`diffStyle`	`"default"`	`"default"`, `"sidebyside"`, `"compact"`
`chatStyle`	`"accent"`	`"accent"`, `"bubble"`
`vimHints`	`true`	Show Vim keybinding hints
`nerdFont`	`true`	Nerd Font icons (off shows ASCII)

Intelligence

Field	Default	What it does
`repoMap`	`true`	Build the codebase graph on launch
`semanticSummaries`	`"ast"`	`"ast"`, `"llm"`, `"off"`
`toolTimeout`	`2`	Tool 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
}

Slot	Runs when
`spark`	Read-only research agents
`ember`	Code-writing agents
`webSearch`	Web search agent
`desloppify`	Cleanup pass after code edits
`verify`	Adversarial review after code edits
`compact`	Context compaction
`semantic`	Repo map one-line summaries
`default`	Fallback for background tasks

Resolution: taskRouter[slot] → taskRouter.default → active model.

Agent features

"agentFeatures": {
  "desloppify": true,
  "tierRouting": true,
  "dispatchCache": true,
  "targetFileValidation": true
}

Feature	What it does
`desloppify`	Run cleanup agent after code agents
`tierRouting`	Auto-route trivial tasks to cheap model
`dispatchCache`	Share file reads across dispatches
`targetFileValidation`	Require file paths on dispatch tasks

Toggle in the TUI with /agent-features.

Providers

Pick keys and add custom providers on the dedicated pages:

All providers — env vars, --set-key commands, keyUrls.
Custom providers — any OpenAI-compatible API.
Copilot — use your GitHub Copilot subscription.

Auth & key storage

Keys go to your OS keychain when available, with a file fallback otherwise.

Platform	Backend
macOS	Login Keychain (`security`), service `soulforge`
Linux	libsecret via `secret-tool` (GNOME Keyring, KWallet)
Linux without `secret-tool`	`~/.soulforge/secrets.json`, mode `0600`
Windows	DPAPI (`crypt32.dll`) — `%LOCALAPPDATA%\SoulForge\secrets.dat`, user-scoped
Windows without DPAPI	Plain 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" }

Value	Order
`"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"] }

Key	File	Default
`soulforge`	`SOULFORGE.md`	on
`claude`	`CLAUDE.md`	off
`cursorrules`	`.cursorrules`	off
`copilot`	`.github/copilot-instructions.md`	off
`cline`	`.clinerules`	off
`windsurf`	`.windsurfrules`	off
`aider`	`.aider.conf.yml`	off
`codex`	`AGENTS.md`	off
`opencode`	`.opencode/instructions.md`	off
`amp`	`AMPLIFY.md`	off

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

Variable	Default	Purpose
`SOULFORGE_NO_REPOMAP`	unset	Skip the repo-map scan at startup.
`SOULFORGE_MAX_OUTPUT_TOKENS`	`64000`	Per-step output cap for all agents (forge + subagents + web-search). Raise for reasoning models that hit `finish_reason=length`.
`SOULFORGE_PRESETS`	unset	Comma-separated preset specs to load on boot. Set automatically by `--plugin <spec>` flags. See presets.
`SOULFORGE_KEY_PRIORITY`	`env`	Key lookup order. `env` = env→keychain→file, `app` = keychain→file→env.
`SOULFORGE_NO_PROMPT`	unset	Skip first-run addon wizard (set to `1`). Useful in CI.
`SOULFORGE_DEBUG_API`	unset	Dump per-step API requests to `~/.soulforge/api-export/`.
`SOULFORGE_DEV_UI`	unset	Show dev-only slash commands (`/ui-demo`, etc).
`SOULFORGE_ENABLE_GHOSTTY`	unset	Force-enable the embedded floating terminal on Windows (off by default — see Windows notes).
`SOULFORGE_HEARTH_SOCKET`	`<configDir>/hearth.sock`	Override the Hearth IPC socket path.
`SOULFORGE_HEARTH_APPROVAL_TIMEOUT_MS`	`300000`	Approval timeout for remote tool calls.
`SOULFORGE_HEARTH_DENY_READ_REMOTE`	unset	Block read-only tools from remote surfaces (set to `1`).
`SOULFORGE_PROXY_VERSION`	latest	Pin a CLIProxyAPI version when installing the proxy addon.
`SOULFORGE_AUTO_INSTALL_ADDONS`	unset	Comma-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.

Get started

Sponsors

Recipes

Providers

Tools

How it works

Reference

Full example

Fields

Model

Display

Intelligence

Compaction

Retry

Task router

Agent features

Providers

Auth & key storage

Lookup order

Pass a key per-launch

Remove a key

Instruction files

Privacy

Environment variables

Hooks

Storage

Scope priority

​Full example

​Fields

​Model

​Display

​Intelligence

​Compaction

​Retry

​Task router

​Agent features

​Providers

​Auth & key storage

​Lookup order

​Pass a key per-launch

​Remove a key

​Instruction files

​Privacy

​Environment variables

​Hooks

​Storage

​Scope priority

Full example

Fields

Model

Display

Intelligence

Compaction

Retry

Task router

Agent features

Providers

Auth & key storage

Lookup order

Pass a key per-launch

Remove a key

Instruction files

Privacy

Environment variables

Hooks

Storage

Scope priority