> ## Documentation Index
> Fetch the complete documentation index at: https://soulforge.proxysoul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Every setting, grouped by what you're trying to do.

Config lives in two files. Project wins.

| Scope   | Path                       |
| ------- | -------------------------- |
| Global  | `~/.soulforge/config.json` |
| Project | `.soulforge/config.json`   |

## Full example

```json theme={null}
{
  "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](/context/compaction) for what these do.

```json theme={null}
"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.

```json theme={null}
"retry": { "maxAttempts": 5, "baseDelayMs": 3000 }
```

## Task router

Assign different models to different jobs. See the [task router recipe](/recipes/task-router) for tuning tips.

```json theme={null}
"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

```json theme={null}
"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](/providers/overview) — env vars, `--set-key` commands, keyUrls.
* [Custom providers](/providers/custom) — any OpenAI-compatible API.
* [Copilot](/providers/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

```json theme={null}
{ "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:

```bash theme={null}
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:

```json theme={null}
{ "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](#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](/installation#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](/tools/hooks). 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.