How hivemux works with tmux and Claude Code hooks

hivemux works in layers: Claude Code hooks write each session’s id and state onto its tmux pane, the sidebar reads that state every second and draws the board, tmux keeps processes alive when the terminal closes, and tmux-resurrect restores layouts after a reboot while hivemux types claude --resume <id> in each pane. Everything runs on your Mac; there is no server.

The layers

Layer	Job
Ghostty	draws. Every window runs hivemux-attach, which attaches to tmux
tmux	keeps processes alive when the terminal closes
tmux-resurrect + continuum	saves layouts every 5 minutes, restores on first launch
Claude Code hooks	write session id and state onto the tmux pane (hivemux-hook)
sidebar	reads that state every second and draws the board (hivemux-sidebar-view)

Claude Code hooks

hivemux setup registers hivemux-hook in ~/.claude/settings.json for eleven Claude Code hook events:

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PermissionDenied, Notification, Stop, StopFailure, SessionEnd.

Each event records the session id, folder and state on the tmux pane where that Claude runs. Because the state lives on tmux panes, a Claude running outside tmux is not shown, and a Claude started before hivemux was installed appears after its next prompt or tool call.

Notifications

The sidebar sends a notification when a task needs input or finishes, except for the task you are looking at. It is sent as a terminal notification (OSC 777), so it shows in terminals that support it, such as Ghostty. With the sidebars hidden (prefix b), no notifications come. See Claude Code notifications.

What survives what

Event	tmux sessions and layout	Claude conversation
Close a Ghostty window	kept	keeps running
Quit Ghostty	kept	keeps running
Mac sleeps (lid closed)	kept	pauses, then continues
Reboot or crash	restored from the last save	resumed automatically
End with /exit or Ctrl+D	window stays	not resumed

Restore after a reboot

1. hivemux-attach: with no tmux server running, starts one with a temporary session.
2. tmux-resurrect: recreates sessions, windows, panes and folders from the last snapshot.
3. hivemux-panes restore: reads the saved pane-to-session list and, in each pane that sits at a shell prompt, changes to the original folder and types claude --resume <id>.
4. Claude Code: the conversation opens (and registers with Remote Control, if on).
5. hivemux-attach: attaches to the session you were last looking at.

Sessions you ended with /exit are not resumed. More in Resume Claude Code sessions.

Files hivemux touches

Path	What is there
~/.tmux.conf	the hivemux block: loads hivemux.tmux and, if chosen, the recommended keys
~/.config/ghostty/config	the hivemux block: attaches every Ghostty window to tmux through hivemux-attach
~/.claude/settings.json	eleven hivemux hooks and, if chosen, Remote Control for every session
~/.zshrc	git installs only: the hivemux bin folder on PATH
~/.local/share/hivemux/	plugins, the pane-to-session list (panes.tsv), the resume log (panes.log), sidebar width and settings, the bee office window, config backups
~/.local/share/tmux/resurrect/	tmux-resurrect layout snapshots

Config changes sit between # >>> hivemux >>> and # <<< hivemux <<< markers, and hivemux uninstall removes exactly those.

Privacy and network access

hivemux has no server and no telemetry. It runs on your Mac and reads Claude Code hook events and tmux state. Its only network requests are:

• fetching the latest Claude Code version when you update Claude (npm registry or Homebrew API)
• cloning or updating hivemux from GitHub, and, during setup, the tmux-resurrect and tmux-continuum plugins (unless you already have them in ~/.tmux/plugins)
• ssh or mosh to Macs you connect to yourself with hivemux connect

The bee office window talks to a small web server that listens only on 127.0.0.1.

For background on running Claude Code in tmux, see Claude Code and tmux.