dsh Configuration Guide: Profiles, Patches & Agent Presets

Everything is a plugin tree

A running dsh is not a binary with features bolted on. It is a plugin tree — a Cordis plugin system assembled at startup from layers of configuration. Every capability (tools, model adapters, storage, sandboxes, the UI, the main loop) is a plugin in that tree, and the configuration layers decide which plugins exist, in which order.

That is the whole mental model. The rest of this guide unpacks the layers.

The layers, from base to top

Configuration stacks in a fixed order, and upper layers override lower ones:

┌─────────────────────────────┐
│  patches      (your overrides)   ← wins
├─────────────────────────────┤
│  profiles     (your named assemblies)
├─────────────────────────────┤
│  bundles      (official plugin sets)
└─────────────────────────────┘

• Bundles — official sets of plugins shipped together. The default experience you get on first launch is a bundle.
• Profiles — named assemblies on your machine. A profile says "load these bundles and plugins, with these settings". You can keep several and switch between them.
• Patches — your own override layer. A patch can target any single plugin entry and replace it, without touching the profile it came from.

Because every layer is just configuration, sharing a setup is sharing the files. Copying a profile or patch is how someone hands you "their dsh".

The patch layer: a dressing system for your agent

The built-in patch layer is the part that feels least like other agents. Think of it as a dressing system — you decide what capabilities the agent wears, and under what conditions:

• Mount local agents as sub-agents. Your machine's Codex and Claude Code can be registered as sub-agents the harness delegates to, rather than competitors it replaces.
• Wire in capabilities. Install plugins that add tools, integrate external services, adjust run permissions, or turn on full-text search.
• Replace the UI. Interface modules are plugins too — skins, panels and even whole UI components can be swapped through a patch.
• Make rules conditional. Rules are JavaScript expressions, so a capability can apply only where you want it: a specific repo, a file type, a time of day.

The patch targets a single plugin entry, so each of these is an override you can add, inspect and remove without touching the profile below it.

Why "installing a plugin" is a config edit

There is no central package manager in the "install and forget" sense. Installing a plugin means adding an entry to your profile or patch layer; the plugin repository's README documents the exact line. On next start the plugin joins the tree; on removal, everything it registered is revoked — registration must be a reversible side effect, which is why a bad plugin can't leave residue behind (see the plugin development guide).

Agent presets: the shape of one session

The mode selector at the top of the UI picks an Agent Preset — a complete definition of the agent in this session:

• which tools it has,
• its system prompt,
• which skills are loaded,
• its sub-agent and workflow setup.

A preset is not a plugin list plus a prompt; it is the whole contract the session runs under. That's why a session locks its preset once it has content — switching mid-session would make the tool calls already in history uninterpretable.

The four built-in presets:

Making your own preset

The Creation mode is the sanctioned way to design a new preset: describe what you want ("a read-only code reviewer that never edits files and answers in Chinese"), and the harness inspects the live runtime, experiments with plugins in memory, drafts the config, mounts it and saves it for reuse.

Two cautions from the docs worth repeating:

• Creation mode executes model-written code against the runtime — trust it like shell access.
• Presets are config, so review what it saved before making it your default.

When to stop configuring

The pleasant default is: run Standard, change almost nothing. Reach for profiles and patches when you repeat the same setup (a team shares one profile), when you want a fixed toolbox for one job, or when you want to swap one component (a different model adapter, a stricter approval policy). The upper layers exist so you can override one thing without forking everything.

Keep exploring

• Sandboxes, approvals & secrets — the safety model these layers plug into
• Quickstart: run dsh in 5 minutes
• The dsh plugins ecosystem