Concepts
Short, example-led explanations of how Ensemble works. Read this section when you need to know who receives a message, why work is waiting, or what a budget refusal means. Each page starts with what you see in the product, then explains the model behind it.
The domain glossary is authoritative for definitions. The documentation style guide fixes the user-facing term for each concept.
Learning path
Read these pages in order on a first pass. Each one stands alone when you need a single answer.
- The workspace shell: the rail, chat, and Work panes, and how to move between them.
- Agents, workspaces, and the leader: reusable teammates, project spaces, and who receives an unaddressed message.
- Conversations and routing: group chat versus direct chat,
$Name,@path, and assignment. - Turns and synthesis: what happens after a message arrives, through an agent turn and the leader's final answer.
- Work lifecycle: pending, working, waiting, retrying, needs you, replied, failed, stalled, and cancelled, plus ACTIVE and HISTORY.
- Dispatch budgets: the command, group, task, and depth ceilings, with a worked example.
- Native sessions: where each agent actually runs, why conversations are isolated, and what "underneath" means.
- Skills: reusable guidance, Skillboxes, and General-skill triage.
- Memory and approvals: saved knowledge and the decisions that wait for you.
- Architecture overview: the server, TUI, durable state, and OpenCode host boundary.
Find the answer
| Question | Page |
|---|---|
| What are the three panes? | The workspace shell |
| Who is the leader, and what does leadership change? | Agents, workspaces, and the leader |
Why did $Name create work in the group but not in a direct chat? | Conversations and routing |
| Why did the command produce only one synthesis? | Turns and synthesis |
| What does a work item status mean? | Work lifecycle |
| Why was a continuation refused? | Dispatch budgets |
| Why does an agent have more than one native session? | Native sessions |
| Who can use a skill? | Skills |
| Why is work waiting for me? | Memory and approvals |
| Where does state live, and what keeps running when I close the page? | Architecture overview |
Next
- Getting started: install Ensemble and reach a first group reply.
- Guides: apply these concepts to a task.
- Reference: look up exact commands, keys, tools, and settings.
Go deeper
- ADR index: every accepted architecture decision.
- Implementation notes: service, TUI, storage, and native-tool boundaries.
- Evidence index: verification records for the behavior described here.