TMUX

Permite a los agentes crear sesiones, dividir paneles, ejecutar comandos y capturar salida con TMUX

Documentación

tmux-mcp-rs

tmux-mcp-rs es un servidor de Model Context Protocol (MCP) para tmux. Permite que los clientes MCP creen sesiones, den forma a ventanas y paneles, ejecuten comandos rastreados, inspeccionen la salida, gestionen búferes de tmux y controlen programas de terminal interactivos mediante herramientas estructuradas, en lugar de depender de un frágil raspado de pantalla.

Úsalo cuando un agente necesite una TTY real, comandos de larga duración, paneles en paralelo, estado de terminal reanudable o una sesión de tmux a la que un humano pueda conectarse durante la misma tarea.

[!WARNING] Este servidor puede permitir que un cliente MCP ejecute comandos de shell, escriba en paneles, lea la salida de la terminal, modifique sesiones de tmux y lea o escriba búferes de tmux. La política de ejecución predeterminada es permisiva. Usa sockets de tmux aislados y una política de config.toml antes de exponerlo a un cliente en el que no confíes plenamente.

Contenido

Qué ofrece el servidor
Requisitos
Instalación
Inicio rápido
Configuración del cliente
Referencia de configuración
Endurecimiento de seguridad
Referencia de herramientas MCP
Referencia de recursos MCP
Flujos de trabajo remotos y con sockets
Patrones de flujo de trabajo para agentes
Desarrollo
Notas y limitaciones
Anclas de código fuente

Qué ofrece el servidor

Herramientas de sesión, ventana, panel, cliente y búfer con entradas y salidas estructuradas.
execute-command y get-command-result para comandos de shell con IDs de comando, URI de recursos, estado, salida y seguimiento del código de salida por canal lateral (waitMs opcional; prefiere la suscripción a recursos para la finalización).
Recursos de panel, ventana, sesión, cliente, servidor y comandos rastreados para comprobaciones ligeras de estado sin volver a ejecutar herramientas.
Herramientas opcionales de entrada sin procesar para programas interactivos, avisos, REPLs y TUIs.
Controles de política en tiempo de ejecución para el filtrado de herramientas, el filtrado de comandos, el ámbito de socket/sesión/panel y grupos de operaciones generales.
Banderas de características en tiempo de compilación que eliminan las herramientas de entrada sin procesar del binario para compilaciones endurecidas.
Enrutamiento SSH opcional para que el servidor MCP local pueda controlar un servidor tmux remoto.

La ruta MCP suele ser más fiable que una habilidad tmux simple porque cada operación tiene una herramienta con nombre, parámetros tipados, IDs estables y respuestas estructuradas. Los clientes no necesitan inferir IDs de panel a partir de texto capturado ni analizar la salida de comandos para determinar si un comando ha terminado.

Requisitos

tmux 3.0 o más reciente en PATH.
Rust 1.70 o más reciente al compilar desde el código fuente.
Un shell compatible con el rastreador de comandos: bash, zsh o fish.

Al iniciarse, el servidor ejecuta tmux -V. Sale cuando detecta tmux 2.x porque tmux 2.x usa formatos de salida y banderas de división diferentes. Si no se puede detectar la versión, el inicio continúa y los errores de tmux se notifican mediante las llamadas a herramientas afectadas.

Instalación

Cargo

cargo install tmux-mcp-rs

Homebrew

brew install bnomei/tmux-mcp/tmux-mcp-rs

npm

npx @bnomei/tmux-mcp-rs --version
# or: npm install -g @bnomei/tmux-mcp-rs

El paquete npm es un envoltorio ligero: en la primera ejecución descarga el binario correspondiente de GitHub Releases, verifica el .sha256, lo guarda en caché y reenvía argv.

Docker

docker run --rm ghcr.io/bnomei/tmux-mcp:0.6.0 --version

La imagen es autocontenida: incluye Alpine tmux 3.x y el binario Linux musl precompilado. Las sesiones se ejecutan dentro del contenedor, no en el servidor tmux de tu escritorio.

Predeterminado (recomendado para Docker): sandbox de agente aislado. La conexión humana usa docker exec (ver más abajo).
Opcional (solo Linux): monta un socket tmux del host para que el contenedor controle un servidor del host al que puedas tmux attach de forma nativa. Docker Desktop en macOS/Windows generalmente no puede alcanzar sockets Unix del host de esta manera.
Para una co-conexión fácil entre humano y agente en una laptop, prefiere Homebrew, cargo o npm en el host en lugar de Docker.

Cliente MCP stdio (mantén stdin conectado):

docker run --rm -i \
  --name tmux-mcp \
  -v "$PWD:/workspace" \
  ghcr.io/bnomei/tmux-mcp:0.6.0

Observa una sesión creada dentro del contenedor:

docker exec -it tmux-mcp tmux attach -t workspace

Cableado de socket del host en Linux (avanzado):

# host: start an isolated tmux server
tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace

# container: talk to that socket (image still needs its own tmux client)
docker run --rm -i \
  -v /tmp/tmux-mcp-agent.sock:/tmp/tmux-mcp-agent.sock \
  --user "$(id -u):$(id -g)" \
  ghcr.io/bnomei/tmux-mcp:0.6.0 \
  --socket /tmp/tmux-mcp-agent.sock

# host: attach as usual
tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace

Iguala el UID/GID del contenedor al propietario del socket cuando fallen los permisos. Más detalle: packaging/README.md.

GitHub Releases

Descarga un archivo precompilado desde GitHub Releases, extráelo y coloca tmux-mcp-rs en tu PATH.

Desde el código fuente

git clone https://github.com/bnomei/tmux-mcp.git
cd tmux-mcp
cargo build --release

El binario se escribe en target/release/tmux-mcp-rs.

Verificar la instalación

tmux -V
tmux-mcp-rs --version

Salida esperada:

tmux 3.x
tmux-mcp-rs <version>

Inicio rápido

Añade el servidor a tu cliente MCP.

Codex CLI:

codex mcp add tmux -- tmux-mcp-rs

Claude Code:

claude mcp add --transport stdio tmux -- tmux-mcp-rs

Configuración genérica de cliente MCP:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs"
    }
  }
}

En tu cliente MCP, pide al agente que cree o liste sesiones de tmux.

Una primera tarea típica es:
```
Create a tmux session named workspace, list its windows and panes, then run pwd in the first pane.
```
Las respuestas de las herramientas deben incluir un ID de sesión, un ID de ventana, un ID de panel y un commandId para el comando rastreado.
Conéctate a la misma sesión de tmux si quieres observar o participar.
```
tmux attach -t workspace
```

Para un trabajo multiagente más seguro, comienza con un socket aislado en lugar del servidor tmux predeterminado:

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace

Luego configura el servidor MCP con --socket /tmp/tmux-mcp-agent.sock, TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock o una anulación por herramienta con socket.

Configuración del cliente

Usa args cuando tu cliente MCP acepte configuración JSON:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs",
      "args": [
        "--shell-type",
        "zsh",
        "--socket",
        "/tmp/tmux-mcp-agent.sock",
        "--config",
        "/path/to/config.toml"
      ]
    }
  }
}

Para un servidor tmux remoto, añade --ssh:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs",
      "args": [
        "--ssh",
        "user@host",
        "--socket",
        "/tmp/tmux-mcp-agent.sock"
      ]
    }
  }
}

Toda herramienta MCP excepto socket-for-path acepta un parámetro opcional socket. Si una herramienta lo omite, el servidor usa el socket predeterminado del proceso.

Referencia de configuración

tmux-mcp-rs no carga automáticamente un archivo de configuración. Pásalo con --config /path/to/config.toml.

Opciones de CLI

Opción	Predeterminado	Descripción
`--shell-type <SHELL>`	`bash`	Shell usado para el rastreo de comandos con conocimiento del shell. Valores admitidos: `bash`, `zsh`, `fish`. Si `[shell].type` existe en el archivo de configuración, el valor de la configuración gana.
`--config <PATH>`	sin definir	Archivo de configuración TOML a leer. Un TOML inválido, expresiones regulares inválidas y herramientas o grupos desconocidos hacen fallar el inicio.
`--socket <PATH>`	socket predeterminado de tmux	Establece `TMUX_MCP_SOCKET` para este proceso del servidor. Un parámetro por herramienta `socket` sigue ganando para esa llamada.
`--ssh <CONNECTION>`	sin definir	Enruta los comandos de tmux a través de SSH. Este valor gana sobre `[ssh].remote` y `TMUX_MCP_SSH`.
`--help`	n/a	Imprime la ayuda de la CLI.
`--version`	n/a	Imprime la versión del binario.

Variables de entorno

Variable	Descripción
`TMUX_MCP_SOCKET`	Ruta del socket tmux predeterminado cuando no se proporciona una anulación por herramienta `socket`. Si no está definida, el servidor usa la ruta predeterminada del socket de tmux: `$TMUX_TMPDIR/tmux-$UID/default`, o `/tmp/tmux-$UID/default` cuando `TMUX_TMPDIR` no está definida.
`TMUX_MCP_SSH`	Cadena de conexión SSH usada cuando `--ssh` y `[ssh].remote` no están definidas. La cadena se analiza con reglas de palabras de shell. Las comillas desbalanceadas hacen fallar el inicio.
`TMUX_MCP_TOOLS`	Anulación por proceso para `[security.tools]`. Usa `allow:<items>` o `deny:<items>`. Sin un prefijo, el valor se trata como una lista de denegación.
`RUST_LOG`	Habilita la salida de rastreo a través de `tracing-subscriber` cuando está definida. Los registros se escriben en stderr.

Reglas de precedencia:

Configuración	Precedencia
Socket	Parámetro por herramienta `socket`, luego `--socket` o `TMUX_MCP_SOCKET`, luego la ruta predeterminada del socket de tmux.
SSH	`--ssh`, luego `[ssh].remote`, luego `TMUX_MCP_SSH`, luego sin SSH.
Tipo de shell	`[shell].type`, luego `--shell-type`, luego `bash`.
Filtro de herramientas	`TMUX_MCP_TOOLS`, luego `[security.tools]`, luego modo de denegación sin elementos denegados.

Ejemplo de configuración

[shell]
type = "zsh"

[ssh]
remote = "user@host"

[security]
enabled = true
allow_execute_command = true
allow_raw_mode = true
allow_send_keys = false
allow_kill = true
allow_create = true
allow_split = true
allow_rename = true
allow_move = true
allow_capture = true
allow_list = true
allowed_sockets = ["/tmp/tmux-mcp-agent.sock"]
allowed_sessions = ["workspace"]
allowed_panes = ["%1"]
allowed_buffer_paths = ["/srv/tmux-mcp-buffers"]

[security.command_filter]
mode = "allowlist"
patterns = ["^cargo ", "^git ", "^rg ", "^sed "]

[security.tools]
mode = "deny"
items = ["@raw-input"]

[tracking]
capture_initial_lines = 1000
capture_max_lines = 16000
completed_retention_minutes = 240
completed_max_entries = 1000
tracking_deadline_seconds = 600

[search]
streaming_threshold_bytes = 262144

Opciones de seguridad

Clave	Tipo	Predeterminado	Descripción
`security.enabled`	booleano	`true`	Habilita las comprobaciones de política. Establécelo en `false` solo cuando quieras omitir todas las comprobaciones de política.
`security.allow_execute_command`	booleano	`true`	Permite `execute-command` y `get-command-result`.
`security.allow_raw_mode`	booleano	`true`	Permite `execute-command` con `rawMode=true`, que envía el comando sin marcadores de rastreo.
`security.allow_send_keys`	booleano	`true`	Permite las herramientas de entrada sin procesar: `send-keys`, `send-hex`, `paste-text` y los ayudantes de teclas especiales.
`security.allow_kill`	booleano	`true`	Permite `kill-session`, `kill-window`, `kill-pane` y `detach-client`.
`security.allow_create`	booleano	`true`	Permite `create-session` y `create-window`.
`security.allow_split`	booleano	`true`	Permite `split-pane`.
`security.allow_rename`	booleano	`true`	Permite las herramientas de renombrado de sesión, ventana y panel.
`security.allow_move`	booleano	`true`	Permite las herramientas de enfoque, redimensionado, zoom, diseño, unión, división, intercambio, movimiento y sincronización de paneles.
`security.allow_capture`	booleano	`true`	Permite `capture-pane` y las herramientas de lectura, escritura y búsqueda de búferes de tmux. Las operaciones de archivos de búfer forman parte de esta superficie de captura.
`security.allow_list`	booleano	`true`	Permite las herramientas de listado de sesión, ventana, panel, cliente, búfer y sesión actual.
`security.allowed_sockets`	matriz de cadenas o sin definir	sin definir	Cuando está definida, el socket efectivo para cada solicitud de herramienta y recurso debe coincidir exactamente con una de estas rutas.
`security.allowed_sessions`	matriz de cadenas o sin definir	sin definir	Cuando está definida, las operaciones con ámbito de sesión se limitan a IDs o nombres de sesión tmux exactos de la lista.
`security.allowed_panes`	matriz de cadenas o sin definir	sin definir	Cuando está definida, las operaciones directas de panel se limitan a los IDs de panel listados.
`security.allowed_buffer_paths`	matriz de cadenas o sin definir	sin definir	Directorios canónicos permitidos para `save-buffer` y `load-buffer`. Cuando no está definida, las rutas deben ser relativas y permanecer bajo el directorio `tmux-mcp-buffers/` del directorio temporal local, o `/tmp/tmux-mcp-buffers/` a través de SSH. Una lista vacía deniega todas las rutas de archivos de búfer.
`security.command_filter.mode`	`off`, `allowlist`, `denylist`	`off`	Modo de filtro de comandos por expresión regular.
`security.command_filter.patterns`	matriz de cadenas	`[]`	Patrones de expresión regular usados por el filtro de comandos.
`security.tools.mode`	`deny`, `allow`	`deny`	Modo de filtro de superficie de herramientas en tiempo de ejecución.
`security.tools.items`	matriz de cadenas	`[]`	Nombres exactos de herramientas o grupos como `@raw-input`.

security.command_filter comprueba cada sentencia de shell no vacía en busca de execute-command, send-keys (literal y no literal), paste-text, set-buffer, append-buffer y los bytes decodificados pasados a send-hex. Divide ;, |, & sin comillas y nuevas líneas, y luego comprueba recursivamente sustituciones de comandos, sustituciones de procesos, sub-shells y grupos de llaves. Rechaza formas de shell que no puede analizar de forma segura, incluidas las comillas ANSI-C $'...' y los envoltorios de shell -c. No filtra los ayudantes de teclas especiales. Para un límite estricto, deshabilita las herramientas de entrada sin procesar en tiempo de ejecución o compílalas fuera.

Opciones de rastreo

Clave	Predeterminado	Descripción
`tracking.capture_initial_lines`	`1000`	Líneas del panel capturadas al actualizar la salida parcial de un comando en ejecución.
`tracking.capture_max_lines`	`16000`	Máximo de líneas del panel capturadas al extraer la salida final entre los marcadores START/DONE visibles para el humano.
`tracking.capture_backoff_factor`	`2`	Aceptado para compatibilidad de configuración. La finalización por canal lateral ya no usa retroceso de captura.
`tracking.completed_retention_minutes`	`240`	Límite de antigüedad para el historial de comandos completados retenido en memoria.
`tracking.completed_max_entries`	`1000`	Máximo de entradas de comandos completados retenidas en memoria. Establézcalo en `0` para deshabilitar la poda por cantidad de entradas y depender solo del tiempo de retención.
`tracking.tracking_deadline_seconds`	`600`	Cuánto tiempo espera el vigilante del canal lateral por `tmux wait-for` antes de marcar `tracking_error`.

Opciones de búsqueda

Clave	Predeterminado	Descripción
`search.streaming_threshold_bytes`	`262144`	Umbral de tamaño de búfer donde la búsqueda transmite a través de un archivo temporal en lugar de cargar todo el texto del búfer en una sola cadena para el pase de búsqueda.

Endurecimiento de seguridad

De forma predeterminada, la aplicación de políticas está habilitada pero es permisiva:

Todas las compuertas gruesas de allow_* están en true.
command_filter.mode está en off.
allowed_sockets, allowed_sessions, allowed_panes y allowed_buffer_paths no están establecidos. Las operaciones de archivos de búfer permanecen restringidas al sandbox de directorio temporal predeterminado.
[security.tools] está en modo de denegación sin elementos denegados.

Ese predeterminado es conveniente para experimentación local, pero no es un sandbox.

Usar un socket de tmux aislado

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
tmux-mcp-rs --socket /tmp/tmux-mcp-agent.sock --config config.toml

[security]
allowed_sockets = ["/tmp/tmux-mcp-agent.sock"]

Cuando allowed_sockets está establecido, las llamadas sin un socket explícito aún se resuelven al socket predeterminado del proceso y deben coincidir con la lista de permitidos.

Eliminar entrada sin procesar en tiempo de ejecución

[security]
allow_send_keys = false

[security.tools]
mode = "deny"
items = ["@raw-input"]

Use esto cuando la entrada del shell deba pasar por execute-command para que el filtrado de comandos y el seguimiento de resultados de comandos permanezcan centrales.

Exponer solo herramientas de lectura y ejecución de comandos rastreados

[security.tools]
mode = "allow"
items = ["@read", "execute-command"]

@read incluye get-command-result, herramientas de listado, herramientas de captura, herramientas de lectura/búsqueda de búfer y socket-for-path.

Anular la superficie de herramientas para un proceso

TMUX_MCP_TOOLS=send-keys,paste-text tmux-mcp-rs
TMUX_MCP_TOOLS=deny:@raw-input tmux-mcp-rs
TMUX_MCP_TOOLS=allow:@read,execute-command tmux-mcp-rs

Compilar sin herramientas de entrada sin procesar

El conjunto de características de Cargo predeterminado incluye interactive y special-keys.

interactive registra send-keys, send-hex y paste-text.
special-keys registra send-cancel, send-eof, send-escape, send-enter, send-tab, send-backspace, send-up, send-down, send-left, send-right, send-page-up, send-page-down, send-home y send-end.

Deshabilite esas características para eliminar las herramientas del binario:

# Filtered-only build: execute-command is the only shell-input path.
cargo build --release --no-default-features --features rayon,rapidfuzz

# Keep raw keystrokes but remove special-key helpers.
cargo build --release --no-default-features --features rayon,rapidfuzz,interactive

execute-command siempre está registrado y permanece sujeto a security.command_filter.

Referencia de herramientas MCP

La disponibilidad de herramientas depende de las características de Cargo y la política de tiempo de ejecución. Las herramientas denegadas en tiempo de ejecución se eliminan de la lista de herramientas MCP anunciada y se deniegan cuando se llaman.

Grupos de herramientas

Grupo	Herramientas
`@all`	Cada herramienta conocida compilada en el binario.
`@read`	`socket-for-path`, herramientas de listado/búsqueda, `capture-pane`, herramientas de lectura/búsqueda de búfer y `get-command-result`.
`@socket`	`socket-for-path`.
`@list`	`list-sessions`, `find-session`, `list-windows`, `list-panes`, `list-clients`, `list-buffers`, `get-current-session`.
`@execute`	`execute-command`, `get-command-result`.
`@capture`	`capture-pane`.
`@buffer-read`	`list-buffers`, `show-buffer`, `search-buffer`, `subsearch-buffer`.
`@buffer-write`	`save-buffer`, `load-buffer`, `delete-buffer`, `set-buffer`, `append-buffer`, `rename-buffer`.
`@create`	`create-session`, `create-window`.
`@split`	`split-pane`.
`@rename`	`rename-session`, `rename-window`, `rename-pane`.
`@move`	`move-window`, `select-window`, `select-pane`, `resize-pane`, `zoom-pane`, `select-layout`, `join-pane`, `break-pane`, `swap-pane`, `set-synchronize-panes`.
`@kill`	`kill-session`, `kill-window`, `kill-pane`, `detach-client`.
`@interactive`	`send-keys`, `send-hex`, `paste-text`.
`@special-keys`	`send-cancel`, `send-eof`, `send-escape`, `send-enter`, `send-tab`, `send-backspace`, `send-up`, `send-down`, `send-left`, `send-right`, `send-page-up`, `send-page-down`, `send-home`, `send-end`.
`@raw-input`	Todas las herramientas de `@interactive` y `@special-keys`.

Herramientas por tarea

Tarea	Herramientas
Utilidad de socket	`socket-for-path` deriva una ruta de `/tmp/<hash>.sock` determinista a partir de una ruta de proyecto.
Gestión de sesiones	`list-sessions`, `find-session`, `create-session`, `kill-session`, `get-current-session`, `rename-session`.
Gestión de ventanas	`list-windows`, `create-window`, `kill-window`, `rename-window`, `move-window`, `select-window`, `select-layout`, `set-synchronize-panes`.
Gestión de paneles	`list-panes`, `split-pane`, `kill-pane`, `rename-pane`, `capture-pane`, `select-pane`, `resize-pane`, `zoom-pane`, `join-pane`, `break-pane`, `swap-pane`.
Ejecución de comandos	`execute-command` devuelve `commandId` + `resourceUri`; prefiera `resources/subscribe` y luego lea en `resources/updated`, o `get-command-result` con `waitMs`.
Gestión de clientes	`list-clients`, `detach-client`.
Inspección de búfer	`list-buffers`, `show-buffer`, `search-buffer`, `subsearch-buffer`.
Mutación de búfer	`save-buffer`, `load-buffer`, `delete-buffer`, `set-buffer`, `append-buffer`, `rename-buffer`.
Entrada sin procesar	`send-keys`, `paste-text`, `send-hex`, `send-cancel`, `send-eof`, `send-escape`, `send-enter`, `send-tab`, `send-backspace`, `send-up`, `send-down`, `send-left`, `send-right`, `send-page-up`, `send-page-down`, `send-home`, `send-end`.

Prefiera execute-command con suscripción/lectura de recursos (o get-command-result + waitMs) para comandos no interactivos. Los comandos rastreados se ponen en cola por panel. Use capture-pane solo para progreso en vivo; no trate los marcadores DONE del panel como autoritativos. Use herramientas de entrada sin procesar solo para indicadores, REPLs, editores, paginadores y TUIs—y no mientras un comando rastreado se esté ejecutando en ese panel.

Las instantáneas de comandos rastreados usan schemaVersion: 1 y actualmente se mueven a través de queued, running, luego completed, failed o tracking_error. El esquema también reserva cancelled, pero el rastreador actual no lo emite. Los comandos rastreados normales rechazan nuevas líneas incrustadas, marcadores de comentario de shell sin comillas (#) y operadores de fondo sin comillas (&) porque esas formas pueden eludir el epílogo de rastreo. Establezca rawMode=true o noEnter=true solo cuando intencionalmente quiera deshabilitar el seguimiento de finalización por canal lateral; esos registros permanecen running.

show-buffer lee como máximo 65,536 bytes de forma predeterminada. search-buffer tiene como predeterminado 40 bytes de contexto, 50 coincidencias y 65,536 bytes escaneados por búfer; devuelve desplazamientos de bytes y cursores de reanudación cuando los resultados se truncan. La búsqueda literal y por expresión regular siempre está disponible. La coincidencia difusa y las puntuaciones de similitud requieren la característica de Cargo rapidfuzz, que está habilitada de forma predeterminada.

Referencia de recursos MCP

Los recursos de servidor, panel, ventana, sesión y cliente reflejan el socket predeterminado del servidor. Los recursos de comandos rastreados conservan el socket efectivo registrado por su execute-command de origen, incluidos los reemplazos de socket por herramienta. Los recursos se enumeran dinámicamente y se filtran según la política de seguridad actual.

Solo los recursos de resultados de comandos rastreados admiten resources/subscribe; lea el recurso después de un evento notifications/resources/updated. Otros URI de recursos proporcionan instantáneas bajo demanda.

URI	Descripción
`tmux://server/info`	JSON con socket predeterminado y contexto SSH.
`tmux://pane/{paneId}`	Últimas 200 líneas de un panel como texto plano.
`tmux://pane/{paneId}/info`	Metadatos del panel como JSON.
`tmux://pane/{paneId}/tail/{lines}`	Cola de N líneas de un panel como texto plano.
`tmux://pane/{paneId}/tail/{lines}/ansi`	Cola de N líneas de un panel con colores ANSI.
`tmux://window/{windowId}/info`	Metadatos de ventana como JSON.
`tmux://session/{sessionId}/tree`	Instantánea de sesión, ventana y panel como JSON.
`tmux://clients`	Clientes de tmux como JSON.
`tmux://command/{commandId}/result`	Estado y salida del comando rastreado.

Flujos de trabajo remotos y de socket

SSH remoto

Use --ssh para ejecutar comandos de tmux en otra máquina. La autenticación SSH debe ser no interactiva, como un agente o inicio de sesión basado en clave.

tmux-mcp-rs --ssh "user@host"

Pase opciones de SSH antes del destino:

tmux-mcp-rs --ssh "-i ~/.ssh/key user@host"

La cadena de conexión se divide con reglas de palabras de shell. El destino debe ser el último token. El servidor cita el comando remoto de tmux antes de enviarlo a SSH, y la verificación de versión de tmux se aplica al tmux remoto cuando se puede alcanzar.

Remoto más socket aislado

Cree un servidor de tmux dedicado en el host remoto:

ssh user@host 'tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace'

Inicie el servidor MCP local contra ese socket remoto:

tmux-mcp-rs --ssh "user@host" --socket /tmp/tmux-mcp-agent.sock

Adjunte directamente desde un shell cuando sea necesario:

ssh -t user@host 'tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace'

Aislamiento de socket

Use --socket o TMUX_MCP_SOCKET para mantener un agente en un servidor de tmux:

tmux-mcp-rs --socket /tmp/tmux-mcp-agent.sock

TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock tmux-mcp-rs

Pre-cree la sesión cuando quiera un espacio de trabajo visible para el humano antes de que el cliente MCP se inicie:

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock tmux-mcp-rs

Docker y sockets

La imagen GHCR incluye tmux 3.x y tiene como predeterminado sesiones autocontenidas dentro del contenedor (docker exec … tmux attach). Solo en Linux, puede montar un socket del host para que el servidor MCP del contenedor maneje un servidor de tmux del host—vea Instalación → Docker y packaging/README.md. Docker Desktop en macOS/Windows no es una ruta confiable de socket del host; use una instalación nativa cuando necesite co-adjunción local fácil.

Patrones de flujo de trabajo de agentes

Las pruebas de integración cubren estos flujos de trabajo de tmux:

Patrón	Superficie de herramientas
Orientación por ID primero	`list-windows`, `list-panes`, `rename-window`.
Diseño de tarea por sesión	`create-session`, `create-window`, `split-pane`, `rename-pane`, herramientas de listado.
Contexto de shell con estado	`send-keys`, `capture-pane`.
Panel de salida continua	`send-keys`, `capture-pane`.
Automatización de indicadores interactivos	`send-keys`, `capture-pane`.
Interrupciones interactivas	`send-cancel`, `send-eof`, `capture-pane`.
Transmisión de paneles sincronizados	`set-synchronize-panes`, `send-keys`, `capture-pane`.
Entrega y búsqueda de búfer	`list-buffers`, `show-buffer`, `save-buffer`, `delete-buffer`, `search-buffer`, `subsearch-buffer`.
Reorganizaciones de paneles	`split-pane`, `select-layout`, `swap-pane`, `break-pane`, `join-pane`.
Metadatos y zoom	Herramientas de renombrado, `zoom-pane`, `resize-pane`, recursos de panel/ventana.
Paquete de contexto listo para auditoría	`execute-command`, `get-command-result`, `capture-pane`.
Orquestación de agentes	`create-window`, `split-pane`, `execute-command`, `send-keys`, `capture-pane`.

Para flujos de trabajo de tmux orientados a agentes, vea:

tmux-buffer-explorer usa búferes de tmux como un espacio de búsqueda externo para texto grande. Es útil cuando un agente necesita búsqueda acotada y rebanadas de seguimiento en lugar de cargar todo un búfer en contexto.

Desarrollo

Compile el binario:

cargo build --release

Ejecuta pruebas unitarias que no requieren tmux:

cargo test --lib
cargo test --test cli
cargo test --test search

Ejecuta pruebas de integración respaldadas por tmux:

TMUX_MCP_INTEGRATION=1 cargo test --test integration

Las pruebas de integración crean servidores tmux aislados usando sockets temporales y los limpian después.

Ejecuta las mismas comprobaciones de Rust que CI:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

Las notas de versión y los detalles de empaquetado de versiones se encuentran en CHANGELOG.md y docs/RELEASE.md.

Notas y limitaciones

tmux es dueño de los búferes de pegado, mientras que este servidor conserva instantáneas de comandos rastreados en memoria. paste-text, set-buffer, append-buffer y las salidas grandes de comandos retenidos aún pueden consumir memoria del host. La salida rastreada está limitada por líneas mediante capture_max_lines, pero las cadenas retenidas y la longitud de cada línea no están limitadas por bytes.
La búsqueda de búferes transmite búferes grandes a través de un archivo temporal después de search.streaming_threshold_bytes, pero los búferes de tmux en sí no se expulsan por tamaño.
Las filas de tmux se analizan a partir de la salida de -F delimitada por tabulaciones. Una tabulación literal dentro de un título de panel, ruta o campo similar puede desplazar campos posteriores y producir filas malformadas u omitidas.
paste-text usa marcadores de pegado entre corchetes. Los shells y programas que no admiten el pegado entre corchetes pueden tratar las nuevas líneas incrustadas como Enter. En macOS, el /bin/bash 3.2 predeterminado no admite el comportamiento moderno de pegado entre corchetes; zsh o un bash más reciente son más seguros para entrada multilínea que no debe enviarse línea por línea.
save-buffer escribe en el sistema de archivos del servidor tmux, y load-buffer lee de él. Ambos están regidos por allow_capture, [security.tools] y security.allowed_buffer_paths. Con la política habilitada por defecto, los llamadores usan rutas relativas dentro del sandbox tmux-mcp-buffers/ del directorio temporal local o /tmp/tmux-mcp-buffers/ sobre SSH; se rechazan el recorrido de directorios padre y los escapes canónicos o de enlaces simbólicos.
Los resultados de comandos están vinculados al socket. get-command-result debe usar el mismo socket efectivo que la llamada original a execute-command.
La finalización de comandos rastreados usa un búfer de salida privado de tmux + la señal wait-for, no el scrollback de panel falsificable. Las líneas opcionales START/DONE son solo para humanos/depuración.
La interacción send-keys/paste-text durante una ejecución rastreada en el mismo panel no está definida; espera a que el comando termine o usa otro panel.
El comportamiento SSH de extremo a extremo se verifica manualmente porque CI no proporciona un host remoto.

Anclas de código fuente

Análisis de CLI y comportamiento de inicio: src/main.rs
Herramientas MCP, recursos e instrucciones del servidor: src/server.rs
Política de seguridad y grupos de herramientas: src/security.rs
Rastreo de comandos: src/commands.rs
Comportamiento del socket tmux, SSH y envoltorio de procesos: src/tmux.rs
Tipos de datos públicos: src/types.rs
Pruebas de CLI: tests/cli.rs
Flujos de trabajo de integración: tests/integration.rs
Pruebas de búsqueda de búferes: tests/search.rs

Licencia

Licencia MIT. Consulta LICENSE.