Guía rápida de inicio de Tmux

Aprenda Tmux desde cero — el multiplexor de terminal con conceptos básicos, comandos frecuentes e integración profunda con Claude Code

Introducción

Adoption of tools like Tmux has surged, largely due to the agent team workflows found in command-line coding agent products like Claude Code.

Towards Data ScienceA beginner's guide to Tmux

Visitar

Si ha utilizado Agent Teams de Claude Code o desea ejecutar múltiples instancias de Claude simultáneamente, Tmux es prácticamente una herramienta indispensable. Le permite ejecutar múltiples sesiones en una sola ventana de terminal, las sesiones continúan ejecutándose en segundo plano incluso si cierra la terminal, y Claude puede generar y gestionar automáticamente múltiples Agents dentro de Tmux.

Este tutorial está diseñado específicamente para usuarios de Claude Code, cubriendo tanto los fundamentos de Tmux como los consejos de integración con Claude Code.

Comprender Tmux

Tmux (Terminal Multiplexer)

Un multiplexor de terminal que permite crear y gestionar múltiples sesiones de terminal en una sola ventana. Su característica principal es la persistencia de sesiones: incluso si se desconecta, las sesiones continúan ejecutándose y al reconectarse puede restaurar el estado anterior.

Fuente: Tmux WikiVisitar

Los tres conceptos fundamentales de Tmux:

┌─────────────────────────────────────────────────────────┐
│                    Session (Sesión)                      │
│  ┌─────────────────────────────────────────────────────┐│
│  │                 Window (Ventana)                     ││
│  │  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ ││
│  │  │   Pane 1     │  │   Pane 2     │  │  Pane 3   │ ││
│  │  │  (Claude 1)  │  │  (Claude 2)  │  │  (Logs)   │ ││
│  │  │              │  │              │  │           │ ││
│  │  │              │  │              │  │           │ ││
│  │  └──────────────┘  └──────────────┘  └───────────┘ ││
│  └─────────────────────────────────────────────────────┘│
│  Window 1: Development    Window 2: Testing             │
└─────────────────────────────────────────────────────────┘

Concepto	Analogía	Descripción
Session	Espacio de trabajo	Contenedor de nivel superior, continúa ejecutándose incluso si se desconecta
Window	Pestaña del navegador	Una sesión puede contener múltiples ventanas
Pane	Pantalla dividida	Una ventana puede dividirse en múltiples paneles

Instalación y fundamentos

Instalar Tmux

# macOS
brew install tmux

# Ubuntu/Debian/WSL
sudo apt-get install tmux

# CentOS/RHEL
sudo yum install tmux

Verificar la instalación:

tmux -V
# Salida similar a: tmux 3.6a

Tecla de prefijo

Todos los comandos de Tmux comienzan con una tecla de prefijo, que por defecto es Ctrl+B.

Método para ingresar comandos:

Presione Ctrl+B (sin soltar)
Después de soltar, presione la tecla del comando

Por ejemplo, dividir ventana: Ctrl+B y luego presione %

Referencia rápida de comandos

Gestión de sesiones

Comando	Descripción
`tmux`	Crear nueva sesión
`tmux new -s name`	Crear sesión con nombre
`tmux ls`	Listar todas las sesiones
`tmux attach -t name`	Conectarse a una sesión
`tmux kill-session -t name`	Cerrar una sesión
`Ctrl+B d`	Desconectar la sesión actual (se ejecuta en segundo plano)

Gestión de ventanas

Atajo	Descripción
`Ctrl+B c`	Crear nueva ventana
`Ctrl+B n`	Siguiente ventana
`Ctrl+B p`	Ventana anterior
`Ctrl+B 0-9`	Cambiar a la ventana especificada
`Ctrl+B ,`	Renombrar la ventana actual
`Ctrl+B &`	Cerrar la ventana actual

Gestión de paneles

Atajo	Descripción
`Ctrl+B %`	División vertical (izquierda-derecha)
`Ctrl+B "`	División horizontal (arriba-abajo)
`Ctrl+B teclas de dirección`	Moverse entre paneles
`Ctrl+B x`	Cerrar el panel actual
`Ctrl+B z`	Maximizar/restaurar panel
`Ctrl+B {`	Mover panel hacia la izquierda
`Ctrl+B }`	Mover panel hacia la derecha

Otros comandos frecuentes

Atajo	Descripción
`Ctrl+B [`	Entrar en modo copia (permite desplazamiento)
`q`	Salir del modo copia
`Ctrl+B ?`	Mostrar todos los atajos

Integración con Claude Code

Por qué Claude Code necesita Tmux

Modo split-pane de Agent Teams: cada Teammate se muestra en un panel independiente
Ejecución en segundo plano: las tareas continúan ejecutándose incluso si cierra la terminal
Persistencia de sesiones: restaura el contexto completo al reconectarse después de una desconexión
Gestión de múltiples instancias: ejecute múltiples sesiones de Claude simultáneamente

Uso básico: ejecutar Claude en segundo plano

# Iniciar Claude en tmux
tmux new -s claude-work
claude

# Desconectar la sesión (Claude continúa ejecutándose)
# Ctrl+B d

# Reconectarse más tarde
tmux attach -t claude-work

Usar el parámetro --tmux

Claude Code tiene soporte nativo para la integración con Tmux:

# Iniciar Claude en una nueva sesión de tmux
claude --tmux

# Usar junto con worktree
claude -w feature-auth --tmux

Esto automáticamente:

Crea una nueva sesión de tmux
Inicia Claude Code en ella
Nombra la sesión como claude-{ID aleatorio}

Modo Tmux de Agent Teams

Agent Teams puede usar el modo de visualización split-pane, donde cada Teammate se ejecuta en un panel independiente:

// settings.json
{
  "teammateMode": "tmux"
}

O mediante la línea de comandos:

claude --teammate-mode tmux

Resultado:

┌─────────────────────────────────────────────────────────┐
│                    Team Lead                             │
├─────────────────┬─────────────────┬─────────────────────┤
│   Teammate 1    │   Teammate 2    │    Teammate 3       │
│   Security      │   Performance   │    Testing          │
│                 │                 │                     │
└─────────────────┴─────────────────┴─────────────────────┘

Configuración práctica

~/.tmux.conf recomendado

Cree o edite ~/.tmux.conf:

# Usar Ctrl+A como tecla de prefijo (más fácil de presionar)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Habilitar soporte de ratón
set -g mouse on

# Aumentar el búfer de historial (Claude genera mucha salida)
set -g history-limit 50000

# Navegación de paneles estilo vim
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Atajos de división más intuitivos
bind | split-window -h
bind - split-window -v

# Recarga rápida de configuración
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Soporte de 256 colores
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",*256col*:Tc"

# Numeración de ventanas desde 1 (el 0 está muy lejos)
set -g base-index 1
setw -g pane-base-index 1

# Optimización de la barra de estado
set -g status-position bottom
set -g status-left-length 40
set -g status-right-length 60

Recargar configuración:

tmux source-file ~/.tmux.conf

Configuración dedicada para Claude Code

Configuración optimizada para Claude Code:

# Atajo de ventana emergente para sesión de Claude
bind -r y run-shell '\
  SESSION="claude-$(echo #{pane_current_path} | md5sum | cut -c1-8)"; \
  tmux has-session -t "$SESSION" 2>/dev/null || \
  tmux new-session -d -s "$SESSION" -c "#{pane_current_path}" "claude"; \
  tmux display-popup -w80% -h80% -E "tmux attach-session -t $SESSION"'

El efecto de esta configuración:

Presione Ctrl+A y para abrir la ventana emergente de Claude
Cada directorio tiene una sesión independiente de Claude
La sesión continúa ejecutándose después de cerrar la ventana emergente
Al reabrirla, se restaura la conversación anterior

Flujos de trabajo comunes

Flujo de trabajo 1: Múltiples proyectos en paralelo

# Crear una sesión independiente para cada proyecto
tmux new -s project-a
# Iniciar Claude dentro
claude -w feature-x

# Desconectar y crear otra sesión
# Ctrl+B d
tmux new -s project-b
claude -w bugfix-y

# Cambiar entre sesiones
tmux switch -t project-a
tmux switch -t project-b

# O listar todas las sesiones para seleccionar
# Ctrl+B s

Flujo de trabajo 2: Panel de desarrollo

Crear un entorno de desarrollo con múltiples paneles:

# Crear sesión
tmux new -s dev

# Dividir en tres paneles
# Ctrl+B % (división vertical)
# Ctrl+B " (división horizontal del lado derecho)

# Disposición de paneles:
# ┌───────────┬───────────┐
# │  Claude   │   Logs    │
# │           ├───────────┤
# │           │   Tests   │
# └───────────┴───────────┘

# Ejecutar Claude en el primer panel
claude

# Cambiar al segundo panel (Ctrl+B flecha derecha)
tail -f logs/app.log

# Cambiar al tercer panel
npm test -- --watch

Flujo de trabajo 3: Desarrollo remoto

La característica más poderosa de Tmux es la persistencia de sesiones, especialmente adecuada para desarrollo remoto por SSH:

# Conectarse al servidor remoto
ssh user@server

# Crear sesión de tmux
tmux new -s remote-claude

# Iniciar Claude
claude

# Desconectar SSH (Claude continúa ejecutándose)
# Ctrl+B d
exit

# Reconectarse más tarde
ssh user@server
tmux attach -t remote-claude
# La sesión de Claude se restaura completamente

Flujo de trabajo 4: Monitoreo de Agent Teams

Usar tmux para monitorear todos los Teammates de Agent Teams:

# Iniciar Claude en modo tmux
claude --teammate-mode tmux

# Crear Agent Team
# "Crea un agent team para revisar el código..."

# En este momento la pantalla se divide automáticamente, un panel por Teammate
# Puede hacer clic en diferentes paneles para comunicarse directamente con el Teammate correspondiente

Solución de problemas

Problemas comunes

Problema	Solución
Colores que se muestran incorrectamente	Asegúrese de que `TERM=xterm-256color`
El ratón no funciona	Agregue `set -g mouse on` a la configuración
Problemas de copiar y pegar	Use `Enter` para copiar en modo copia
La sesión desapareció	Verifique `tmux ls`, posiblemente fue un reinicio del sistema

Limpiar sesiones huérfanas

Claude Code a veces deja sesiones de tmux sin limpiar:

# Listar todas las sesiones
tmux ls

# Terminar una sesión específica
tmux kill-session -t session-name

# Terminar todas las sesiones (¡use con precaución!)
tmux kill-server

Usuarios de iTerm2

Si utiliza iTerm2 en macOS, puede usar su integración nativa:

# Usar el modo de integración tmux de iTerm2
tmux -CC

# O en Claude Code
claude --teammate-mode tmux

iTerm2 convierte automáticamente los paneles de tmux en pestañas y pantallas divididas nativas.

Mi experiencia de uso

Cuándo usar Tmux

Escenario	¿Se necesita Tmux?
Conversación simple y única con Claude	No es necesario
Tareas de larga duración	Necesario
Agent Teams	Altamente recomendado
Desarrollo remoto	Imprescindible
Múltiples proyectos en paralelo	Recomendado

Configuración mínima

Si no desea complicarse con la configuración, solo necesita recordar estos comandos:

# Crear sesión
tmux new -s work

# Desconectar (ejecutar en segundo plano)
Ctrl+B d

# Reconectarse
tmux attach -t work

# Dividir paneles
Ctrl+B %    # División izquierda-derecha
Ctrl+B "    # División arriba-abajo

# Cambiar entre paneles
Ctrl+B teclas de dirección

Mejores combinaciones con Claude Code

Worktree + Tmux: cada worktree en una sesión de tmux independiente
```
claude -w feature-auth --tmux
```
Agent Teams + Tmux: gestión visual de todos los Teammates
```
claude --teammate-mode tmux
```

Tareas largas + desconexión: inicie y desconéctese, vuelva más tarde a verificar

# Iniciar
tmux new -s migration
claude
# "Ejecutar migración de base de datos..."
# Ctrl+B d

# Varias horas después
tmux attach -t migration

Conclusión

Tmux es una herramienta clave para el uso eficiente de Claude Code, especialmente en los siguientes escenarios:

Punto clave	Descripción
Persistencia	Las sesiones no se pierden al desconectarse
Paralelismo	Gestione múltiples instancias de Claude simultáneamente
Visualización	Visualización split-pane de Agent Teams

Solo tres comandos básicos para comenzar:

tmux new -s name crear sesión
Ctrl+B d desconectar sesión
tmux attach -t name reconectarse

Lecturas relacionadas:

Guía completa de Claude Agent Teams -- Agent Teams necesita Tmux para el modo split-pane
Guía completa de Claude Worktree -- Worktree puede combinarse con Tmux para ejecución en segundo plano

Materiales de referencia:

Tutoriales en video:

Tmux Basics Tutorial -- Fundamentos de Tmux
Tmux + Claude Code Workflow -- Flujo de trabajo de integración con Claude Code
Advanced Tmux Configuration -- Técnicas de configuración avanzada