Alien Desk

Guides

How to keep track of Claude Code sessions in tmux

Running Claude Code in tmux windows? Mark the window that is waiting for you with a hook, and see every session at a glance.

tmux is a good home for long Claude Code sessions: they keep running when you close the terminal, and you can split and switch quickly. The catch is the same as with tabs. A window where Claude is waiting for permission looks just like one that is still working.

Mark the waiting window with a hook

Hooks run inside the tmux pane where Claude Code is running, so they can talk to tmux. This renames the window when Claude needs you, and lets tmux name it again once you answer. Add it to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "[ -z \"$TMUX_PANE\" ] || tmux rename-window -t \"$TMUX_PANE\" '● needs you'" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "[ -z \"$TMUX_PANE\" ] || tmux set-window-option -t \"$TMUX_PANE\" automatic-rename on" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          { "type": "command", "command": "[ -z \"$TMUX_PANE\" ] || tmux set-window-option -t \"$TMUX_PANE\" automatic-rename on" }
        ]
      }
    ]
  }
}

Now the tmux status bar shows which window is waiting. If you name your windows yourself, put your own name back instead of turning automatic-rename on. Outside tmux the hooks do nothing.

This works per window, so with several panes in one window you still have to look for the right one.

See every session, in tmux or not

Alien Desk lists every Claude Code session in a small Mac panel, including the ones inside tmux: which needs you, which is working and which is done. Click a row and the terminal window with that session comes to the front. This part is free.

More guides