The daemon and worktrees

The daemon opens sessions on this computer when a terminal asks. The Tatu app uses it too, to open sessions from your phone.

To start it yourself, choose a folder containing your projects:

tatu daemon -root ~/projects

You can open sessions only in that folder or below it. A daemon without a relay serves this computer’s terminals only. Run /remote setup inside Tatu to set up the connection for paired devices.

Start it on demand

Press Ctrl+G and choose + New session. If no daemon answers locally, Tatu starts one. If no project folder is set, the screen asks for one and saves it as daemon.root.

Choose a project, give the session a name if you want, and choose whether to isolate its work. The terminal opens the new session when it is ready. Closing the terminal does not stop it.

Use /settings daemon.mode to choose when the daemon starts:

new-session (default): when + New session needs it; local terminals only.
with-tatu: also when you start an interactive Tatu or tatu agents; local terminals only.
with-tatu-phone: like with-tatu, but also connects to the relay so paired devices can open sessions. Set up /remote setup first.

with-tatu and with-tatu-phone do not start it for print mode, JSON mode, RPC mode or headless sessions. Without a project folder set, startup does not ask or launch it.

Set the folder with /settings daemon.root. Both settings are global, not project settings. A running daemon keeps its root until it exits; changing the mode updates an on-demand daemon’s relay connection without restarting its sessions.

An on-demand daemon stays while local agents or terminals need it. After none remain, it waits 30 seconds and exits. A daemon started by hand runs until you stop it.

Stop a session or manage worktrees

In the agents list:

Ctrl+K on a session the daemon opened asks before stopping it. This ends the session’s process, not just its current run. It cannot stop sessions you started yourself.
Ctrl+W opens the selected computer’s worktrees. Press Enter to reopen one as a new session, or Ctrl+X to remove it.

A worktree in use cannot be removed. Removing one with uncommitted or unmerged work requires an extra confirmation.

Isolated sessions

An isolated session works in a git worktree: a separate copy on its own branch.

The branch is tatu/<name>-<id>, or tatu/<id> without a name. The name is made suitable for a branch.
The folder is <parent>/.tatu-worktrees/<project>-<id>.
Tatu fetches the current branch’s upstream and starts there. With no upstream, a detached HEAD or a failed fetch, it starts from HEAD and shows a warning.
Ignored .env* files are copied too, except under node_modules.
A folder containing several repositories gets a worktree for each, plus its top-level files.

The worktree stays when the session ends. Only worktrees Tatu manages under the daemon’s root are offered here, not worktrees you created yourself.

Automations

The daemon also opens the sessions of automations at their time. It keeps them in ~/.tatu/automations.json, so they run only while the daemon runs. They count toward the limit below: a task whose time comes while the daemon is full is skipped as full.

Limits and errors

The default limit is 8 simultaneous sessions. Change it with tatu daemon -root ~/projects -max-sessions 12, TATU_DAEMON_MAX_SESSIONS, or max_sessions in ~/.tatu/remote/daemon.json. A flag wins over the environment, which wins over that file.

8 sessions are already open: stop a managed session or wait for one to end. The number follows your limit.
another tatu daemon is already running on this machine: use the existing daemon; only one runs per computer.
no relay in the startup line: local terminals can reach it, but paired devices cannot.
spawn_failed: the new session could not start. Read the accompanying reason, such as a missing credential or invalid model. See ~/.tatu/logs/daemon.log for daemon diagnostics.

If the connection drops while you request a session, check the agents list before asking again: it may already have opened.

Stopping or restarting the daemon stops the sessions it opened. A new daemon does not take those processes back; reopen sessions or worktrees yourself. Saved conversations remain resumable.

The daemon is not a launchd or systemd service yet. Start it yourself, or let Tatu start it when needed.