Cómo organizar una docena de sesiones de Claude Code en ejecución en tmux

Cuando lanzas Claude Code en la terminal para hacer algunas ediciones rápidas, todo se ve ordenado. Ejecutas el comando, le das una tarea, esperas la respuesta, lo cierras. Los problemas comienzan cuando mantienes cuatro o cinco proyectos abiertos al mismo tiempo. En un repositorio, el agente está refactorizando pruebas, en otro está escribiendo una migración de base de datos, y en un tercero está ejecutando una compilación.

En media hora, la terminal se convierte en un laberinto. No queda claro dónde el agente está esperando confirmación del comando, dónde todavía está ejecutando scripts, y dónde terminó hace mucho tiempo y simplemente está inactivo. Tienes que recorrer manualmente las ventanas de tmux, perdiendo tiempo verificando estados.

Tak Matsuyama, autor del blog devas.life y de varias utilidades populares para Neovim y tmux, presentó una solución a este problema. Su plugin tmux-claude-session-manager transforma ventanas de terminal dispersas con agentes en una lista ordenada con cambio rápido.

Qué hace el plugin

En esencia, es un administrador de tareas para Claude Code dentro de tmux. La herramienta combina la interfaz de fzf, el mecanismo de popup integrado de tmux y la API interna de Claude Code.

Presionas una combinación de teclas y ves una ventana flotante con una lista de todas las sesiones en ejecución. Cada proceso muestra su estado de inmediato:

• working (el agente está ocupado generando o ejecutando comandos);
• waiting (se requiere entrada o confirmación del usuario);
• idle (la sesión está inactiva);
• tiempo desde la última actividad del agente.

Los agentes que necesitan tu atención se mueven automáticamente a la parte superior de la lista. Se muestra una vista previa en vivo de la pantalla a través de capture-pane junto a ella. Puedes ver inmediatamente qué pregunta confundió al asistente, sin siquiera cambiar a la sesión en sí.

Al presionar Enter accedes directamente al contexto de la ventana deseada y abres la sesión en un marco emergente. ¿Terminaste el diálogo o el agente completó su trabajo? Presiona la combinación de teclas para eliminar el proceso y la sesión se cierra limpiamente.

Detalles interesantes bajo el capó

No hay daemons personalizados ni hooks pesados de bash analizando la salida de ps aquí. El autor tomó una ruta más elegante.

Las versiones de Claude Code 2.1.139 y superiores pueden exponer información sobre sus agentes a través del comando integrado claude agents --json. Cada copia en ejecución reporta su estado actual a un supervisor local. El plugin simplemente lee este JSON a través de jq.

El principal desafío técnico fue vincular procesos a los paneles de tmux. En macOS, por ejemplo, un panel a menudo reporta el PID del shell padre en lugar del programa hijo. Dentro del plugin, el script agents.sh vincula identificadores a lo largo de una cadena: pid -> tty -> panel de tmux.

Gracias a esta vinculación, el plugin rastrea procesos en lugar de sesiones. Si lanzaste tres agentes diferentes en un proyecto o ejecutaste Claude en un panel adyacente regular sin el plugin, la herramienta encontrará cada proceso y lo mostrará como una línea separada. Toda la consulta toma solo tres llamadas al sistema, por lo que la interfaz funciona sin retrasos.

Otro detalle interesante: si abres el menú de selección (prefix + u) mientras ya estás dentro de un popup de Claude, el plugin primero desconecta el popup actual y luego expande la ventana de selección al tamaño completo de la terminal externa. No hay muñecas matryoshka anidadas de marcos que se encogen.

Instalación y configuración básica

Necesitarás tmux versión 3.2 o superior con soporte para popups, fzf instalado, la utilidad jq y una versión reciente de Claude Code.

Si usas el administrador de plugins TPM, agrega esta línea a tu archivo de configuración ~/.tmux.conf:

set -g @plugin 'craftzdog/tmux-claude-session-manager'

Después de eso, presiona prefix + I para cargarlo.

Por defecto, el plugin usa dos combinaciones de teclas:

• prefix + y lanza una nueva sesión de Claude en el directorio actual dentro de una ventana emergente (o se conecta a una existente);
• prefix + u abre el selector de fzf con todos los agentes activos.

Dentro de la ventana de lista, funcionan las flechas estándar y el filtrado de texto. Enter cambia a la sesión seleccionada y Ctrl-x termina el proceso abruptamente.

Los parámetros son fáciles de sobrescribir. Por ejemplo, puedes establecer indicadores de lanzamiento para Claude en sí o cambiar las dimensiones de la ventana:

set -g @claude_popup_width '85%' set -g @claude_popup_height '85%' set -g @claude_args '--dangerously-skip-permissions'

Para los fans del control modal, el README tiene un gran ejemplo de integración con diseño estilo vim. Puedes configurar fzf para que la lista se abra en modo navegación a través de j/k, y el cambio al modo búsqueda ocurre con las teclas i o a:

set -g @claude_fzf_options "\ --prompt 'nav> ' \ --bind 'j:down' \ --bind 'k:up' \ --bind 'q:abort' \ --bind 'x:execute-silent(kill {3})+reload(sleep 0.3; \$CLAUDE_PICKER --list)' \ --bind 'i:unbind(j,k,q,i,a,x)+change-prompt(filter> )' \ --bind 'a:unbind(j,k,q,i,a,x)+change-prompt(filter> )' \ --bind 'esc:rebind(j,k,q,i,a,x)+change-prompt(nav> )'"

¿Vale la pena instalarlo?

Si ejecutas Claude Code una vez a la semana para un par de líneas de código, puedes arreglártelas fácilmente sin el plugin. Una pestaña de terminal regular es perfectamente suficiente.

La herramienta es útil para quienes usan activamente el enfoque de agentes en la terminal y paralelizan tareas en diferentes ramas o subproyectos. El plugin elimina la tediosa tarea de encontrar la pestaña correcta y consolida el monitoreo de tareas en segundo plano en una pantalla clara. La configuración toma un par de minutos y el código fuente del script es compacto y transparente, sin ninguna magia innecesaria.