Skip to content

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.

json
{
  "version": 1,
  "id": "workspace_01JEXAMPLE",
  "name": "Acme Notes",
  "leader": "Nova",
  "members": [
    "Nova",
    "Sage"
  ],
  "synthesis": true,
  "paused": false
}
FieldRequiredDefaultOwner and rules
versionyes1File format version. Must be 1; any other value makes the file unreadable and the directory is ignored.
idnononeOptional workspace id hint used during discovery. It only wins when the id is free or already names this directory.
nameyesnoneWorkspace name. Trimmed and required; authoritative over the stored workspace row.
leaderyesnoneLeader agent name. Must resolve to exactly one non-archived agent and must be in members.
membersyesnoneMember agent names. Trimmed, non-empty, case-insensitively unique, and each must resolve to one non-archived agent.
synthesisnotrueWorkspace synthesis toggle. Missing means true; only false disables it.
pausednofalsePause 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.

SettingDefaultMeaning
maxActiveRuns3Scheduler concurrency slots. Minimum 1. No Settings row or : command at this version.
maxDelegations10Per-run fan-out cap, also used as the maximum skill count capped at 8. Minimum 1.
maxDepth5Deprecated. Readable from older stores but ignored for enforcement; use dispatchDepth.
synthesistrueLegacy stored boolean with no active consumer found in this release. Workspace synthesis in config.json is the live toggle.
nativeFirstonNative-first migration mode: on, off, or shadow. Absent or invalid resolves to on.
nativeMentionRoutingtrueMention-routing kill switch. false makes $Name a reference, appends a visible refusal, and forces the legacy tool surface.
toolSurfaceunsetExplicit tool-surface override: native or legacy. Unset means the effective surface follows the migration mode; an explicit legacy survives :native-first on.
dispatchGroupMaxHops8Hops allowed inside one dispatch group (root or continuation). Captured by each new root group.
dispatchCommandMaxHops24Hops allowed for one command across every group. Must be at least the group budget and cover the continuation allowance.
dispatchDepth8Longest ancestor chain inside one group.
dispatchContinuations2Continuation 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.

SettingDefaultAllowed
dispatchGroupMaxHops8tiers 8, 16, 24
dispatchCommandMaxHops24tiers 8, 16, 24, 32, 40, 48; at least group hops
dispatchDepth81–16
dispatchContinuations20–5; each continuation needs at least an 8-hop group

Deprecated and unused fields ​

  • Settings.maxDepth is deprecated. It remains readable for older stores and is ignored for enforcement; depth comes from dispatchDepth.
  • Settings.synthesis is stored but has no active consumer in this release. The live synthesis toggle is the workspace synthesis field in config.json.
  • maxActiveRuns, maxDelegations, and maxDepth have no Settings-panel row or dedicated : command at this version. They are stored settings writable through settings.update.

Next ​

Released under the MIT License.