hivemux troubleshooting for Claude Code and tmux

Start with hivemux doctor, which checks dependencies, the tmux and Ghostty config blocks, the eleven Claude Code hooks and the running tmux server. Most other problems are fixed by restarting the sidebars (hivemux-sidebar respawn) or by fully quitting and reopening Ghostty; specific symptoms are below.

Quick commands

hivemux doctor                         # check dependencies and wiring
hivemux-panes list                     # panes hivemux will resume after reboot
tmux set -g @hivemux-anim off          # stop animations (to keep them off: menu → Settings)
tmux set -g @hivemux-fps 15            # fewer animation frames, less CPU (default 30)
hivemux-sidebar respawn                # restart every sidebar
touch ~/tmux_no_auto_restore           # skip restore on next launch

Restore after a reboot

Claude did not reopen after a reboot

Check the remembered list and the resume log. If the pane is not listed, the session started after the last save or was ended with /exit.

hivemux-panes list
cat ~/.local/share/hivemux/panes.log

busy in the log means the pane was not at a shell prompt, so it was skipped. pane missing means the layout changed and the pane no longer exists. In both cases, run claude -c in that folder to continue the latest conversation.

A window I just made is not in the restore list

Autosave runs every 5 minutes. After starting something important, save right away with prefix Ctrl+S.

Start clean once, without restoring

# skip restore on the next start; delete the file to turn it back on
touch ~/tmux_no_auto_restore
# restore the layout but do not resume Claude (while tmux is running)
tmux set-environment -g HIVEMUX_NO_RESUME 1

Sidebar

A Claude is missing from the sidebar, or its state updates late

The sidebar reads what the Claude Code hooks recorded, once a second. A Claude started before hivemux was installed appears after its next prompt or tool call. Claude running outside tmux is not shown.

# print the sidebar contents as text
hivemux-agents list

The sidebar is missing or has the wrong width

Press prefix b twice to recreate every sidebar. To change the width, use right-click → Settings → Sidebar width, or drag the grip bar on the sidebar’s right edge. The default is 32 columns. From the command line:

tmux set -g @hivemux-sidebar-width 40
hivemux-sidebar fix
# forget the saved width (back to 32)
rm ~/.local/share/hivemux/sidebar-width
# restart every sidebar if one is stuck or looks wrong
hivemux-sidebar respawn

If keyboard focus ends up in the sidebar, q or Esc returns it to the work pane.

A · window appears in the top window list while a popup is open

The rename, new project, settings, Option+O and Option+W popups open over a still copy of the screen. The · window is that copy; it goes away when the popup closes.

Turn off the animations

Right-click → Settings → Animation off stops them at once and stays off after restarts. To turn them off just for now, or use less CPU:

tmux set -g @hivemux-anim off
# or keep them with fewer frames (default 30)
tmux set -g @hivemux-fps 15

Keys

Option+number does nothing

Ghostty has to send Option as Alt. hivemux setup sets this, but a Ghostty that was open before needs a full quit and restart. Otherwise use prefix Space, or click a card.

Shift+Enter sends instead of adding a new line

The tmux server does not have the extended-keys setting yet. Reload the config or open Ghostty again. Ctrl+J always inserts a new line.

tmux source-file ~/.tmux.conf

Notifications

No notification when a task finishes

A task in the window you are looking at is not announced; notifications come when the terminal is in the background or you are in another window. Check that:

• Notifications is on in right-click → Settings.
• Ghostty (or your terminal) is allowed in System Settings → Notifications.
• Your terminal supports OSC 777 terminal notifications, as Ghostty does.
• The sidebars are not hidden: they send the notifications, so with prefix b hiding them, none come.

Remote tasks over mosh do not send notifications; use ssh for those. See Claude Code notifications.

Terminal and tmux

The claude command is not found inside tmux

The tmux server inherits the PATH of whatever started it. If it was started outside Ghostty, PATH may lack Claude. Stop the server and open Ghostty again.

tmux kill-server

Caution

tmux kill-server ends everything running in tmux.

A new Ghostty tab shows the same screen

A new tab attaches to a session no other tab shows, or creates a new one when all are shown. Use prefix s to move to the session you want.

Option+O does not open a file

Option+O lists only files that exist, newest first; relative paths are resolved against Claude’s working folder. On a screen attached from another Mac, VS Code and Cursor open the file over Remote-SSH, which needs the Remote - SSH extension on the Mac you connect from. ⌘+click works only where Claude prints the path as a link.

Phone and Remote Control

Sessions do not show up in the phone app

Remote Control needs a claude.ai subscription sign-in, not an API key. Sessions started before Remote Control was turned on do not connect by themselves; type /remote-control in them.

claude auth status

No button to start a new session on the phone

New sessions need a server-mode window. In that folder press prefix Shift+R. The first time it asks to enable Remote Control and to trust the folder; answer y to both.

Another Mac

mosh stops at “Nothing received from server on UDP port”

Allow incoming connections for mosh-server in the other Mac’s firewall. Both Macs need brew install mosh. More in Work from another Mac.

Undo the setup

hivemux uninstall removes only what hivemux added. Originals of the files setup changed are kept, with timestamps, in the backup folder. See Uninstall.

hivemux uninstall
ls -la ~/.local/share/hivemux/backups/