Roost: A Single-Go-Binary Sidebar for Claude Code with Clickable Prompt History, File Tree, and Notifications

A developer built Roost to address three gaps when using Claude Code over SSH via tmux: clickable prompt history, a file tree to reduce cat-ing files, and push notifications when Claude is waiting. It's a single Go binary serving a web interface on 127.0.0.1:8080 designed for SSH tunnelling.

Key Features

• xterm.js terminal backed by tmux: Survives WebSocket disconnects, sleep, and server restarts. Every session is tmux new-session -A -s {id}.
• File tree: Preview files, drag-drop upload, and automatically follows your current directory by reading tmux's pane_current_path — no shell integration required.
• Activity panel: Reads ~/.claude/projects/*.jsonl and shows every prompt. Click a prompt → terminal scrolls back to that turn.
• Top-bar chips: Display active model and latest context tokens.
• Push notifications: Uses Claude Code's Stop hook to ping your laptop when Claude becomes idle, even with the tab backgrounded.

Design Decisions

• tmux as durability layer: The shell survives disconnects and restarts because tmux handles session persistence. Roost only owns a WebSocket bridge and an append-only disk log.
• Single-user-per-instance: No accounts or RBAC. Two people sharing a host each run roost serve on a different port. UNIX UIDs handle isolation; reverse-proxies handle multi-tenant auth.
• Vanilla JS, no build step: Frontend is plain <script> files embedded via //go:embed all:web. No bundler — easier to debug and ship.

Notable Bug Fix

tmux's display-message -p '#{x}\x1f#{y}' returns 0x1f as a literal underscore when launched without a UTF-8 locale (e.g., from systemd units). The one-line fix: tmux -u. If you pipe tmux through field separators, lock the locale.

Compatibility

Validated on Linux server + Windows Chrome over SSH tunnel. macOS-as-server works but has rough edges. Codex sessions work if you swap agents. Repo: github.com/liamsysmind/roost. v0.1.0 tarballs at github.com/liamsysmind/roost/releases/tag/v0.1.0.