Quickstart
Install the stable 0.1.1 package, create two agents and a workspace, send one message, and watch the work item finish. The example uses an acme-notes workspace with two synthetic agents, Nova and Rook.
The automated packed-install smoke for this path completes in roughly 30 seconds; the recorded scripted runs were 29.4 s, 31.6 s, and 34.9 s. That is not a human completion estimate; install and model latency vary by machine.
Before you start
- OpenCode 2.2.6, 2.2.7, or 2.3.0 on Linux with tmux, and Node 22.23.4 or newer.
- A project directory you can open in OpenCode.
- At least one provider and model configured in OpenCode. The agent wizard reads the model list from the host.
- The plugin installed. If it is not, follow Install first.
Step 1: Install and verify
opencode plugin add @heyimteee/ensemble@0.1.1
opencode plugin listExpected entry:
ensemble.v2 0.1.1 @heyimteee/ensemble@0.1.1If the entry is missing, restart OpenCode and run opencode plugin list again.
Step 2: Open Ensemble
Restart OpenCode, then run /ensemble or the Open Ensemble palette command. With no workspace yet, the header reads:
ENSEMBLE │ no workspaceStep 3: Create the first agent
A workspace needs at least one member, so create the agents before the workspace.
- Press
hto focus the rail, thenato open the agent wizard. - Enter the agent name
Novaand pressEnter. - Enter a short title, for example
Research, and pressEnter. - Enter a role, for example
You research project material and summarize it., and pressEnter. - Skip the optional memories step with
Enter. - Choose a main model from the host list and press
Enter. If a reasoning effort step appears, choose one and pressEnter.
Expected toast, and a direct chat opens:
Nova created. Opening a direct chat.Step 4: Create the second agent
- Press
hto return to the rail, thena. - Name the agent
Rook, give it a title such asReview, and write a role such asYou review changes and report risks. - Skip memories, choose the main model, and confirm.
Expected toast:
Rook created. Opening a direct chat.Both agents appear in the rail under Homeless until they join a workspace.
Step 5: Create the workspace
- Press
hto return to the rail, thenn. - On Workspace directory, choose Use current directory for the project you opened, or choose Type a path… and enter another directory. Press
Enter. - On Workspace name, enter
acme-notesand pressEnter. - On Workspace members, press
SpaceonNovaandSpaceonRookso both are selected, then pressEnter. - On Workspace leader, choose
Novaand pressEnter. - On Leader synthesis, choose
Yes — let the leader synthesizeand pressEnter.
Expected toast:
#acme-notes created.Ensemble then offers to move each agent's no-workspace direct chat into the workspace. Answer y to both prompts:
Move Nova into #acme-notes?
Move Rook into #acme-notes?Step 6: Send the first message
The workspace is now active and the group chat is selected.
- Press
ito focus the composer. - Type
Summarize what this project is for in three bullets. - Press
Enter.
The message goes to the leader because it has no $Name. Nova answers in the group chat, and the reply streams in before it settles as Markdown.
Step 7: Watch the Work pane
While the turn runs, the Work pane shows one active group:
WORK ACTIVE │ 1 group · 1 active · 0 done │ page 1/1When the turn finishes, the work item moves from WORKING to REPLIED and settles into HISTORY.
- Press
lto select the Work pane, thenEnterto enter it. - Press
fto switch between ACTIVE and HISTORY. - In HISTORY, press
Enteron the rolled-up group to expand it, focus the finished work item, and pressoto open Nova's native session. - Press
F2to return to Ensemble.
Expected result
You have one workspace, two agents, and one group reply. The Work pane has a REPLIED work item, and o opens the native session that produced it. The next page turns this into a working team: First team.
Troubleshooting
| Symptom | What to do |
|---|---|
| The agent wizard says no models are available | Configure a provider and model in OpenCode, then reopen the wizard. The list refreshes from the host. |
| The workspace wizard rejects the members step | Select at least one member with Space before you continue. |
| The leader step has no options | The leader must be one of the members selected in the previous step. Go back with N and select a member. |
| The work item stays QUEUED | Confirm the workspace is not paused and that the agent has a model. If it stays stuck, use the incident runbook. |
o does not open a native session | Focus the work item first with j/k, then press o. On a group chat, o asks which member's session to open. |
Next
- First team: choose a leader, delegate work, and inspect a native session.
- Concepts: learn why unaddressed messages reach the leader.
- Guides: apply Ensemble to a real workflow.