Skip to main content
Harmony
Download

Desktop handoff

PreviewAvailable on: WindowsShips in the preview channel only. Not a stable release.

Move between the terminal and the desktop without losing anything, and why nothing is lost.

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

/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:

nala desktop
nala 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:

nala

Then attach to the session you were already using:

/attach <session-id>

Or pick up the most recent paused one:

/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 · approvalsNALA 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 byWhat
DaemonSessions, tasks, artifacts, messages, orchestration
Session hostProvider processes and PTYs
ClientPresentation, 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 transferDoes not
Sessions, tasks, artifacts, messagesYour terminal's own scrollback from before you started nala
Session route and modeUnsubmitted composer text
Approvals and their stateShell 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.

How the CLI finds the desktop

The installed shim exports a validated absolute path to the desktop executable. When the desktop is already running, nala 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.