Skip to content

Files and storage ​

Ensemble keeps workspace-shape files in the project directory and durable rows in OpenCode plugin storage. The host owns the physical storage format and paths; documentation names the logical prefixes, not a filesystem location.

Workspace files ​

PathContentsSafe to edit?
<workspace>/.ensemble/config.jsonWorkspace name, leader and member names, synthesis, paused, version, optional id.Yes, with valid JSON and resolvable active agent names. See Configuration.
<workspace>/.ensemble/init.jsonContract marker with version and installedAt.No. Restore from a backup; reconciliation reads it.
<workspace>/.ensemble/handoffs/Typed Markdown handoff files. The handoff tool enforces realpath containment under this directory.Yes for content, while keeping files under this directory.
<workspace>/.ensemble/attachments/<conversationKey>/Attachment bytes and an index file. Transcript rows carry metadata, not bytes.No. Managed by the attachment path.
<workspace>/AGENTS.mdProject instructions plus the generated Ensemble block between <!-- ensemble:start v7 --> and <!-- ensemble:end -->.Yes outside the block. Edits inside the block are overwritten when the roster contract refreshes.
<workspace>/.gitignoreEnsemble appends .ensemble/ when it creates the directory.Safe. Ensemble only appends the missing line.

Plugin storage ​

The following logical prefixes are the durable state Ensemble owns. They are stored through the host's plugin storage API, so there is no documented filesystem path and no supported hand-edit workflow.

PrefixContentsEdit policy
v2/agent/Agents, including archived rows and memory/skill settings.No supported hand-edit path. Use the RPC or an operator CLI.
v2/workspace/Workspaces, members, leader, pause, and synthesis.No supported hand-edit path. Use the RPC or an operator CLI.
v2/message/Group and direct conversation rows, ordered by sequence.No supported hand-edit path. Use the RPC or an operator CLI.
v2/subtask/Work items, review batches, handoff metadata, and turn state.No supported hand-edit path. Use the RPC or an operator CLI.
v2/dispatchgroup/Dispatch-group ledgers and captured hop budgets.No supported hand-edit path. Use the RPC or an operator CLI.
v2/init/Workspace init jobs and their progress.No supported hand-edit path. Use the RPC or an operator CLI.
v2/native-subagent/Native subagent parent/child relationships.No supported hand-edit path. Use the RPC or an operator CLI.
v2/binding/Session bindings and retired-session history.No supported hand-edit path. Use the RPC or an operator CLI.
v2/memory/Memories with scope, provenance, and history.No supported hand-edit path. Use the RPC or an operator CLI.
v2/approval/Approval inbox rows and resolutions.No supported hand-edit path. Use the RPC or an operator CLI.
v2/dmqueue/Queued direct sends.No supported hand-edit path. Use the RPC or an operator CLI.
v2/dm/Legacy direct-message rows kept for migration.No supported hand-edit path. Use the RPC or an operator CLI.

Additional rows:

KeyContentsEdit policy
v2/metaStored settings, UI state, and coordination version.Use the Settings panel or the validated RPC.
v2/backup/rollbackOne pre-restore rollback slot.Use the backup rollback command.
ensemble.stateLegacy pre-v2 state kept for migration.No hand edit; reset or restore.

The backup document is ensemble.backup format 1. It contains durable rows plus the derived workspace config and init records. It excludes attachment bytes, handoff files, project content, host sessions, credentials, and logs.

Logs ​

Default directory: $XDG_STATE_HOME/ensemble/logs, or ~/.local/state/ensemble/logs when XDG_STATE_HOME is unset. ENSEMBLE_LOG_DIR overrides it.

PropertyValue
FilesService and TUI JSONL, plus a separate failures sink. Rotated files append .1 through .N.
PermissionsOwner-only files in an owner-only directory.
Default retention7 days
Rotated filesAt most 5 per role/prefix
Maximum size10 MiB per file
ContentMetadata and IDs by default. Free text only with ENSEMBLE_LOG_CONTENT=1; credentials and common token shapes are redacted.

Logs are safe to delete for privacy, but they are the evidence source for a support bundle. data delete --logs removes only matching Ensemble log files.

OpenCode-owned paths ​

PathOwnerUse
$XDG_STATE_HOME/opencode/service.jsonOpenCodeService descriptor read by doctor, data, backup, and the support bundle. Read-only.
<host-owned plugin storage>OpenCodeNo documented path; use the RPC and operator CLIs.
<host-owned native sessions>OpenCodeOnly the host can remove them; data delete needs --delete-native-sessions to ask.

Safe-to-edit summary ​

  • Safe: .ensemble/config.json, AGENTS.md content outside the Ensemble block, handoff Markdown under .ensemble/handoffs/, and .gitignore additions.
  • Managed: the AGENTS block, .ensemble/init.json, .ensemble/attachments/, every v2/ storage row, and the rollback slot. Use init, reset, backup, data, or settings.
  • Disposable: local JSONL logs, with the support-evidence caveat above.

There is no second product configuration file. Agent settings and dispatch limits live in v2/meta.

Next ​

Released under the MIT License.