Claude Code session manager on Windows, macOS and Linux
| OS | Session backend | Notifications | Folder picker | Prebuilt binary |
|---|---|---|---|---|
| macOS arm64 / x64 | tmux | terminal-notifier or osascript | osascript | prebuilt binary (cargo-dist) |
| Linux x64 / arm64 | tmux | notify-send if installed |
zenity or kdialog if installed |
prebuilt binary (cargo-dist) |
| Windows x64 | session host (below) | PowerShell toast | PowerShell WinForms dialog | prebuilt binary and PowerShell installer (preview, not yet verified on real Windows); x64 runs under emulation on ARM |
A feature the OS lacks answers 501 and the TUI says so; nothing else changes.
Session host (Windows, or GARAGE_BACKEND=host anywhere)
Section titled “Session host (Windows, or GARAGE_BACKEND=host anywhere)”The daemon picks its backend once at start (GARAGE_BACKEND=tmux|host; unset
means tmux on macOS and Linux, host on Windows). With the host backend each
session is one detached claude-garage host process:
- it runs
claudeon a ConPTY (a plain PTY on Unix), mirrors the output into a vt100 screen with 10,000 lines of scrollback, and listens on 127.0.0.1; - it writes
<garage dir>/hosts/<id>.json(port, token, pid). The directory is 0700 and the files 0600 on Unix; on Windows the per-user profile directory is the protection, and aGARAGE_DIRoutside the profile gets an owner-only ACL (or the host refuses to start). File names escape every byte outside[A-Za-z0-9_-]as%XX; - every connection starts with the token; a control connection answers info, history, capture, rename and shutdown;
- hosts outlive the daemon, the TUI and the terminal, but not a reboot. A record whose port refuses connections, or whose host process is gone, is stale and is removed by the daemon, only if the file still holds the record that was probed (a respawn’s new record is never deleted).
The daemon never sends the token over HTTP. GET /api/attach?id= answers
{"kind":"tmux","socket":"name"} or {"kind":"host","id":"..."}; the TUI builds
the tmux command itself (socket names are [A-Za-z0-9_-]{1,64}) or reads the
host’s record from the garage directory, and only dials loopback addresses.
Every daemon route also checks the Host header (127.0.0.1, localhost or [::1]
on the daemon’s port) so a web page cannot reach it by DNS rebinding.
Testing the host backend on macOS or Linux:
GARAGE_BACKEND=host claude-garage daemoncargo test -p garage-host -p claude-garage # real host processes in temp dirs, no tmuxLinux packaging notes
Section titled “Linux packaging notes”- Build targets:
x86_64-unknown-linux-gnuandaarch64-unknown-linux-gnu. The workspace is pure Rust (no C dependency):cargo check --workspace --all-targets --target <triple>passes from macOS with onlyrustup target add. - Runtime:
tmux(required),claude; optionalnotify-send(libnotify-bin),zenityorkdialog. - Binaries to ship per target: one
claude-garage(TUI, daemon and launcher in one program, first-party plugins embedded). cargo-dist builds it natively on a macOS, Linux x64, Linux arm64 and Windows runner; seedist-workspace.toml. - glibc: build on the oldest distro you support (e.g. an Ubuntu 22.04 runner) or the binary needs the newer glibc of the build machine.
- Live check (task 5.2) in an OrbStack Ubuntu machine:
sudo apt install tmux libnotify-bin zenity, build, then create, attach, close and restore a session and trigger a needs-input notification.
Windows: what a contributor should check by hand
Section titled “Windows: what a contributor should check by hand”Compiles for x86_64-pc-windows-msvc (cargo check --workspace --all-targets) but
has not been run on Windows:
claude-garagestarts the daemon detached (no console window) and the TUI.ncreates a session: aclaude-garage hostprocess appears,claude(an npmclaude.cmdshim orclaude.exe) runs in it, the tile shows it.- Typing, Shift+Enter (newline), Ctrl+Enter (send now), resize, scrollback.
- Quit the TUI: sessions keep running. Kill a host in Task Manager: the session shows as restorable.
- Toast on needs-input, the folder picker,
x x(taskkill of the tree). claude agents --jsonis run by name: confirm it resolves whenclaudeis a.cmdshim.
Credits
Section titled “Credits”Windows host design based on PR #2 by Sabbir Hossain Khan.