Configuration
Ensemble has two configuration layers. The workspace file is human-editable and authoritative for workspace shape. Agent settings, dispatch limits, and UI state live in OpenCode plugin storage under v2/meta and are written through the validated service path.
Workspace file: .ensemble/config.json
Path: <workspace>/.ensemble/config.json. version must be 1. The workspace owns this file: Ensemble writes it on create, update, membership sync, and restore, and you may edit it directly. A missing file means the directory is not an Ensemble workspace.
{
"version": 1,
"id": "workspace_01JEXAMPLE",
"name": "Acme Notes",
"leader": "Nova",
"members": [
"Nova",
"Sage"
],
"synthesis": true,
"paused": false
}| Field | Required | Default | Owner and rules |
|---|---|---|---|
version | yes | 1 | File format version. Must be 1; any other value makes the file unreadable and the directory is ignored. |
id | no | none | Optional workspace id hint used during discovery. It only wins when the id is free or already names this directory. |
name | yes | none | Workspace name. Trimmed and required; authoritative over the stored workspace row. |
leader | yes | none | Leader agent name. Must resolve to exactly one non-archived agent and must be in members. |
members | yes | none | Member agent names. Trimmed, non-empty, case-insensitively unique, and each must resolve to one non-archived agent. |
synthesis | no | true | Workspace synthesis toggle. Missing means true; only false disables it. |
paused | no | false | Pause flag. Missing means false; true rejects new work. |
Extra fields are ignored. A wrong version, a missing name or leader, duplicate member names, or a name that does not resolve to exactly one active agent makes the file invalid. Discovery then ignores that directory; reconciliation keeps the last good state.
Editing while the service runs is reconciled on the maintenance timer. Reopen the workspace to force reconciliation.
Stored settings
Settings are stored in the plugin storage row v2/meta, not in a repository file. Ensemble owns this row; updateSettings() is the validated write path, and the TUI Settings panel plus the :native-first, :tools, and :limits commands all use it. Do not hand-edit the storage row.
| Setting | Default | Meaning |
|---|---|---|
maxActiveRuns | 3 | Scheduler concurrency slots. Minimum 1. No Settings row or : command at this version. |
maxDelegations | 10 | Per-run fan-out cap, also used as the maximum skill count capped at 8. Minimum 1. |
maxDepth | 5 | Deprecated. Readable from older stores but ignored for enforcement; use dispatchDepth. |
synthesis | true | Legacy stored boolean with no active consumer found in this release. Workspace synthesis in config.json is the live toggle. |
nativeFirst | on | Native-first migration mode: on, off, or shadow. Absent or invalid resolves to on. |
nativeMentionRouting | true | Mention-routing kill switch. false makes $Name a reference, appends a visible refusal, and forces the legacy tool surface. |
toolSurface | unset | Explicit tool-surface override: native or legacy. Unset means the effective surface follows the migration mode; an explicit legacy survives :native-first on. |
dispatchGroupMaxHops | 8 | Hops allowed inside one dispatch group (root or continuation). Captured by each new root group. |
dispatchCommandMaxHops | 24 | Hops allowed for one command across every group. Must be at least the group budget and cover the continuation allowance. |
dispatchDepth | 8 | Longest ancestor chain inside one group. |
dispatchContinuations | 2 | Continuation groups one command may open. |
Dispatch limits
The four dispatch values are validated as one set. New commands capture the current values; running groups keep the caps they already captured.
| Setting | Default | Allowed |
|---|---|---|
dispatchGroupMaxHops | 8 | tiers 8, 16, 24 |
dispatchCommandMaxHops | 24 | tiers 8, 16, 24, 32, 40, 48; at least group hops |
dispatchDepth | 8 | 1–16 |
dispatchContinuations | 2 | 0–5; each continuation needs at least an 8-hop group |
Deprecated and unused fields
Settings.maxDepthis deprecated. It remains readable for older stores and is ignored for enforcement; depth comes fromdispatchDepth.Settings.synthesisis stored but has no active consumer in this release. The live synthesis toggle is the workspacesynthesisfield inconfig.json.maxActiveRuns,maxDelegations, andmaxDepthhave no Settings-panel row or dedicated:command at this version. They are stored settings writable throughsettings.update.
Next
- Environment: paths and process variables.
- Files and storage: what is safe to edit.