tmux-claude-notifier

A tmux plugin that highlights windows when a Claude Code session is waiting for your input.

The Problem

When running multiple Claude Code sessions across tmux windows, it's easy to lose track of which sessions need attention. You might miss when Claude has:

• Asked a question
• Finished a task and is waiting for the next instruction
• Requested permission approval

The Solution

This plugin provides visual indicators in your tmux status bar showing which windows have Claude sessions waiting for input.

Who Is This For?

This plugin is useful if you:

• Run Claude Code sessions in multiple tmux windows (10+)
• Frequently lose track of which sessions need your attention
• Want a visual indicator without switching windows to check

If you typically run a single Claude session, you probably don't need this.

Installation

Requirements

• tmux 3.0+
• Claude Code CLI with hooks support
• bash 4.0+

With TPM (recommended)

Add to your ~/.tmux.conf:

set -g @plugin 'mrf/tmux-claude-notifier'

Press prefix + I to install.

Manual Installation

git clone git@github.com:mrf/tmux-claude-notifier.git ~/.tmux/plugins/tmux-claude-notifier

Add to your ~/.tmux.conf:

run-shell ~/.tmux/plugins/tmux-claude-notifier/claude-notifier.tmux

Setup

1. Configure Claude Code Hooks

Add to your ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.tmux/plugins/tmux-claude-notifier/scripts/notify.sh working"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.tmux/plugins/tmux-claude-notifier/scripts/notify.sh waiting"
          }
        ]
      }
    ]
  }
}

2. Add Indicators to Your Status Bar

Add the status script to your window format in ~/.tmux.conf.

Important: If you use a tmux theme (like tmux-power, catppuccin, dracula, etc.), place these lines after the TPM initialization (run '~/.tmux/plugins/tpm/tpm') so they override the theme's window format.

# Simple: append indicator when waiting
set -g window-status-format "#I:#W#(~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh indicator #{window_id})"
set -g window-status-current-format "#I:#W#(~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh indicator #{window_id})"

For conditional styling (yellow background when waiting):

set -g window-status-format "#{?#{==:#(~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh waiting #{window_id}),1},#[bg=yellow]#[fg=black],}#I:#W#{?#{==:#(~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh waiting #{window_id}),1},*,}#[default]"

Example placement with TPM and a theme:

# Plugins and theme
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'wfxr/tmux-power'
set -g @tmux_power_theme 'everforest'

# Initialize TPM
run '~/.tmux/plugins/tpm/tpm'

# Claude notifier - AFTER TPM to override theme formats
run-shell ~/.tmux/plugins/tmux-claude-notifier/claude-notifier.tmux
set -g window-status-format "#I:#W#(~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh indicator #{window_id})"
set -g window-status-current-format "#I:#W#(~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh indicator #{window_id})"

3. Reload tmux

tmux source-file ~/.tmux.conf

Status Script Modes

The status.sh script supports three modes:

Mode	Output	Use Case
waiting	1 or 0	Conditional formatting
indicator	! or empty	Simple append to window name
status	waiting, working, or empty	Debugging/scripting

Configuration

# Change the indicator character (default: !)
set -g @claude_indicator_char '?'

# Change state directory (default: $XDG_RUNTIME_DIR/tmux-claude-state)
set -g @claude_state_dir '/tmp/my-claude-state'

Maintenance

Clean Up Stale State

If you close a pane while Claude is running, the state file may remain. Clean up orphaned states:

~/.tmux/plugins/tmux-claude-notifier/scripts/cleanup.sh

Or clear all state:

~/.tmux/plugins/tmux-claude-notifier/scripts/cleanup.sh --all

How It Works

1. Claude Code hooks call notify.sh when Claude starts working or stops
2. State files are created in /tmp/tmux-claude-state/ named by window and pane ID
3. tmux status bar calls status.sh to check if any pane in a window is waiting
4. Visual indicator appears when a window has a waiting Claude session

Claude Code → notify.sh → state file → status.sh → tmux status bar

Troubleshooting

Indicator not showing

1. Check hooks are configured: cat ~/.claude/settings.json
2. Verify state files exist: ls /tmp/tmux-claude-state/
3. Test status script: ~/.tmux/plugins/tmux-claude-notifier/scripts/status.sh waiting @1

Stale indicators

Run cleanup: ~/.tmux/plugins/tmux-claude-notifier/scripts/cleanup.sh

Not working outside tmux

The scripts silently exit when $TMUX is not set. This is intentional.

Security

State files are stored in /tmp/tmux-claude-state/ (or $XDG_RUNTIME_DIR/tmux-claude-state/). The directory is created with mode 700 (user-only access). State files contain only the strings "working" or "waiting" - no sensitive data.

Note: If the state directory is created by another process before first use, it may have different permissions. The plugin does not contain sensitive data, but if this concerns you, you can set a custom directory:

set -g @claude_state_dir "$HOME/.local/state/tmux-claude-state"

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Run shellcheck on all scripts
4. Submit a pull request