Glossary
PreviewAvailable on: WindowsmacOSLinuxShips in the preview channel only. Not a stable release.
Canonical definitions, with the distinctions that matter kept sharp.
Terms are grouped by what they belong to. Where two terms are commonly conflated, the difference is stated rather than implied.
Four distinctions to get right first
IMPORTANT
A terminal is not an agent. A pane can run a plain shell forever with no model involved.
Installed is not authenticated. Harmony can detect a provider binary and still be unable to run a turn.
Queued is not delivered. A message can reach a harness and never start a turn.
Process alive is not working. An agent can hold a session open and advance nothing.
Product
| Term | Definition |
|---|---|
| Harmony | The product as a whole: desktop, TUI, CLI, daemon, and MCP server |
| Harmony Desktop | The Electron application — the full-surface client |
| NALA TUI | The terminal-native agent surface, started with nala |
| Harmony CLI | Scriptable, non-interactive commands against the same daemon |
| NALA Agent | The first-party agent identity, as distinct from third-party providers |
| Pi | The extensibility runtime bundled with the product |
Runtime
| Term | Definition |
|---|---|
| Daemon | The local process that owns durable state: sessions, orchestration, tasks, artifacts, A2A, channels. Survives app close |
| Session host | Owns provider processes and PTYs, plus launch reservations and principal registration |
| Client | Anything presenting the daemon's state — desktop, TUI, CLI. Closing a client does not stop work |
| Native Capability Bus | The capability layer clients use to reach daemon functionality |
| Principal | A registered identity a session runs as |
| Writer lease | The mechanism deciding which participant may write a shared record |
Workspace model
| Term | Definition |
|---|---|
| Workspace | A named context with its own pane tree, working directory, and status |
| Surface | A tab within a workspace: terminal, browser, editor, diff, file tree, or a Harmony panel |
| Pane | A leaf in the split tree. Max 20 per workspace |
| Terminal session | A durable shell owned by the daemon, rendered in a pane |
Agents and routes
| Term | Definition |
|---|---|
| Agent | A model-driven participant that can take work |
| Agent session | A durable conversation with an agent |
| Provider | The vendor behind an agent CLI (Claude, Codex, Cursor, …) |
| Account profile | Which of your identities with a provider is in use |
| Model | The specific model requested |
| Effort | Reasoning depth, where the provider exposes it |
| Execution route | The full path: harness, provider, account, model, effort, tool set, platform, billing class |
| Billing class | Whose money is spent, under which plan |
| Harness | The agent program being driven |
Work
| Term | Definition |
|---|---|
| Task | A durable unit of work with an identity and a state. Outlives panes and reboots |
| Plan | A proposed sequence of steps toward a goal |
| Plan revision | A numbered version of a plan; revisions are kept |
| Orchestration run | One execution attempt of a plan |
| Artifact | A durable Markdown output attached to the work |
| Worktree | A separate git checkout so parallel agents do not collide. File isolation, not a security boundary |
| Delegation | An edge assigning a task to another agent |
Messaging
| Term | Definition |
|---|---|
| A2A | Agent-to-agent messaging: send, ask, reply, inbox |
| Channel | A durable, Slack-like room for agents and humans |
| Attention | The signal that something needs a human |
| Approval | An explicit consent gate before a consequential action |
Delivery states
The real states Harmony reports, not a generic lifecycle:
| State | Means |
|---|---|
received_and_started | The agent is working on a turn. The only state where started is true |
queued_behind | Accepted into the harness queue, with N ahead |
received_not_started | Text delivered, no work signal yet |
idle | At the prompt, queue empty |
needs_enter | Staged in the composer, needs another Enter |
unknown | Could not be determined from available evidence |
See delivery lifecycle.
Extensibility
| Term | Definition |
|---|---|
| Skill | A packaged capability an agent can invoke |
| Command | A slash command in the TUI or desktop composer |
| Prompt | Reusable instruction text |
| Extension | Code extending the application |
| Plugin | A packaged extension |
| Hook | A handler fired on a lifecycle event |
| MCP | Model Context Protocol — Harmony publishes tools to MCP hosts |
| ACP | Agent Client Protocol — Harmony can drive external ACP harnesses |
SECURITY
Extensions, skills, and plugins are not sandboxed by default. Treat third-party extension code as code you are choosing to run.
Modes
| Term | Definition |
|---|---|
| Safe / YOLO / Ask | Execution modes governing how much an agent may do unprompted |
| A2A mode | Off, Connect, or Orchestrate — how much agents may coordinate |
| Crew Mode | Ownership-scale delegation, separate from the YOLO authority setting |