The service
Collins is two programs. collins-service runs your sessions: every agent's pty, the terminal panel's shells, the sandboxes, the shared state (state.json), the session tools' MCP socket, every gh and git call Collins makes for you, and everything that spends tokens. collins, the window, is a client of it: it connects over a Unix socket, renders each session in a terminal and hosts the workbench around it. Quitting the window, or losing it to a crash, ends nothing: the agents keep working on the service, and the next window picks them up.
Nothing about the window looks different because of the split, by design. What changed is what quit and close mean, below.
Same machine, or not
Both halves run as the same user. They usually share a machine; a service on another machine is reached over ssh, with the socket forwarded — see A service on another machine.
The window is not the only possible client. The protocol the socket speaks is specified in The service API, under the MIT license, for any other tool that wants to drive a service.
What runs where
| The service | The window |
|---|---|
| Agent processes, on ptys it holds; the screen model of record for each | A terminal per session, painted from the service's stream |
~/.claude: transcripts, the CLI's trust entries, its login | The sidebar, composer, editor, git page, PR pages |
state.json: names, favorites, archives, drafts, PR records, notifications, the pty table | ui-state.json: appearance, geometry, keybindings, panel layouts, open_tabs |
Busy and finished-run detection, /bg handoffs, the agent list | Notification cards, sounds, the status icon, Caffeine Mode |
| The session tools' MCP socket, the sandboxes and their grants | Dialogs and what you type |
gh, git reads for PRs, titles, usage, icon generation, login repair | The update check (it describes the window's package) |
The window never reads a session's state off its own terminal: busy, the session a terminal belongs to, whether a prompt would land are the service's facts, sent as events. The window keeps a mirror of the store and of the settings that the service keeps current.
Starting
You never start the service by hand. When the window starts it looks for the service's socket ($XDG_RUNTIME_DIR/collins/<app id>/api.sock) and, finding none, starts one: systemctl --user start collins-service.service where systemctl exists and the unit is installed, else it spawns collins-service itself, detached. The unit ships in the collins-service package of every channel (the .deb, the RPM, the PPA and the AUR; the window's collins package depends on it), at /usr/lib/systemd/user/collins-service.service with the keeper's beside it, and is written by collins --install-desktop for a pip install. The packages do not enable it: nothing runs until a window asks, and nothing starts at login. To have it run from login, enable it yourself:
systemctl --user enable collins-service.serviceWhen the socket takes longer than the window's wait, the window asks systemd: a unit still starting (a slow cold start) or still stopping (a graceful stop ahead of the start) is waited for, up to about 90 s in all; one that is failed or stays inactive (a stale ExecStart from an older install, a service exiting with an error), or is active with no socket where the window looks (a unit running under another XDG_RUNTIME_DIR), is not trusted again by that window, which spawns the service itself from then on, says so once in a toast ("The Collins service is running unmanaged"), and trusts the unit again the next time a systemd-started service answers. journalctl --user -u collins-service.service says why the unit failed.
A service spawned without the unit has no restart policy; one the unit runs is restarted on failure. A source checkout (data/install.sh installs the launcher and icons, no unit) spawns the service too: with no collins-service on PATH, the window runs python3 -m collins.service.main from its own checkout. The debug instance (./start-debug, app id com.episode6.Collins.Debug) always spawns its own, with no unit, beside your real one: the script first stops any service (and keeper) already running under the debug id, so the window and the service it then spawns both run the checkout it was started from. It shares your config directory and so your state.json: run the debug instance and the real one one at a time.
A second collins-service for the same app id finds the first's lock and exits 0.
A package upgrade never restarts a running service: the new window keeps talking to the old service for as long as their protocols overlap. To run the new service code, use Restart service (below). The first window after an upgrade from a service older than v0.1.5 hides nearly everything, and its banner has the button.
Quitting, detaching and reopening
A tab is a view over a session's terminal on the service.
- Detach (the tab menu, a session row's menu) closes the view and leaves the session running. The row becomes a running row (yellow, with the barber pole while the agent works); opening it attaches to the session as it stands, mid-turn included.
- Close is unchanged: the agent is asked to exit, with the same confirmations. A session you asked to stop (a tab's close, Stop Sessions and Quit) stops even if its window goes before the agent has left: the service runs the graceful exit and, when the agent ignores it, ends the session itself.
- Quit detaches every tab (unless When quitting with running sessions says otherwise). With sessions running, the quit dialog says so and offers Quit, Stop Sessions and Quit (each agent asked to exit first, as quitting always did before the service) and Keep Running (Hide Window). The status icon belongs to the window: it goes with it, though the sessions keep running. A New Thread whose first prompt was never sent, and a tab whose agent has already exited, end with the window: nothing of theirs is left to keep running.
- Reopening. The window records the tabs it has open on this service (
open_tabsinui-state.json) and reopens them at the next launch and after a reconnect: a session the service still runs is attached, one that ended meanwhile (a restart, a crash of the service) is resumed withclaude --resume. - A crash or
kill -9of the window ends nothing.
A session counts as running only while its CLI runs: a shell left behind after the agent exited is not a running row, and opening that session resumes it. A shell with no agent in it that no window shows — a launch whose claude never started, or a detached session whose agent has quit on its own — is closed by the service rather than kept: it is no running session, and nothing would ever attach to it. A fresh launch is given time first: a shell whose agent has never been seen running is held for 30 s from its spawn (the shell may still be running its rc before it starts the typed command) and checked once more at the hold's end, so a detach or a crash of the window right after Send does not close a healthy launch; attaching within the hold cancels the check. The service refuses to spawn a second CLI on a session that is already running ("This session is already running in the Collins service"); the window attaches instead.
A finish or a message that arrives while no window is open is in the bell when the next window connects, unread, not on the desktop: nothing was there to announce it, and the window does not announce it late. Set Notification command (notify_command, Preferences → Service) and the service runs that program for each of them instead, with the notification in COLLINS_NOTIFY_* environment variables (see Notifications and A service on another machine).
If the connection drops while a window is open, the window shows a "Reconnecting to the Collins service" banner, finds or restarts the service with a growing backoff (1, 2, 5, 10, then every 30 s) and attaches every tab again from the service's screen model. A window reconnecting after a dropped link keeps its standing desktop notifications; only one read elsewhere meanwhile comes down.
Restarting and stopping
A restart ends no session. The service does not hold the sessions' terminals itself: a second small program, collins-keeper, forks every agent and panel shell on the service's behalf, stays their parent and keeps a duplicate of every terminal's master. When the service stops, whatever runs in those terminals keeps running: an agent mid-turn blocks on its output for the moment the service is away, and the service that starts next asks the keeper for its terminals, loads the screen it saved for each (the screen model of record, written every few seconds and at the stop), makes every program repaint, and picks up where the last one stopped. For a sandboxed session it holds the box again, mounts its live grants again and only then sweeps what nothing uses. What is lost is at most the last read the dying service had taken and not yet shown, which the repaint puts right.
Restart service (the main menu) says what the restart means for the sessions (how many run, how many are working, that they keep running through it and each open tab shows its own again once the service is back; and that the /bg background agents keep running too: they belong to the CLI's daemon, see below). Restart Now does it at once; Restart When Idle has the service wait until no session is busy (it looks every 2 s), shown as "Restarting when idle" with a Cancel where the reconnect banner goes. The service disconnects its windows first, so a window sees the link go, reconnects to the new service and attaches every open tab again. Without a keeper (none could be started, or COLLINS_KEEPER=none in the service's environment) the restart is the old one: every foreground session ends gracefully, is recorded as resumable, and each open tab resumes its own once the service is back; the dialog says which.
A crash of the service ends nothing either: the keeper holds the terminals, the next service adopts them. A crash of the keeper loses nothing running (its children are reparented and run on, the service reads them still) but their exit statuses: the service starts another keeper and hands it the terminals, and such a session's end is reported with no status. The /bg daemon and its agents hold no pty of the service's and run on through any of it.
The protocol mismatch dialog. A service and a window speak the same protocol or one apart; outside that the window refuses to connect and names both versions. If the service is the older it offers Restart Service (the service is sent SIGTERM) and Quit; if the service is newer, the dialog asks you to upgrade Collins and the window quits. A restarted service that still speaks another protocol gets the same ending.
To stop the service outright:
systemctl --user stop collins-service.service # the unit
kill $(pgrep -f 'bin/collins-service') # a spawned oneEither is SIGTERM, and with the keeper present it stops the service alone: every session runs on under the keeper, blocked on its output, until the next service adopts it (the next window starts one). To stop every session for good, stop the keeper as well:
systemctl --user stop collins-keeper.service # ends every session it holds
# a keeper the service spawned itself (no unit): its pid file names it
pid=$(cat "$XDG_RUNTIME_DIR"/collins/com.episode6.Collins/keeper.pid)
grep -q collins-keeper /proc/"$pid"/cmdline && kill "$pid"The pid file is removed when the keeper exits by itself; one left by a keeper that was killed can name any process by now, which is what the cmdline check is for. Only one keeper runs per app id: a second one started on the same socket (by hand, by a stall, by an upgrade) exits 0 on the first one's lock and changes nothing. A keeper that speaks an older protocol than the service and still holds sessions is left alone, and so is one that is there but does not answer: the service runs without a keeper, touches none of those sessions' rows, saved screens, sandbox plans or boxes, refuses to start a second copy of any of them ("running in a keeper this Collins service cannot read"), says so in the Restart service dialog ("held by a keeper this service cannot take over"), and stopping that keeper is the way on. Without any keeper process at all the rows name sessions that are gone, and are dropped.
The keeper ends each child it holds (SIGHUP, then SIGKILL) and exits. A service stopped with no keeper ends every foreground session the way Stop Sessions and Quit does: each agent is asked to exit (the CLI's own exit keystrokes, a worktree dialog answered, a bounded wait, then the process ended for good), its session id is recorded (resume_on_start in state.json), and the service exits 0, so the unit does not restart it by itself; the next window starts it again and finds the sessions resumable. Restart service runs the same stop sequence (service.restart) and exits as cleanly; the window that asked reconnects and starts it again.
Both units are KillMode=process: systemd signals the service (or the keeper) alone, never the agents or the CLI's background daemon. A stop, a restart or a package upgrade of the service therefore ends nothing: the keeper holds the sessions' terminals, and /bg agents and the daemon behind them were never the service's. The keeper's unit, collins-keeper.service, ships beside the service's and is started by the service on demand (never enabled by a package); where there is no systemd, or no unit, the service spawns collins-keeper itself, detached.
Where things live
| What | Where |
|---|---|
| The API socket | $XDG_RUNTIME_DIR/collins/<app id>/api.sock (0600, directory 0700) |
| Single-instance lock | service.lock beside it, held for the service's life |
| The keeper's socket, pid and lock | keeper.sock, keeper.pid and keeper.lock beside it |
| Each terminal's saved screen | ~/.local/state/collins/pty/<app id>/<pty id>.model, written every few seconds and at a stop, read by the next service, removed when the terminal ends |
| The local proof | local-proof beside it: 32 random bytes, 0600, minted at each start |
With no $XDG_RUNTIME_DIR | ~/.local/state/collins/<app id>/ for the three above; a path too long for a Unix socket falls back to a 0700 directory under the temp directory |
| The session tools' socket | mcp.sock beside api.sock when $XDG_RUNTIME_DIR is set; under the temp directory (/tmp/collins/<app id>/) otherwise |
| Service state | ~/.config/collins/state.json |
This device's state, open_tabs | ~/.config/collins/ui-state.json |
The proof is how the window finds out it shares the service's filesystem: it computes the proof's path for its own app id, opens it without following a symlink, requires a regular 0600 file of its own uid holding exactly 32 bytes, and sends the contents back. A service that merely names a path gets nothing read. Nothing in the window is gated on it yet; it is the check later phases hide local-only actions behind. The socket is not a security boundary: every client is already trusted with a shell.
collins-service --check
On a desktop the user manager has the desktop's environment and the service inherits it. On a headless box two things need doing first, and --check says which:
$ collins-service --check
service: 0.1.5, app id com.episode6.Collins
lingering: off (on a headless box the service and its sessions end at the last logout; to keep them: loginctl enable-linger you)
runtime dir: /run/user/1000
socket: /run/user/1000/collins/com.episode6.Collins/api.sock (none)
shell: /bin/bash (login profile and interactive rc read)
claude: /home/you/.local/bin/claude
bwrap: /usr/bin/bwrapshell: names the shell the capture used and what it read: login profile and interactive rc read; login profile read; the interactive rc handed the shell on (with the fix, ~/.profile or ~/.zprofile, and "or did not answer within 5 s" when the interactive shell was cut off at the limit); interactive rc read; the login profile did not answer; or, when neither answered, one of no answer within 5 s, shell could not be run (with the reason: the shell is not installed) and no PATH read from either round. In those three the service runs on its own environment. It never makes --check exit 1.
It exits 1 when $XDG_RUNTIME_DIR is unset or claude is not on the login shell's PATH.
- Lingering. Without
loginctl enable-linger, the user manager, the service and$XDG_RUNTIME_DIRgo away at logout and do not exist at boot. On a headless box,loginctl enable-lingeris the first step; thelingering:line names the command for your user while it is off, and says why it cannot tell (no loginctl, orloginctl did not say) when it readsunknown. Lingering is a note, not a requirement: it never makes--checkexit 1. Where polkit wants an administrator for it, run the command withsudo. Without a runtime directory the keeper's lock falls back under~/.local/state/collins/<app id>/with the rest; on a home directory shared over NFS by two machines, Linux's NFSflockemulation can make one machine's keeper exit on the other's lock, which leaves that machine keeperless (its service then forks its own ptys and a restart ends them). A runtime directory, which every login session has, avoids it. - The CLI on
PATH. Shells spawn with the service's environment overlaid by a login-shell capture, which is what finds~/.local/bin/claudeand yourPATHon a box with no desktop. Once at start the service runs two shells at once,$SHELL -lc 'env -0'(the login profile:~/.profile,~/.bash_profile,~/.zprofile) and$SHELL -lic 'env -0'(that and the interactive rc: aPATHthatpipx ensurepathput in~/.bashrcbehind Debian's non-interactive guard), to one 5 s deadline, and fails soft to its own environment. A shell counts only when what it printed holds aPATH; the interactive one's variables overlay the login one's. An rc that hands the shell on (exec zsh,exec fish, auto-tmux) prints nothing under-i, so the login profile's answer stands, but aPATHset only in such an rc is not seen: put it in~/.profileor~/.zprofile.--check'sshell:line says which answered. The capture wins (yourPATHorder too), exceptCOLLINS_*,XDG_*,PYTHONPATH,HOME,USERand systemd's own variables, which stay as the service was started with, and the service's own leadingPATHentries stay first.SSH_AUTH_SOCKis yours to provide there, as it is over ssh. Everyclaudethe service itself looks up (what the window's welcome asks about, the command a session starts with, titles, icons) is found on that samePATH, so a service started by--print-socketover a non-interactive ssh command finds the CLI that--checkreports.
collins-service --print-socket starts the service if needed and prints the socket's path.
Logging
COLLINS_LOG=INFO (or DEBUG) turns on the service's logging, to stderr: under the unit that is the journal (journalctl --user -u collins-service). A service spawned by the window sends its output to /dev/null unless COLLINS_LOG is set in the window's environment, in which case it inherits the window's stdout and stderr.
Requirements
libsoup 3 (gir1.2-soup-3.0, libsoup3) carries the socket and is a dependency of every package. The service imports no GTK: it runs on a box with no display, and its package, collins-service, depends on PyGObject, GLib and libsoup 3 alone (recommending bubblewrap, bindfs and fuse3 for sandboxed sessions). Install it without the window on a headless box (A service on another machine).