# How Harmony works Source: https://docs.ideharmony.com/concepts/architecture Harmony's core design decision is that **the work does not live in a window**. Everything that matters (terminals, tasks, agents, messages, approvals, artifacts) lives in a detached daemon process. The desktop app, the `nala` TUI, and the CLI are just clients of that daemon. This one decision explains most of what Harmony can do that a terminal tab cannot. ## The daemon The daemon is a background process that owns every PTY (terminal session) and every piece of orchestration state. Because it outlives any window: - Closing the app does not kill your terminals. Rebooting does not either. - Multiple clients can attach to the same session at once. - Agents keep working while you are not looking at them. Manage it directly when you need to: ```bash harmony daemon status harmony daemon logs harmony daemon restart harmony daemon stop # refuses if work is active ``` ## The single durable writer For orchestration state, the daemon is the **sole writer**. Tasks, agents, messages, approvals, and artifacts all flow through one store, which is what makes A2A messaging durable (messages survive restarts and land exactly once) and approvals meaningful (there is exactly one queue to approve from). The entity model: ``` Workspace (1) ──< Task (N) ──< Agent (N) │ │ │ ├──< Session (1) │ │ queued → starting → running → waiting → stopped/failed │ └──< Delegation (N) │ parent → child, depth-limited, cycle-detected └──< Artifact (N) │ └──< Artifact (N) parent dependency, acyclic ``` Tasks come in four modes: **Regular** (standard tracked work), **Plan** (an idea captured without running shell commands), **Epic** (large multi-task work), and **Review** (code review with findings to resolve). ## The orchestration services Inside the daemon, each concern is a service: tasks, providers, messages, agents, artifacts, spawn proposals, approvals, idea capture, comments, claims, search, snapshots, journals, verification, scheduling, worktrees, reconciliation (detecting ambiguous writes after timeouts or crashes), and the skills manager. You will meet them through the UI and CLI rather than directly, but their names show up in traces and `harmony doctor` output. ## Why local-first matters here Because the daemon is on your machine, everything described above works offline, with zero accounts, and with your code never leaving the machine unless you ask a remote model to see it. The optional Harmony Pro plan adds cloud hosting, so agents keep working while your machine is off. It does not sell model usage (agents use your own provider subscription), and it is never a requirement. The local product is the permanent foundation. ## Where things live on disk | What | Windows | Linux / macOS | |---|---|---| | Background service data (sessions, tasks, agents, scrollback) | `%USERPROFILE%\.wmux\` | `~/.wmux/` | | Desktop app data (window layout, preferences, secure storage) | `%APPDATA%\NALA\` | `~/.config/NALA/` (Linux), `~/Library/Application Support/NALA/` (macOS) | | Logs | `%APPDATA%\NALA\logs\` (desktop app) and `%USERPROFILE%\.wmux\logs\` (background service) | `~/.config/NALA/logs/` or `~/Library/Logs/NALA/` (desktop app) and `~/.wmux/logs/` (background service) | | App install | `%LOCALAPPDATA%\NALA\` | `/opt/nala/` or AppImage | Harmony was first released as NALA, and it grew out of an open-source project called wmux. Folder names, pipes and the single-instance lock keep those older names so existing installs keep working. See [Configuration & data](/docs/reference/configuration) for the full list. ## Next steps - [Durable sessions](/docs/concepts/session-survival) — what survival actually means. - [The Harmony Agent](/docs/tui) — the resident agent and how routing works. - [A2A messaging](/docs/a2a) — the protocol on top of the store.