Instalación y Configuración de TermDeck

TermDeck es una plataforma local-first diseñada para transformar la experiencia de desarrollo mediante la orquestación de agentes de IA (como Claude Code, Codex o Gemini) y terminales estándar. A diferencia de un emulador de terminal convencional, actúa como una capa de gestión que permite manejar múltiples tareas simultáneas en ventanas flotantes dentro del navegador, manteniendo el control total sobre las acciones de la IA sin comprometer la seguridad de los datos.

1. Requisitos Previos y Entorno

Para garantizar que TermDeck funcione correctamente, tu sistema debe cumplir con los siguientes requisitos técnicos:

Node.js: Versión 18 o superior (requerido para el motor de ejecución).
Git: Instalado y configurado en el PATH del sistema (necesario para la gestión de git worktrees por agente).
tmux (Recomendado): Esencial para garantizar que las sesiones de terminal persistan incluso si cierras el navegador o si hay una desconexión del servidor local.
Permisos de PTY: Acceso para ejecutar procesos node-pty, necesarios para crear conexiones entre el servidor Node y los shells reales.

2. Métodos de Instalación

Dependiendo de tu flujo de trabajo, puedes elegir entre una ejecución rápida o una instalación permanente en tu sistema.

Opción A: Ejecución Instantánea (Modo Prueba)

Si deseas probar las capacidades de TermDeck sin instalar dependencias globales, utiliza el gestor npx. Esto descargará y ejecutará la versión más reciente temporalmente:

npx @kiril6/termdeck

Opción B: Instalación Permanente (Recomendado)

Para un uso diario, se recomienda instalar el binario globalmente. Esto añade termdeck a tu PATH y permite un acceso rápido desde cualquier terminal:

npm i -g @kiril6/termdeck

Opción C: Instalación mediante Clon (Para entornos específicos)

Si necesitas una configuración específica de node-pty para tu arquitectura de sistema:

git clone https://github.com/kiril6/termdeck
cd termdeck
node install.js
npm start

3. Configuración de Hooks y Agentes

El paso más crítico para la funcionalidad avanzada es la configuración de los hooks. Estos permiten que TermDeck reconozca estados específicos (como "esperando aprobación" o "ejecutando tarea") en herramientas como Claude Code, Codex o Gemini.

Ejecuta el siguiente comando para inicializar los hooks:

npx @kiril6/termdeck hooks install

4. Funciones Avanzadas y Optimización

TermDeck ofrece herramientas únicas para mejorar el flujo de trabajo con agentes de IA:

Git Worktrees: Cada agente opera en su propio git worktree, evitando que múltiples agentes modifiquen el mismo archivo simultáneamente.
Sistema de Semáforos: Interfaz visual que indica si un agente está trabajando (Verde), esperando (Ámbar) o requiere aprobación humana (Rojo).
Broadcast Input: Envía comandos o fragmentos de texto a todas las terminales activas simultáneamente.
Window Glue: Bloquea y une ventanas adyacentes para que se comporten como una sola unidad visual al redimensionarlas.

5. Verificación del Sistema

Tras la instalación, verifica el estado de tu entorno con estos pasos:

Inicia la aplicación: termdeck o mediante npx @kiril6/termdeck.
Accede a la interfaz en tu navegador local (por defecto en http://localhost:3000).
Verifica que las terminales se rendericen mediante xterm.js y que los indicadores de estado cambien correctamente según la actividad del agente.

6. Seguridad y Buenas Prácticas

Privacidad Local-First: TermDeck no envía datos a la nube ni recolecta telemetría. Tus claves API se mantienen en tu máquina, utilizadas solo por las herramientas CLI locales.
Aislamiento de Contexto: Utiliza siempre git worktrees para separar el contexto de cada agente y evitar conflictos de archivos.
Persistencia con tmux: Si usas tmux, tus sesiones persistirán incluso si el proceso del navegador falla o se reinicia.

7. Resolución de Problemas Comunes

Problema	Causa Probable	Solución
Error en el inicio (Puerto 3000)	Conflicto de puertos con otro servicio local.	Detén el proceso que ocupa el puerto o cambia la configuración del puerto en TermDeck.
Terminales sin respuesta / Sin renderizado	Falta de permisos para `node-pty` o dependencias del sistema faltantes.	Asegúrate de tener privilegios suficientes y que las librerías de PTY estén instaladas en tu SO.
Error de versión de Node	Versión inferior a la 18.0.0.	Actualiza mediante NVM o el instalador oficial antes de intentar ejecutar TermDeck.

Preguntas Frecuentes (FAQ)

¿Es seguro usar mis claves de API en TermDeck?
Sí, porque el software corre exclusivamente en tu máquina. Las llaves son utilizadas por las herramientas CLI locales que tú ya tienes configuradas.

¿Necesito Docker para ejecutarlo?
No es necesario; está diseñado para correr directamente sobre Node.js en tu sistema operativo, aunque puedes usarlo dentro de un contenedor si prefieres aislar el entorno del SO.

¿Qué sucede si el navegador se cierra?
Si tienes tmux configurado, la sesión del terminal persistirá y podrás reanudarla inmediatamente al volver a abrir la aplicación.

Información técnica verificada por HostingByte.

Enlaces Relacionados: Ficha de Software: termdeck | Más Guías de Instalación

Cómo instalar y configurar TermDeck