tmux-claude-code

A bash-only tmux plugin for browsing, tracking, and resuming Claude Code sessions.

It combines two sources of truth:

• live tmux panes currently running claude
• the local Claude Code session transcripts under ~/.claude/projects

That gives you one session browser for:

• sessions already open in a tmux pane (active)
• sessions touched recently
• older idle sessions

Selecting a session either jumps to the pane that already has it open, or resumes it with claude --resume <id> in a new tmux window or split pane.

Features

• TPM-compatible plugin entrypoint
• popup session browser
• jump to an already attached tmux pane
• resume any stored session in a new tmux window or split pane
• status segment for status-left or status-right
• fzf support when available (numbered fallback otherwise)
• rich titles (session summary / first prompt) via jq, with a graceful no-jq fallback
• shows git branch and project directory per session

Requirements

• tmux >= 3.2 (display-popup is required)
• bash
• claude CLI available in PATH
• optional: jq for rich session titles and message counts
• optional: fzf for fuzzy popup search

Install with TPM

Add this to your ~/.tmux.conf:

set -g @plugin 'CoderMungan/tmux-claude-code'
run '~/.tmux/plugins/tpm/tpm'

Install with prefix + I. Update later with prefix + U.

Manual install

git clone https://github.com/CoderMungan/tmux-claude-code.git ~/.tmux/plugins/tmux-claude-code
chmod +x ~/.tmux/plugins/tmux-claude-code/claude-code.tmux

run-shell '~/.tmux/plugins/tmux-claude-code/claude-code.tmux'

Then reload tmux:

source-file ~/.tmux.conf

Default key binding

• prefix + C opens the popup browser

Change it with:

set -g @claude-key 'K'

Configuration

set -g @claude-key 'C'
set -g @claude-status-position 'right'
set -g @claude-popup-width '90%'
set -g @claude-popup-height '80%'
set -g @claude-recent-minutes '240'
set -g @claude-max-sessions '50'
set -g @claude-projects-dir "$HOME/.claude/projects"
set -g @claude-resume-target 'window'
set -g @claude-status-colors 'true'

Options

Option	Default	Description
@claude-key	C	Prefix binding that opens the popup
@claude-status-position	right	Documentation-only hint for where you place the status segment
@claude-popup-width	90%	Popup width
@claude-popup-height	80%	Popup height
@claude-recent-minutes	240	Sessions updated within this window are recent; older ones are idle
@claude-max-sessions	50	Max sessions pulled from disk
@claude-projects-dir	~/.claude/projects	Path to the Claude Code projects directory
@claude-resume-target	window	Resume into a new window or a split pane
@claude-status-colors	true	Enable tmux color escapes in the status segment

Status line integration

The plugin does not overwrite your existing status line. Add the segment wherever you want:

set -g status-right '#(~/.tmux/plugins/tmux-claude-code/scripts/claude-status.sh) | %H:%M'

Example output:

CC:5 A:1 R:2 I:2

Where:

• CC = total sessions shown
• A = active (open in a live tmux pane)
• R = recent
• I = idle

Status meanings

• active: a live tmux pane is running claude in this session's directory
• recent: updated within @claude-recent-minutes
• idle: older than the recent window

Popup workflow

When you open the popup:

• if fzf is installed, you get fuzzy search
• otherwise, you get a numbered fallback menu
• each row shows a colored dot, status, session title, project directory, and git branch

Popup status colors:

• green active = open in a live tmux pane
• yellow recent = touched recently
• gray idle = older

Selecting a session does one of two things:

1. if that session is already open in a tmux pane, the plugin jumps to that pane
2. otherwise, it runs claude --resume <session-id> in a new tmux window or split pane, in the session's directory

Session detection

Claude Code side

Claude Code stores each session as a JSONL transcript:

~/.claude/projects/<encoded-project-path>/<session-uuid>.jsonl

The plugin reads, per transcript:

• session-uuid (the file name)
• cwd (the session's working directory)
• gitBranch
• last activity time (file mtime)
• title: the session summary line, else the first real user prompt, else Untitled
• user + assistant message count

Titles and counts use jq when present. Without jq, the plugin still lists and resumes sessions; titles degrade to the raw summary text or Untitled.

tmux side

The plugin scans tmux panes using:

• #{pane_current_command}
• #{pane_pid} + ps -p <pid> -o command=
• #{pane_current_path}
• #{pane_title}

A pane running claude is matched back to the most recently updated stored session in the same directory and marked active. A live pane with no stored match still appears as a tmux-only active row.

CLI helpers

• scripts/claude-status.sh — prints the status segment
• scripts/claude-list.sh — prints tab-separated session records
• scripts/claude-popup.sh — opens the popup browser

The list script prints tab-separated records with these fields:

source  session_id  title  directory  path  status  updated_epoch  age_minutes  attached  pane_id  window_id  tmux_session_id  branch  msg_count

Validation

make validate
make smoke

Troubleshooting

If prefix + C does nothing:

1. confirm tmux version is >= 3.2 (tmux -V)
2. confirm the plugin path exists
3. reload tmux config
4. for TPM installs, run prefix + U

Useful checks:

tmux list-keys | grep -E 'prefix\s+C\b'
~/.tmux/plugins/tmux-claude-code/scripts/claude-status.sh

Limitations

• matching live tmux panes to stored sessions is best-effort (by directory), since the claude process does not expose its session id on the command line
• Claude Code transcript format changes may require plugin updates

Privacy

This plugin reads local tmux metadata and local Claude Code session metadata only. It does not send data anywhere.

License

MIT