tmux-claude

Show Claude Code session status in your tmux status line and quickly switch between sessions with an fzf popup.

Why

If you use tmux sessions per project, windows per repo, and panes for neovim, Claude Code, etc., you quickly lose track of what your Claude sessions are doing. Which one finished? Which one is waiting for permission? With multiple projects running in parallel, constantly switching panes just to check status is a drag. This plugin puts all that info in your status bar so you always know at a glance.

Status Icons

Icon	Status	Meaning
🚀	starting	Session launching
⏳	thinking	Processing prompt
🔧	tool	Running a tool
💤	idle	Waiting for user input
⌨️	input	Requesting user input
🔐	permission	Waiting for permission
📦	compacting	Compacting context
❌	error	API/turn error

Each session shows as <icon> <directory>, e.g. ⏳ my-project | 💤 other-project.

Requirements

• tmux >= 3.0
• Claude Code
• jq
• fzf (optional, for the session switcher popup)

Installation

With TPM

Add to your tmux.conf:

set -g @plugin 'smilovanovic/tmux-claude'

Then press prefix + I to install.

Note: If you use a theme plugin (e.g. tmux-gruvbox), list tmux-claude after the theme in your plugin list. TPM loads plugins in order, and the theme must build the status line before this plugin can replace #{claude_status} in it. Otherwise the placeholder will remain as literal text.

Manual

Clone the repo:

git clone https://github.com/smilovanovic/tmux-claude.git ~/path/to/tmux-claude

Add to your tmux.conf:

run '~/path/to/tmux-claude/claude.tmux'

Usage

Add #{claude_status} to your status line config. The plugin replaces it with the actual status output at load time.

Important: The plugin must run after your theme plugin so it can replace #{claude_status} in the final status string.

Plain tmux

set -g status-right '#{claude_status} | %H:%M'

run '~/path/to/tmux-claude/claude.tmux'

With tmux-gruvbox

set -g @plugin 'egel/tmux-gruvbox'
set -g @tmux-gruvbox 'dark256'
set -g @tmux-gruvbox-right-status-x '#{claude_status} | %d.%m.%Y'

run '~/.config/tmux/plugins/tpm/tpm'

# Must be after TPM so the theme has already set status-right
run '~/path/to/tmux-claude/claude.tmux'

With other themes

Put #{claude_status} in whichever status option your theme uses, then ensure claude.tmux runs after the theme.

Session Switcher Popup

Press prefix + f to open an fzf popup listing all active Claude Code sessions.

The left side shows each session's status icon, working directory, and tmux pane location. The right side shows a live preview of the pane contents. Select a session to switch to its pane.

Sessions not running inside a tmux pane are shown as [detached].

Press ctrl-x inside the popup to kill the pane of the currently selected session. The list refreshes automatically after the pane is killed.

To change the key bindings:

set -g @claude-popup-key 'C-f'
set -g @claude-popup-kill-key 'ctrl-k'

The kill key value uses fzf key notation (e.g. ctrl-x, ctrl-k, alt-d).

How it works

The plugin has two parts:

1. Hook handler (scripts/hook.sh) — Registered as a Claude Code hook for all status-relevant events. Writes the current status to ~/.claude/sessions/<PID>.status.

2. Status script (scripts/status.sh) — Called by tmux on each status refresh. Reads session files, verifies PIDs are alive, and outputs formatted status.

3. Session switcher (scripts/popup.sh) — Opened via prefix + f. Lists active sessions, maps each Claude PID to its tmux pane by walking the process tree, and uses fzf with a pane preview to let you switch between sessions.

Hooks are automatically added to ~/.claude/settings.json when the plugin loads. No manual hook configuration needed.

Robustness

• No stale state — status.sh verifies PIDs on every call. Dead sessions are cleaned up automatically.
• Crash-safe — If Claude crashes without firing SessionEnd, the dead PID is detected on the next status refresh.
• Idempotent — Running install_hooks.sh multiple times won't duplicate hook entries.

Uninstall

After removing the plugin from tmux.conf, clean up the Claude Code hooks:

~/.config/tmux/plugins/tmux-claude/scripts/uninstall_hooks.sh

Or manually remove the tmux-claude entries from ~/.claude/settings.json.

License

MIT