Skip to main content
Presets are reusable config bundles — task router rules, agent features, theme, instruction files, custom providers — that merge into your AppConfig at boot. Useful for syncing settings across machines, sharing a team setup, or pinning a known-good config to a repo.

​
Three ways to load

Presets resolve in this order — later wins:
  1. Global — ~/.soulforge/config.json → presets[]
  2. Project — <cwd>/.soulforge/config.json → presets[]
  3. CLI — --plugin <spec> (stackable) or SOULFORGE_PRESETS=spec1,spec2
{
  "presets": [
    "team/standard",
    "./presets/local.json",
    "https://example.com/forge-preset.json"
  ]
}

# One-off CLI overlay (multiple --plugin flags stack)
soulforge --plugin team/standard --plugin ./extra.json

# Same via env
SOULFORGE_PRESETS=team/standard,./extra.json soulforge

​
Spec formats

FormExample
Registry idteam/standard
Absolute path/etc/forge/preset.json
Relative path./presets/local.json, ../shared.json
Home path~/forge/preset.json
URLhttps://example.com/preset.json
Specs must be at least 2 characters and match ^(https?:\/\/|\.\/|\.\.\/|\/|~\/)|^[a-zA-Z0-9][a-zA-Z0-9._/-]{1,}$. Invalid specs are logged and skipped.

​
Wizard

soulforge --presets
# or
soulforge presets
Interactive picker — browse the registry, preview overlays, add to global or project scope.

​
Boot output

By default preset resolution is silent on success. Failures print one short line to stderr (one bad preset never blocks boot — fail-open). For full traces: 
soulforge --verbose-presets
You’ll see one line per spec (ok or fail) with the resolved source.

​
How merging works

Presets are resolved to plain AppConfig patches, then merged on top of DEFAULT_CONFIG in load order. The diff against defaults becomes the presetOverlay — applied before loadConfig() returns, so every consumer sees the merged shape transparently. Your ~/.soulforge/config.json is never rewritten. Removing the preset entry restores the prior behaviour on next launch.

​
Authoring

A preset is a JSON file (or registry-hosted JSON) with any subset of AppConfig fields: 
{
  "name": "team-standard",
  "description": "Team default router + theme + privacy",
  "config": {
    "theme": { "name": "catppuccin" },
    "taskRouter": {
      "spark": "anthropic/claude-haiku-4-5",
      "ember": "anthropic/claude-sonnet-4-5"
    },
    "agentFeatures": {
      "desloppify": true,
      "tierRouting": true
    },
    "forbiddenPatterns": ["*.env", "secrets/**"]
  }
}
Drop it under ~/.soulforge/presets/<name>.json to make it discoverable, or host anywhere reachable by HTTPS.

​
Environment

VariablePurpose
SOULFORGE_PRESETSComma-separated specs (set automatically by --plugin flags).

​
See also