Concepts
The nine ideas the rest of the documentation assumes: what a session is, who owns durable state, and why activity is not progress.
Everything else in these docs is a procedure. This section is the model those procedures operate on. If a page elsewhere says "the run continues after you close the window" and that sounds like a claim rather than a consequence, the explanation is here.
Nine pages, and they are not independent. Two ideas run through all of them:
- The client is not the orchestrator. A window is a view onto work that lives somewhere else. That single separation is why sessions survive, why two surfaces can watch one run, and why closing something does not cancel it.
- State is the truth, not activity. A process that is running is not a task that is progressing. A fleet that looks busy can be entirely blocked. Every page here that seems to be splitting hairs is drawing that line.
Read in this order
If you are new, take the first three in sequence and the rest as needed.
| Read | Page | Answers |
|---|---|---|
| 1 | How Harmony works | The detached daemon, the single durable writer, and the entity model underneath every session |
| 2 | The three surfaces | Desktop, nala TUI, and CLI as three peers of one daemon |
| 3 | Agents and sessions | What counts as an agent, what a session actually is, and why a live process is not progress |
| 4 | Durable sessions | Terminals that outlive the UI, reattach after sleep, and restore honestly after a restart |
| 5 | Tasks, plans, and runs | The durable work model, and why state matters more than activity |
| 6 | Providers, models, and routes | An execution route is eight things, not one, and that is how cost is controlled |
| 7 | Approvals and permissions | Spawn proposals, risk tiers, permission modes, and what YOLO really turns off |
| 8 | Worktrees | How parallel agents avoid colliding, and what isolation does not protect |
| 9 | Software factories | Many agents collaborating through shared versioned artifacts and an auditable protocol |
The distinctions worth slowing down for
Each of these is a place where two things look identical from the outside and behave differently. They are the recurring source of confusion, so they are called out on their own pages rather than left implicit.
NOTE
A session is not a process. A task is not a run. Queued is not delivered, delivered is not accepted, and accepted is not completed. An agent reporting success is not evidence that it succeeded.
Where to go next
- To do something rather than understand it, start at Getting started.
- For what is actually implemented versus designed, read feature status before depending on anything in this section.
- For one-line definitions of the terms used above, see the glossary.