Skip to content

Ensemble documentation ​

Ensemble is a persistent agent team inside OpenCode: one group chat, named agents, visible work, and each agent's native session underneath. These docs help you install it, learn the mental model, complete common tasks, and look up exact behavior.

Version scope: stable 0.1.x, current v7 roster contract. Verified on OpenCode 2.2.6, 2.2.7, and 2.3.0 on Linux/tmux, with Node 22.23.4 or newer. Prerelease history lives in the changelog, not in a separate docs tree.

See it in motion ​

The Ensemble three-pane workspace in the synthetic Acme Notes fixture: agents in the rail, a working Ada work item in Work, and a group message in chat.
A scripted replay of the isolated synthetic fixture. The install command is illustrative; the workspace, message, work item, and native session were captured from the local host.
Text summary of the replay
  1. The stable install command is shown at an isolated shell prompt.
  2. OpenCode starts and /ensemble opens the workspace.
  3. A group message is assigned to the leader, Ada.
  4. Work shows Ada's card as WORKING with its hop budget.
  5. o opens Ada's native session, where the release note runs.

The recording is a scripted replay of an isolated synthetic fixture. The install command is illustrative; the workspace, messages, Work card, and native session were captured from the local OpenCode host. Reduced-motion settings keep the poster visible until you press play.

The replay covers the stable install command, /ensemble, a group message, the work item, and the native session underneath. Read the quickstart for the same path as copyable steps, or the workspace shell for the pane model.

Start here ​

I want to…Start with
Install Ensemble and get a first replyGetting started
Understand agents, workspaces, and routingConcepts
Finish a task in the appGuides
Look up a command, key, tool, or settingReference
Back up, upgrade, or recover an installOperations
Fix an install, work, timeout, or model failureTroubleshooting
Check install tags, platform limits, and diagnosticsFAQ
Find support, recovery, security, and privacy in one placeOperations and support
Assess security or privacySecurity or Privacy
Get help or report a problemSupport
Contribute code or documentationContributing

Learning paths ​

New users ​

  1. Read What is Ensemble? and check the support matrix before you install on an unverified host.
  2. Follow Install for the stable 0.1.1 package.
  3. Complete the Quickstart: two agents, one workspace, one message, and one finished work item.
  4. Continue with First team to delegate work and open a native session.
  5. Use Upgrade when you move from a prerelease.

Daily users ​

  1. Learn the shared language in Concepts and the domain glossary.
  2. Use Guides for routing, the Work pane, approvals, and settings.
  3. Keep the keyboard reference open while you work.
  4. Look up exact behavior in Reference when a guide is not enough.

Team leads ​

  1. Read Concepts for the leader, group chat, turns, work items, and dispatch budgets.
  2. Follow Guides to create a workspace, add members, and delegate work.
  3. Look up exact limits and commands in Reference when a delegation is refused or an agent stops.
  4. Review support and operations before asking a team to depend on the preview.

Operators ​

  1. Start at Operations for backup, restore, upgrade, and rollback.
  2. Read Scale, soak, and local diagnostics for the tested envelope and evidence collection.
  3. Use the incident runbook when a workspace is broken, work is stuck, or data may be lost.
  4. Follow the support policy and support matrix before filing.

Contributors ​

  1. Start with Contributing, CONTRIBUTING.md, and AGENTS.md.
  2. Read the documentation style guide before adding or moving a page.
  3. Update the redirect map when navigation changes.
  4. Find architecture decisions and verification evidence in the evidence index, reached through the contributing hub.

Security reviewers ​

  1. Start at Security for the threat model, permission review, and accepted risks.
  2. Read Privacy for data classes, retention, export, and delete.
  3. Follow the private reporting process in SECURITY.md. Never put a vulnerability in a public issue.

Documentation sections ​

SectionCovers
Getting startedInstall, first run, quickstart, and the first team
ConceptsAgents, workspaces, leader, conversations, turns, work items, budgets, native sessions, skills, memory, and approvals
GuidesTask-shaped walkthroughs and recipes
ReferenceTools, commands, keyboard, configuration, environment, files, CLI, and supported hosts
OperationsBackup, restore, upgrade, rollback, release operations, and diagnostics
SecurityThreat model, permission review, and accepted risks
PrivacyData classes, retention, export, and delete
SupportSupport policy, troubleshooting, FAQ, incident runbook, support matrix, and known limitations
ContributingDevelopment workflow, docs process, ADRs, and verification evidence

Operations, security, privacy, and support are user-facing sections. ADRs, verification records, implementation notes, and assessments are public engineering evidence: they stay linked from the contributing hub and its evidence index, not from the primary user navigation.

About these docs ​

npm run docs:check validates the page inventory and frontmatter, internal links and VitePress-rendered anchors, Markdown and shell fences, the current contract, host, and Node claims, generated-reference freshness, the docs site build, and the built-site anchor crawl. CI runs npm run docs:check:fast in the Docs job and the separate Docs site job owns the one PR build. The full gate also keeps every docs section reachable from this home and requires every current verification record to be linked from the evidence index.

Released under the MIT License.