harness-multitool

The daemon

One daemon per machine hosts every conversation of the harness. Windows are its clients: an agent keeps working when its window closes, and callbacks, Telegram and other agents reach it through the daemon.

What it is

The daemon is a background process, multitool daemon, that holds the conversations (ADR 0024). Every message in and out goes through it, and it alone writes a conversation's log (INV-15, CON-75).

A session's engine runs in the daemon: its log, its tools and its calls to a provider or a delegate. A window holds a view, sends operations and hears events.

What the daemon holds once is shared by every window and every profile (CON-124):

How it works

Windows talk to it over a local socket

Windows, the harness's MCP servers and the command line talk to the daemon over one local socket, <data dir>/daemon/daemon.sock, named in address.json beside it (ADR 0027, CON-130). On Linux the data dir is ~/.local/share/harness-multitool/.

A window works with any daemon that speaks its protocol, whatever its build. A daemon of another protocol is replaced when it is idle; while it runs other windows' conversations, the window waits and asks it every 2 seconds to stop if idle.

HTTP for callbacks

The daemon also listens on an HTTP port on 127.0.0.1. It serves callbacks from outside, /health and the dashboard, nothing a window needs.

Every conversation has its own callback URL, http://127.0.0.1:<port>/callback/<token>, the same across tabs, windows, reloads, daemon restarts and moves between adapters (CON-164). A callback reaches the session wherever it is open and starts a run of an idle agent. A session not open keeps it, 500 at most for 7 days. See callbacks.md.

Agents outlive their windows

Leaving a window (/exit, or Ctrl+C twice) asks what its agents do (CON-181):

  1. stop now;
  2. let the command under way finish;
  3. let them finish their work, then end;
  4. keep them running in the daemon, where Telegram, callbacks and other agents reach them.

'Remember my choice' sets Settings > Behaviour 'On exit'. A window lost without a word (killed, its terminal or ssh dropped, silent for 30 s) does 'On an accidental loss', 3 by default.

With no window, a question an agent asks (a permission, ask_user, a plan approval) waits in its conversation. The next window that opens the conversation takes over its run and its question.

When the connection drops

A window that loses the daemon tries again every 2 seconds for as long as it is open, and starts a daemon if none comes back (CON-131). It shows a toast at every loss and every connection made.

While it is down, a second toast stays up with a pulsing bar and the attempts so far, naming the reason. What you send meanwhile is refused at once with a toast, and the typed message stays in the composer.

The window never hangs on the daemon: with no connection a call fails at once, and a daemon that does not answer in 2 seconds counts as lost (CON-132). When the connection is back, every tab reopens its conversation.

Delegate processes

Each Claude Code or Codex process the daemon starts runs in a systemd user scope of its own under multitool-agents.slice on Linux, counted apart from the daemon (CON-166).

No delegate outlives its daemon. On a stop the daemon ends each one, SIGTERM then SIGKILL after 3 s (CON-128). multitool daemon reap stops scopes left by a daemon that is gone; it runs at each daemon's start and after the service stops (CON-182).

Using it

The window starts the daemon when it needs one. Installed with ./install.sh --local, the daemon runs as a user service (CON-162):

OSService
Linuxsystemd user unit multitool-daemon.service, with linger enabled unless --no-linger
macOSa LaunchAgent
Windowsa Scheduled Task multitool-daemon at logon

Elsewhere it starts in the background with a warning. --no-service installs only the binary. Before restarting a daemon, the installer checks whether agents are working and asks first (CON-176).

multitool daemon                # run it in the foreground; --port picks the port on localhost
multitool daemon --status       # what it counts: conversations, Telegram, its rss_mb and peak_mb
multitool daemon restart        # stop it, its runs included, and start this build's on the same port
multitool daemon stop           # stop it and start none
multitool daemon reap           # stop delegate scopes whose daemon is gone
multitool dashboard             # print the dashboard's address with its token
systemd-cgtop multitool.slice   # each delegate's memory, apart from the daemon's

multitool daemon restart goes through the service when one is installed. Runs going on are stopped and counted, but no conversation is lost: every open window finds the new daemon and reopens its tabs (CON-128). From Telegram, /restart does the same after a ✅ (CON-167).

/reload, or the agent's plugins_reload, swaps the window's binary and replaces the daemon too. The daemon keeps its port, so callback URLs stay valid, though callbacks sent during the second of the swap fail (Reload).

The dashboard

The daemon serves a page on its HTTP port, /dashboard, local only, opened with the token multitool dashboard prints (ADR 0029). Its tabs:

The token lets whoever has it see and start games, so keep it to yourself.

Across machines

The project's principles name many agents across machines as the normal case (P-9), and the roadmap plans for it. Today the daemon serves one machine.

What works today

crates/session/src/remote.rs is the window's side of the local daemon, RemoteSessions, not a network client (crates/session/src/remote.rs:1).

What is planned

So the daemon is today a local orchestrator for the agents of one machine, reachable from outside only through Telegram. A shared orchestrator and sync node across machines is a goal on the roadmap, not a feature.

Limits and status

Specs and decisions

This page's source