convez.ai
AgenteDevOps & InfraestruturaAvançado
bezlant

tmux-claude

bezlant/tmux-claude

Integração tmux para sessões Claude Code com persistência e nomenclatura automática

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin 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-claude

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Stable naming — starting Claude in a pane creates a fresh session with a tmux-derived name, with explicit opt-in resume
  2. Save/restore — survives tmux server restart (reboot) via tmux-resurrect integration

Requirements

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 name redbot
  • Multi-pane window redbot, pane 2 → session name redbot.2

When you type claude in a pane, the wrapper:

  1. Computes the session name from #{window_name} and #{pane_index}
  2. Passes --name <name>
  3. 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:

  1. prefix + S (resurrect save) triggers a post-save hook that records pane→session mappings
  2. prefix + 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 UUID
  • codex → resumes with session UUID
  • nvim → reopens nvim
  • just → 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_running in restore.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

OptionDefaultDescription
@tmux-claude-auto-install-wrapperonAuto-install fish wrapper to ~/.config/fish/functions/
TMUX_CLAUDE_MAX_SAVES20Max 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 --name flags, leaving contaminated metadata)

License

MIT

Ver o original no GitHub

Bom para

Relacionados