tools-only tmux + Claude Code Workflow Reference
Quick reference for tmux session management with Claude Code.
Session Picker (cc-pick)
Interactive fzf-based session picker that combines Claude Code history with tmux status:
cc-pick # Launch interactive picker
cc-pick 30 # Show last 30 sessions
Features:
- Shows Claude sessions with category tags (🐛 bug, ✨ feature, etc.)
- Indicates tmux status: 🟢 claude running, 🟡 tmux idle, ⚪ no tmux
- Preview pane with session details
- Direct resume into tmux
Keybindings:
| Key | Action |
|---|---|
Enter |
Resume session in tmux (creates/attaches + runs claude --resume) |
Ctrl-O |
Open project in VSCode/Cursor (copies resume command) |
Ctrl-T |
Attach to tmux session only (no Claude resume) |
Ctrl-Y |
Copy session ID to clipboard |
Esc |
Cancel |
CLI Tools (~/.local/bin/)
| Command | Usage | Description |
|---|---|---|
cc |
cc [name] |
Create/attach tmux session with Claude running |
ccls |
ccls |
List sessions with status (🟢 claude / ⚪ idle) |
ccpick |
ccpick |
Interactive fzf picker with live preview |
cckill |
cckill |
Kill only idle sessions (preserves active Claude) |
ccnew |
ccnew <path> [--ghostty|--vscode|--cursor] [--model <m>] |
Open new Claude session in project dir |
ccresume |
ccresume <session-id> [--ghostty|--vscode|--cursor] [--project <path>] |
Resume session in Ghostty/VS Code/Cursor |
Shell Aliases (.zshrc)
| Alias | Expands To | Description |
|---|---|---|
t |
tmux |
Quick tmux access |
ta |
tmux attach -t |
Attach to named session |
tn |
tmux new -s |
Create new named session |
tls |
tmux list-sessions |
List all sessions |
tk |
tmux kill-session -t |
Kill named session |
tmux Keybindings
Prefix: Ctrl+A (not default Ctrl+B, to avoid Claude Code conflict)
Pane Mode (Ctrl+P, then...)
| Key | Action |
|---|---|
h |
Move left |
j |
Move down |
k |
Move up |
l |
Move right |
s |
Split horizontal (pane below) |
v |
Split vertical (pane right) |
x |
Kill pane |
Tab Mode (Ctrl+T, then...)
| Key | Action |
|---|---|
n |
New window |
h |
Previous window |
l |
Next window |
x |
Kill window |
r |
Rename window |
Popup Commands (prefix + key)
| Key | Action |
|---|---|
s |
Session picker (fzf popup) |
g |
Lazygit popup (90% screen) |
Terminal Title Hook
When enabled, terminal titles show Claude status:
- 🔴
project-name— Claude is thinking - 🟢
project-name— Ready for input
Also plays sound and sends desktop notification on completion.
Crash Recovery
tmux sessions survive VSCode/Cursor crashes:
# After crash, just reattach
ccpick # Interactive picker
# or
ta session-name # Direct attach
Common Workflows
Start new Claude session
cd ~/my-project
cc # Creates session named "my-project" with Claude (tmux)
# Or open directly in Ghostty/VS Code/Cursor:
ccnew ~/my-project # Ghostty tab (default)
ccnew ~/my-project --vscode # VS Code terminal
ccnew ~/my-project --model sonnet # With model override
Check what's running
ccls
# Output:
# my-project 🟢 claude (Jan 18 12:30)
# other-project ⚪ idle (Jan 17 09:00)
Clean up old sessions
cckill # Offers to kill idle sessions only
Quick session switch
# Inside tmux
Ctrl+A, s # Opens fzf session picker popup
Configuration Files
- tmux config:
~/.tmux.conf - Claude hooks:
~/.claude/settings.json - Terminal title hook:
~/.claude/hooks/terminal-title.sh - CLI tools:
~/.local/bin/cc,ccls,ccpick,cckill,ccnew,ccresume - Session scripts:
~/.claude/scripts/cc-sessions-fzf.sh,cc-sessions.sh - New session launcher:
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh
Session History Scripts (~/.claude/scripts/)
| Script | Usage | Description |
|---|---|---|
cc-sessions-fzf.sh |
cc-pick |
Interactive fzf picker with tmux integration |
cc-sessions.sh |
cc-sessions [n] |
List last n sessions with categories |
Reload Config
tmux source-file ~/.tmux.conf
Troubleshooting
fzf picker not showing data
# Check if history exists
ls -la ~/.claude/history.jsonl
# Test data extraction
jq -s 'length' ~/.claude/history.jsonl
tmux session not detected
# List tmux sessions
tmux list-sessions
# Check session paths
tmux list-sessions -F "#{session_name}: #{pane_current_path}"
Terminal title not updating
- Verify hooks in
~/.claude/settings.json - Check tmux passthrough:
set -g set-titles onin~/.tmux.conf - Restart Claude for hooks to take effect