tmux-claude
bezlant/tmux-claude
Integração tmux para sessões Claude Code com persistência e nomenclatura automática
Ver no GitHubPlugin tmux que integra sessões do Claude Code e Codex com gerenciamento persistente. Oferece nomenclatura estável de sessões baseada na janela tmux e sobrevive a reinicializações via integração com tmux-resurrect.
Instalação
npx convez-ai bezlant/tmux-claude1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter sessões Claude Code entre reinicializações do servidor tmux
- Organizar múltiplas sessões Claude por nome de janela tmux
- Automatizar setup de ambiente para equipes usando Claude Code agents
Veredito

Solução especializada para quem usa Claude Code dentro de tmux e precisa de persistência entre reinicializações. Requer conhecimento de tmux, hooks e shell scripting; valor agregado é alto para esse nicho específico.
README
A tradução para o português deste README ainda está na fila.
tmux-claude
tmux plugin for Claude Code and Codex session management.
Two features:
- Stable naming — starting Claude in a pane creates a fresh session with a tmux-derived name, with explicit opt-in resume
- Save/restore — survives tmux server restart (reboot) via tmux-resurrect integration
Requirements
- tmux >= 3.2
- TPM
- tmux-resurrect (for save/restore)
- python3 (for session lookup)
Install
set -g @plugin 'bezlant/tmux-claude'
prefix + I to install.
Setup
1. SessionStart hooks (required for save/restore)
These hooks write session IDs to tmux pane variables so the plugin can map panes to sessions.
Claude Code — add to ~/.claude/settings.json:
{
"hooks": {
"SessionStart": [{
"hooks": [{
"type": "command",
"command": "bash ~/.config/tmux/plugins/tmux-claude/scripts/claude-session-hook.sh"
}]
}]
}
}
Codex — add to ~/.codex/hooks.json:
{
"hooks": {
"SessionStart": [{
"hooks": [{
"type": "command",
"command": "bash ~/.config/tmux/plugins/tmux-claude/scripts/codex-session-hook.sh"
}]
}]
}
}
2. Shell wrapper (stable naming)
The plugin auto-installs the fish wrapper on prefix + I. For other shells:
# Bash (add to ~/.bashrc)
source ~/.config/tmux/plugins/tmux-claude/shell/claude.bash
# Zsh (add to ~/.zshrc)
source ~/.config/tmux/plugins/tmux-claude/shell/claude.zsh
To disable fish auto-install:
set -g @tmux-claude-auto-install-wrapper off
Features
Stable Claude Naming
Each pane gets a stable session name derived from its tmux window name:
- Single-pane window
redbot→ session nameredbot - Multi-pane window
redbot, pane 2 → session nameredbot.2
When you type claude in a pane, the wrapper:
- Computes the session name from
#{window_name}and#{pane_index} - Passes
--name <name> - Starts a fresh session with that name
To opt into tmux-name based resume, run claude --tmux-resume or set TMUX_CLAUDE_AUTO_RESUME=1. In that mode, the wrapper scans ~/.claude/projects/<encoded-path>/*.jsonl for a session whose customTitle matches and passes --resume <uuid> --name <name> when it finds one.
Bypass: passing --resume, --continue, --name, or -p explicitly skips the wrapper logic.
/clear behavior: /clear keeps the same session ID, but a plain claude launch is fresh by default. Use claude --tmux-resume only when you intentionally want the named cleared session back.
Save/restore
Survives tmux server restart (reboot). Requires tmux-resurrect and SessionStart hooks.
How it works:
prefix + S(resurrect save) triggers a post-save hook that records pane→session mappingsprefix + R(resurrect restore) triggers a post-restore hook that sends resume commands to each pane
Mapping format: claude-panes.txt lives in the configured @resurrect-dir and uses snapshot v2, an eight-column TSV format:
target tool sid sid_kind cwd original_cwd wname flags
If @resurrect-dir is not set, save/restore use ~/.tmux/resurrect. Legacy pipe-delimited snapshots are still readable during restore.
Restore writes restore.log beside the snapshot with BEGIN, OK, WARN, SKIP, and END lines so failed or degraded panes can be inspected after restore.
Tools restored:
claude→ resumes with session UUIDcodex→ resumes with session UUIDnvim→ reopens nvimjust→ re-runs the recipe
Safety:
- Atomic save (temp file + mv) — partial saves can't corrupt the mapping
- Zero-pane enumeration preserves the previous mapping instead of clobbering
- Hooks stamp both session IDs and agent PIDs, then clear stale pane variables when a pane switches between Claude and Codex
- Stale PIDs are tolerated when the saved UUID still has a valid local Claude/Codex artifact; those rows are marked
pid_mismatch_trusted - Concurrent restore runs are skipped with
restore_already_runninginrestore.log
Manual usage:
# Save current state
bash ~/.config/tmux/plugins/tmux-claude/scripts/session-save.sh
# Preview what restore would do
bash ~/.config/tmux/plugins/tmux-claude/scripts/session-restore.sh --dry-run
# Audit every live tmux pane for restore readiness
bash ~/.config/tmux/plugins/tmux-claude/scripts/session-audit.sh
# Restore
bash ~/.config/tmux/plugins/tmux-claude/scripts/session-restore.sh
session-audit.sh exits non-zero when a live Claude/Codex pane would only restore as a picker or has an invalid UUID artifact.
Post-reboot attach helper
For fish users, the plugin can install a tres helper:
tres
tres starts a temporary bootstrap tmux server when needed, reads the saved tmux-resurrect session name from ~/.config/tmux/resurrect/last, waits for the restored window count to stabilize, then attaches to that restored session. It falls back to session 0 when no snapshot is available.
If @resurrect-dir is set, tres reads last from that configured directory. If you already have a custom ~/.config/fish/functions/tres.fish, the plugin will not overwrite it; copy shell/tres.fish manually if you want the plugin helper.
Configuration
| Option | Default | Description |
|---|---|---|
@tmux-claude-auto-install-wrapper | on | Auto-install fish wrapper to ~/.config/fish/functions/ |
TMUX_CLAUDE_MAX_SAVES | 20 | Max resurrect save files to keep |
Override max saves:
set-environment -g TMUX_CLAUDE_MAX_SAVES 30
How it works (internals)
Claude Code stores sessions as JSONL files in ~/.claude/projects/<encoded-path>/. The path is encoded by replacing / and . with - (e.g., /Users/foo/my.project → -Users-foo-my-project).
Each JSONL file starts with a {"type":"custom-title","customTitle":"..."} entry set at creation time. The optional --tmux-resume lookup scans these files (sorted newest-first by mtime) and returns the first UUID whose customTitle matches the computed pane name.
This avoids:
--continue(resumes most recent session in the directory regardless of name — causes cross-pane hijacking)- Matching on
agentName(can be overwritten by previous--nameflags, leaving contaminated metadata)
License
MIT