Presets

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:

Global — ~/.soulforge/config.json → presets[]
Project — <cwd>/.soulforge/config.json → presets[]
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

Form	Example
Registry id	`team/standard`
Absolute path	`/etc/forge/preset.json`
Relative path	`./presets/local.json`, `../shared.json`
Home path	`~/forge/preset.json`
URL	`https://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

Variable	Purpose
`SOULFORGE_PRESETS`	Comma-separated specs (set automatically by `--plugin` flags).

Get started

Sponsors

Recipes

Providers

Tools

How it works

Reference

Three ways to load

Spec formats

Wizard

Boot output

How merging works

Authoring

Environment

See also

​Three ways to load

​Spec formats

​Wizard

​Boot output

​How merging works

​Authoring

​Environment

​See also

Three ways to load

Spec formats

Wizard

Boot output

How merging works

Authoring

Environment

See also