# Harmony TUI Source: https://docs.ideharmony.com/tui The Harmony TUI is a full agent surface that lives in a terminal. It is not a cut-down version of the desktop and not a chat box: it talks to the same daemon, creates the same durable tasks, reads the same artifacts, and participates in the same agent-to-agent messaging. Start it in any terminal, in the directory you want to work in: ```powershell nala ``` ## What it is | Layer | What it means | |---|---| | Identity | A first-party Harmony agent, not a third-party CLI wrapped in branding | | Runtime | The TUI engine plus one reasoning owner; models never load in the TUI process | | Client role | A **client** of the daemon — closing it does not end your work | | Tools | Harmony tools: tasks, artifacts, worktrees, A2A | > [!IMPORTANT] > The TUI is a client. The daemon owns orchestration state and the session host > owns provider processes. This is why you can detach, close the terminal, and > reattach later to the same session. ## How a turn actually runs When you submit a message the TUI does not simply create a task and hope: 1. It ensures a structured session for the selected reasoning provider. 2. It submits the prompt, and the daemon spawns the provider turn. 3. It polls session events into the transcript until the turn completes. 4. It keeps the durable task id from the acknowledgement. The header chrome is gated on evidence: **Starting**, **Thinking**, **Ready**, and **Failed** appear on real submit acknowledgement and terminal turn evidence, not on optimism. Polling continues through error events until the canonical completion event, so a failure does not leave stale "running" state on screen. > [!NOTE] > If the interface looks reluctant to claim progress, that is deliberate. It > reports what it can prove, and `unknown` is a real answer. ## The four-character interaction language Almost everything is reachable from four prefixes: | Prefix | Addresses | Example | |---|---|---| | `/` | Commands — 80 built-ins | `/tasks` | | `@` | Files, agents, and entities | `@src/config.ts` | | `#` | Tasks and artifacts | `#task-id` | | `!` | Your shell, directly | `!git status` | Learn these four and the rest of the surface follows. See [the composer](/docs/tui/composer). ## What you can do without leaving the keyboard | Area | Commands | |---|---| | Session | `/resume` `/fork` `/attach` `/detach` `/stop` `/quit` `/clear` `/compact` | | Route | `/mode` `/provider` `/model` `/profile` `/permissions` | | Work | `/task` `/tasks` `/artifact` `/artifacts` `/export` | | Fleet and A2A | `/agents` `/send` `/ask` `/delegate` `/review` | | Code | `/worktree` `/diff` | | Context | `/context` `/memory` `/trace` | | Extensibility | `/skills` `/extensions` `/mcp` `/tools` | | Voice | `/voice` `/speak` `/read-aloud` `/bark` `/play-back` | | Presence | `/stay` `/come` | | Meta | `/help` `/usage` `/doctor` | The complete generated list, with descriptions straight from the registry, is at [TUI slash commands](/docs/tui/slash-commands). ## Overlays Heavier interactions open as overlays rather than scrolling the transcript: command palette, agent fleet, context and memory, diff review, doctor recovery, permissions, plan approval, provider picker, session picker, tasks and artifacts, and traces. ## Errors are structured Failures carry a code and a `retryable` flag rather than prose you have to interpret. Transport codes (`DAEMON_NOT_CONNECTED`, `DAEMON_TIMEOUT`, `DAEMON_CANCELLED`, `DAEMON_RPC_ERROR`) are distinct from domain errors, so "the daemon is unreachable" never looks like "the model refused". ## Handing off to the desktop ```text /desktop ``` Opens the desktop attached to the same daemon, with your session, tasks, and artifacts intact. The reverse works too — start in the desktop, attach a terminal later. ## Related - [Your first TUI session](/docs/getting-started/first-tui-session) - [The composer](/docs/tui/composer) - [Sessions](/docs/tui/sessions) - [TUI slash commands](/docs/tui/slash-commands)