Desktop handoff
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
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.
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.