# hivemux troubleshooting for Claude Code and tmux

Fix common hivemux problems: Claude not resumed after reboot, missing sidebar, no notifications, Option+number not working, claude not found in tmux.

Source: https://hivemux.dev/docs/troubleshooting/

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

```sh
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`.

```sh
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

```sh
# 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.

```sh
# 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:

```sh
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:

```sh
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.

```sh
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](/guides/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.

```sh
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.

```sh
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](/docs/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](/docs/uninstall/).

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