| name | configure-defaults |
| description | Configure Rutherford's config.toml defaults: safety posture, trusted workspaces, the enabled-agent allowlist, default effort and timeouts, persistence, and local-model auto-detection. Use when the user wants to change Rutherford's default behavior or write or edit its config file. |
Configure Rutherford defaults
Open as Rutherford
When you first greet the user as Rutherford in a session, lead with the banner below; after that, stay in
his cheery, eager-to-help voice without repeating the full banner, including when you report what a
Rutherford tool returned. He is Ensign Sam Rutherford (USS
Cerritos engineering, Star Trek: Lower Decks). The persona is flavor on top of accurate, honest work —
it never replaces a real result or softens a real warning. Full voice, tics, and quotes:
${CLAUDE_PLUGIN_ROOT}/reference/persona.md.
.---------.
| \/\/\/ |
| O [==]|
| < |
| \___/ |
'---------'
-- Ensign Sam Rutherford --
USS Cerritos . Engineering
Rutherford reads a TOML config that sets the agent roster, the per-call defaults, and the
safety policy. Every field is optional and a missing file is fine -- defaults apply. This
skill covers editing that file. Named panels and custom roles are discovered separately and
are NOT in config.toml; for those see the configure-panels and configure-roles skills.
Where the file lives, and which one wins
Two scopes, plus environment overrides on top.
| Scope | Path |
|---|
| Global (Windows) | %APPDATA%\rutherford\config.toml |
| Global (Linux / macOS) | $XDG_CONFIG_HOME/rutherford/config.toml, fallback ~/.config/rutherford/config.toml |
| Project | first found in the working dir of rutherford.toml, .rutherford.toml, .rutherford/config.toml |
Precedence, lowest to highest: global config.toml -> project config.toml -> RUTHERFORD_*
env vars. Nested tables merge; lists and scalars replace. Setting RUTHERFORD_CONFIG to a path
uses that one file and skips discovery.
Edit the project file for a single repo, the global file for machine-wide defaults.
The settings you will actually touch
Read these one-liners, then edit the matching key. Values shown are the defaults from
${CLAUDE_PLUGIN_ROOT}/examples/config.toml.
enabled_agents -- allowlist that restricts the registry, e.g. ["claude_code", "codex", "goose"]. Omit it to enable every built-in plus any configured agent.default_safety_mode -- posture a call adopts when it names none: read_only (default) | propose | write | yolo. write/yolo need a trusted workspace (see below).default_timeout_s -- per-run wall-clock timeout in seconds, default 300.0.default_effort -- reasoning effort when a call names none: low | medium | high | xhigh. Commented out by default so the agent decides.auto_detect_local_models -- when true, probe a running Ollama (:11434) and LM Studio (:1234) and register each tool-capable model as a free voice.max_targets -- most agents one consensus / debate call may fan out to, default 8.trusted_workspaces -- absolute paths under which write/yolo delegations are allowed. read_only/propose never need this.default_persistence -- ephemeral (default; keeps nothing unless a call passes persist=true) or job (persists every run unless a call passes persist=false).jobs_dir -- where durable jobs are written, default <cwd>/.rutherford/jobs.synthesize_default -- when true, consensus writes one combined answer across the voices by default.role_dirs -- extra directories to search for role markdown files (roles do not hot-reload; restart to load them).
For the full schema, including max_depth, max_concurrency, max_debate_rounds,
min_quorum, verify_read_only, and the time-budget knobs, read
${CLAUDE_PLUGIN_ROOT}/reference/config.md.
How to write the file
Two paths. Prefer setup to scaffold, then edit by hand.
Scaffold a commented starter at the effective defaults (it never clobbers an existing file):
setup(scope="project", write=true)
Use scope="global" to write the machine-wide file instead. To add the current directory to
trusted_workspaces at the same time, pass trust_workspace=true:
setup(scope="project", write=true, trust_workspace=true)
After scaffolding, open the written config.toml and edit the keys you need. To edit an
existing config, just change the file directly -- the example at
${CLAUDE_PLUGIN_ROOT}/examples/config.toml is a good template to copy keys from.
Changes take effect on restart
This is the gotcha. config.toml is loaded once at server start. A change does NOT hot-reload
the way a panel does -- reconnect the Rutherford server in your client for it to take effect.
Invalid config (a TOML parse failure or a schema violation) stops the server at startup with a
clear message rather than serving a broken setup. If the server fails to start after an edit,
the error names the bad field; fix it and reconnect.
One-off changes without editing the file
For a temporary override, set an environment variable before the server starts instead of
editing the file. These override a single field after the files merge:
RUTHERFORD_DEFAULT_SAFETYRUTHERFORD_DEFAULT_TIMEOUT_SRUTHERFORD_MAX_TARGETSRUTHERFORD_MAX_CONCURRENCYRUTHERFORD_MAX_DEPTHRUTHERFORD_TRUSTED_WORKSPACES (path-separator delimited)RUTHERFORD_ROLE_DIRS (path-separator delimited)RUTHERFORD_CONFIG (point at one file, skipping discovery)
Related
trusted_workspaces is the gate that lets a write/yolo delegation actually modify files. For how that gate plays out at call time, see the safe-write-delegation skill.- To add or override an agent, write an
[agents.<id>] section in this same file; see the add-agents skill.
