# Desktop handoff Source: https://docs.ideharmony.com/tui/desktop-handoff The TUI and the desktop are two views of the same daemon state. Moving between them is not an export, a sync, or a migration — it is opening a second window onto something that already exists. ## From the TUI ```text /desktop ``` Opens the desktop attached to the same daemon, with your session, tasks, and artifacts present. From a shell, the equivalent commands work after the installer exits: ```powershell harmony desktop harmony desktop --agent ``` `--agent` opens the desktop and focuses an agent terminal in one step. ## From the desktop Open any terminal in your project and run: ```powershell nala ``` Then attach to the session you were already using: ```text /attach ``` Or pick up the most recent paused one: ```text /resume ``` ## Why nothing is lost
Client continuityThe desktop, the TUI, and the CLI are three clients of one daemon. The daemon holds the session, run, tasks, artifacts, approvals, and traces. Each client is a view onto that same state, so switching between them transfers nothing — there is nothing to transfer. Two clients can watch the same session at once because neither writes directly; both issue remote calls and the daemon serialises them, with a writer lease where several participants could write the same record. Unsubmitted composer text is the exception: it lives in the client and does not follow you.CLIENTS — VIEWS ONLYHarmony Desktoppanes · fleet · approvalsHarmony TUIkeyboard · transcriptHarmony CLIscriptableOne daemon — the single durable writersession · run · tasks · artifacts · approvals · tracestwo clients may watch at once; a writer lease decides who may writeException: unsubmitted composer text lives in the client and does not follow you.
Switching clients transfers nothing, because there is nothing to transfer — the state was never in the client you left.
Neither client owns the state. The daemon does. | Owned by | What | |---|---| | Daemon | Sessions, tasks, artifacts, messages, orchestration | | Session host | Provider processes and PTYs | | Client | Presentation, and your decisions | A client is disposable. Closing one does not signal the daemon, which is the same reason a session survives closing your terminal or rebooting. ## Both at once Two clients can watch the same session. Neither writes directly — both issue RPCs, and the daemon serialises the result, with a writer lease where several participants could write the same record. > [!NOTE] > This is genuinely useful rather than a curiosity: leave the desktop open on a > fleet view while working in a terminal, and the two stay consistent because > they are reading the same source. ## What does not transfer | Does transfer | Does not | |---|---| | Sessions, tasks, artifacts, messages | Your terminal's own scrollback from before you started `nala` | | Session route and mode | Unsubmitted composer text | | Approvals and their state | Shell history in the surrounding terminal | Unsubmitted composer text is the one that surprises people. Text staged but not submitted lives in that client. See the `needs_enter` state in [delivery lifecycle](/docs/a2a/delivery-lifecycle). ## How the CLI finds the desktop The installed shim exports a validated absolute path to the desktop executable. When the desktop is already running, `harmony desktop` uses a dedicated activation call that restores, shows, and focuses the window, selecting or creating the requested workspace. When it is not running, the CLI starts the validated executable and waits for its endpoint with a bounded timeout. > [!SECURITY] > The path hint is validated before use — it must be an absolute, existing file > with the expected executable name. An environment variable should not be able > to redirect the CLI into launching an arbitrary binary. ## Related - [Sessions](/docs/tui/sessions) - [Session survival](/docs/concepts/session-survival) - [Harmony Desktop](/docs/desktop)