Configurar tmux para usar Claude Code por SSH sin perder la sesión

Todo depende del equipo que ejecuta el trabajo. tmux conserva la sesión de terminal cuando se pierde la conexión. No puede hacer que una computadora suspendida siga procesando, mantener activo un servidor apagado ni reiniciar un proceso de Claude que haya fallado. Anthropic recomienda expresamente tmux o screen para que una sesión remota de Claude sobreviva a una desconexión SSH. Documentación de Remote Control de Anthropic.

Cómo configurar tmux según la documentación de Anthropic

Guarda la configuración en el equipo que ejecuta Claude Code. Si trabajas de forma remota, debe ir en el archivo ~/.tmux.conf del servidor remoto. Si hace falta, instala tmux con el gestor de paquetes de ese equipo y comprueba allí tmux -V y claude --version antes de continuar.

Incorpora este bloque a ~/.tmux.conf. Las tres primeras líneas corresponden a la configuración documentada por Anthropic; la opción comentada del ratón es una preferencia opcional, no un requisito de Anthropic.

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

# Optional preference: enable mouse interaction in tmux.
# set -g mouse on

La opción passthrough permite que las notificaciones y las actualizaciones de progreso lleguen a la terminal externa. Las teclas extendidas permiten a tmux distinguir Mayús+Enter de Enter. Para aplicar la configuración a un servidor tmux que ya está en marcha, ejecuta tmux source-file ~/.tmux.conf; un servidor nuevo carga el archivo al iniciarse. Configuración de terminal de Anthropic.

Si todavía no tienes un servidor tmux activo, crea primero la sesión que se muestra más abajo y después ejecuta el comando de recarga. Deja los complementos de terceros fuera de la configuración inicial: este flujo de trabajo no necesita ninguno.

Asigna a cada worktree una sesión con nombre propio

Un worktree de Git es otra copia de trabajo con sus propios archivos y su propia rama, que comparte el historial del repositorio. Una sesión de tmux es un conjunto de ventanas de terminal identificado por un nombre; un panel es una subdivisión de una ventana. Imagina el worktree como la mesa de trabajo y tmux como la habitación de la que puedes salir y a la que puedes volver. Guía de worktrees de Anthropic.

Usa nombres relacionados para que el nombre de la sesión te indique en qué copia de trabajo vas a entrar. Esta es una organización sugerida, no la configuración predeterminada de Claude Code:

El siguiente ejemplo de configuración inicial presupone que ya existe un repositorio en ~/src/project, con al menos un commit, y que los nombres de ramas, directorios y sesiones están libres. Sustituye dev@devbox y la ruta del proyecto. Empieza desde el shell habitual de tu computadora portátil, fuera de tmux. Los comandos de worktree siguen el procedimiento manual de Anthropic; la organización en sesiones con nombre es la propuesta de esta guía.

ssh dev@devbox
cd ~/src/project

git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix -b bugfix

tmux new-session -d -s cc-feature-a -n claude -c "$HOME/src/project-feature-a"
tmux new-session -d -s cc-bugfix -n claude -c "$HOME/src/project-bugfix"

tmux attach-session -t cc-feature-a
# Now inside the feature worktree's tmux shell:
claude

Una vez establecida la conexión SSH, introduce los demás comandos en el equipo remoto. Al principio, las dos sesiones sin cliente conectado contienen shells. Cuando te conectas a una de ellas y ejecutas claude, la sesión de programación arranca a la vista, incluidas las solicitudes habituales de configuración. Cuando quieras activar la segunda tarea, desconéctate de tmux, entra en cc-bugfix y ejecuta allí claude.

Cada worktree necesita su propia preparación del proyecto, incluidas las dependencias y la configuración local que corresponda. Comprueba el directorio y la rama antes de encargarle a Claude una tarea que modifique archivos. Procedimiento manual de worktrees de Anthropic.

Si quieres un shell adicional para las pruebas en la copia de trabajo de la funcionalidad, ejecuta tmux new-window -t cc-feature-a -n checks -c "$HOME/src/project-feature-a" desde un shell del equipo remoto. Mantén las comprobaciones junto a la tarea a la que pertenecen. Evita usar la copia de trabajo principal como directorio temporal compartido por ambos agentes.

Si también usas Codex, nuestra guía de worktrees con Codex CLI explica por separado el flujo de trabajo de esa herramienta.

Desconecta tmux, cierra la computadora y vuelve a entrar por SSH

Con el prefijo predeterminado de tmux, pulsa Ctrl+B, suelta ambas teclas y después pulsa D. Esto desconecta el cliente y te devuelve al shell remoto. Ya puedes cerrar la conexión SSH. Deja Claude en ejecución dentro de su sesión.

Cuando vuelvas, ejecuta ssh dev@devbox, después tmux list-sessions y, por último, tmux attach-session -t cc-feature-a. Usa el mismo equipo remoto y la misma cuenta de usuario. Desde tu computadora portátil, puedes hacer lo mismo con un solo comando: ssh -t dev@devbox 'tmux attach-session -t cc-feature-a'.

Estos atajos presuponen el prefijo predeterminado. Si lo cambiaste, utiliza el que hayas configurado. Dentro de tmux, cambia de sesión en lugar de abrir otro cliente tmux anidado.

Al volver a conectarte, accedes al proceso de terminal que ya estaba en ejecución. Si ese proceso terminó, recuperar la conversación es una operación distinta: claude --continue retoma la conversación más reciente del directorio actual y claude --resume abre un selector. Ninguno sustituye a mantener activo el proceso original. Gestión de sesiones de Anthropic.

Si quieres acceder desde el teléfono o el navegador, consulta Claude Code Remote Control. La ejecución sigue ocurriendo en el equipo anfitrión, que debe permanecer encendido. Remote Control de Anthropic.

Añade un equipo de agentes cuando el trabajo necesite coordinación

Los equipos de agentes son experimentales y están desactivados de forma predeterminada. Desde un shell de tmux, inicia una nueva sesión interactiva del agente coordinador con CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux. La variable de entorno habilita los equipos para ese inicio; la opción del comando selecciona los paneles divididos. Configuración de equipos de agentes de Anthropic.

El modo predeterminado actual es in-process. El modo auto usa paneles divididos dentro de tmux y recurre a una alternativa cuando hace falta; tmux selecciona el modo de paneles divididos con detección de terminal. Para guardar la preferencia, utiliza teammateMode en ~/.claude/settings.json. Los paneles divididos dan a cada miembro del equipo una terminal visible independiente. Anthropic señala que la terminal integrada de VS Code, Windows Terminal y Ghostty no son compatibles con este modo. Modos de visualización y limitaciones de Anthropic.

Para una primera prueba, yo le daría al coordinador este encargo acotado:

Las sesiones cc-feature-a y cc-bugfix que hayas iniciado manualmente no se convierten en miembros de un equipo por el simple hecho de estar en tmux. Crear un equipo es una decisión aparte sobre quién reparte el trabajo y concilia los hallazgos. Elige subagentes de Claude Code cuando quieras delegar tareas concretas dentro de una misma sesión.

Un panel no es una copia de trabajo independiente. Asigna archivos distintos o usa worktrees separados para las tareas de edición independientes. Los equipos también consumen más tokens; tmux no reduce ese consumo. Al volver a conectarte, accedes a una terminal que sigue activa, mientras que /resume no restaura a los miembros del equipo ejecutados en el mismo proceso. Recomendaciones de Anthropic para equipos de agentes.

Cinco situaciones en las que esta configuración resulta útil

Yo priorizaría estos usos en este orden. Son posibles flujos de trabajo, no afirmaciones de productividad demostradas con mediciones.

Mide el costo de las interrupciones antes de añadir más automatización. Como ejemplo, cinco interrupciones que obliguen a dedicar cuatro minutos cada una a reconstruir el contexto cuestan veinte minutos por semana. Son valores hipotéticos, no resultados de una prueba de rendimiento. Registra tus propios tiempos de recuperación, preparación y revisión: el flujo de trabajo merece la pena si el total mejora. Tener más agentes simultáneos no implica automáticamente un mejor resultado en relación con el costo.

Dos herramientas pequeñas que podrías crear a partir de esta configuración

La oportunidad más sólida es un lanzador de worktrees y sesiones para equipos de desarrollo. Un equipo de plataforma podría pagar por unificar los nombres de las tareas, las rutas de las copias de trabajo y los comandos de conexión que usan sus desarrolladores. La versión mínima útil crearía o localizaría un worktree, abriría su sesión de tmux con nombre y mostraría la rama y la ruta antes de iniciar Claude. Debería pedir confirmación antes de eliminar una copia de trabajo.

La estimación de palabras clave de DataForSEO para Estados Unidos, consultada el 12 de octubre de 2026, es de 480 búsquedas mensuales de “tmux claude code”. Es una señal limitada de interés por la configuración, no una cifra de compradores. La dificultad es que un pequeño script interno puede bastar; un producto de pago necesita ofrecer configuración o soporte específicos para cada equipo que ahorren trabajo recurrente.

Un inventario de sesiones remotas es una segunda propuesta, más acotada. Un equipo pequeño de ingeniería podría usar un lugar común para registrar los alias de los equipos aprobados, los nombres de las sesiones y las rutas de las copias de trabajo, con un comando de conexión SSH que se pueda copiar. Empieza por facilitar la búsqueda y el acceso; añade controles del ciclo de vida solo si los usuarios los necesitan.

La misma consulta de DataForSEO estima 1,600 búsquedas mensuales en Estados Unidos de “claude code remote” y 70 de “claude code remote ssh”. La consulta más amplia incluye a quienes buscan otras interfaces remotas, así que por sí sola no valida un producto basado en SSH. La dificultad está en la gestión del acceso: el inventario debe respetar los permisos que cada desarrollador ya tiene en los equipos remotos. Entrevista a equipos que trabajen principalmente a distancia antes de crear un panel.

Dudas habituales al trabajar con esta configuración

Para empezar el lunes: elige una tarea remota, crea su worktree y su sesión con nombre, y comprueba que puedes desconectarte y volver a entrar antes de dejarla sin supervisión. Añade una segunda tarea independiente solo cuando ese procedimiento ya te resulte habitual.

Si tu equipo necesita integrar este flujo de trabajo en su entorno de desarrollo, desarrollamos sistemas de IA para producción.