Remote-first tmux co-pilot for humans + LLMs.

mcp-tmux

Table of Contents

• Quickstart (2 minutes)
• Highlights
• Prerequisites
• Install & run
• MCP client wiring (example)
• Exposed tools
• Collaborative workflow
• How-to (verbose examples)
• ChatGPT / Supergateway
• Configuration
• Safety notes
• Tips for LLM prompts
• CI, security, and governance
• Developing
• License

mcp-tmux is a Model Context Protocol server for people who learned the hard way that large language models are extremely confident about terminals they cannot actually see. It lets an LLM operate inside tmux with real, inspectable state instead of vibes, screenshots, or remembered lies. The server anchors the model to concrete reality: SSH-aware session discovery and bootstrapping, authoritative window and pane topology, and pull-based state snapshots so context is fetched when needed rather than hallucinated continuously. It can spawn or reattach to remote tmux sessions via your SSH config, inject keystrokes into the correct pane on purpose, read scrollback with full historical context, manage windows and splits deterministically, and enforce defaults so the model doesn’t calmly execute commands in a pane that stopped existing five minutes ago.

You need this if you want an LLM to assist in real terminals without pretending the terminal is a chat log. This is for pairing with an AI on live systems, debugging multi-pane chaos, automating the boring parts while you handle the judgment calls, or letting a model help without giving it omnipotent shell access and hoping nothing exciting happens. mcp-tmux exists to replace guesswork with state, narration with observation, and “I think you’re in the left pane” with provable fact.

Disclaimer: reasonable engineering effort has been applied to reduce the probability of reality-ending command execution. Guardrails exist. So do sharp edges. If something catastrophic happens, it will almost certainly be because a human approved it, ignored context, or decided this was a good idea at the time. Logs are kept. History remembers. Responsibility remains firmly biological.

Quickstart (2 minutes)

1. Install & build:

npm install
npm run build

2. Run with sensible defaults:

MCP_TMUX_HOST=my-ssh-alias MCP_TMUX_SESSION=collab npx @k8ika0s/mcp-tmux

3. In your MCP client, call:

tmux_open_session → tmux_default_context → tmux_list_windows / tmux_list_panes → tmux_send_keys → tmux_capture_pane

4. Re-ground anytime with tmux_state.

Highlights

• Remote-first: give it an SSH alias + session name and it will create or reconnect the remote tmux session for you.
• Collaborative: you and the model can attach to the same tmux; new windows/panes get LLM-friendly labels.
• Complete control: list, capture, send keys, manage windows/panes/sessions, or fall back to raw tmux commands when needed.
• Safety in the loop: destructive calls require confirm=true; defaults keep the model from mis-targeting panes.
• Observability: logging back to the client plus a tmux_state snapshot that includes recent scrollback.
• Tasks-ready: built-in MCP task helpers for tailing, watching, and waiting on patterns.

Capability map

Prerequisites

• tmux available on PATH (override with TMUX_BIN=/path/to/tmux). For remote flows, tmux must be installed on the remote host.
• Node.js 18+.
• SSH access to the target host(s) using config aliases (the host parameter is the ssh config Host).

Install & run

npm install
npm run build
MCP_TMUX_HOST=my-ssh-alias MCP_TMUX_SESSION=collab npx @k8ika0s/mcp-tmux  # optional defaults

# Version check
mcp-tmux --version

During development you can use hot reload:

npm run dev

MCP client wiring (example)

Add to your MCP client config (example for Claude Desktop/CLI style):

{
  "servers": {
    "tmux": {
      "command": "npx",
      "args": ["@k8ika0s/mcp-tmux"],
      "env": {
        "MCP_TMUX_HOST": "my-ssh-alias",   // optional default host
        "MCP_TMUX_SESSION": "collab"       // optional default session
      }
    }
  }
}

SSH quality-of-life: consider enabling ControlMaster/ControlPersist in your ssh config for faster repeated ssh -T <host> tmux ... invocations.

Exposed tools

• tmux_open_session: Ensure a remote tmux session exists (create if missing) given host (ssh alias) and session, and set them as defaults.
• tmux_default_context: Shows detected default session and a quick session listing.
• tmux_state: Snapshot sessions, windows, panes, and capture of the active/default pane.
• tmux_set_default / tmux_get_default: Persist or view default host/session/window/pane.
• tmux_capture_layout / tmux_restore_layout: Save and re-apply window layouts.
• tmux_tail_pane: Poll a pane repeatedly to follow output without reissuing commands.
• tmux_tail_task: Task-based tail with polling over time (client polls task results).
• tmux_select_window / tmux_select_pane: Change focus targets explicitly.
• tmux_set_sync_panes: Toggle synchronize-panes for a window.
• tmux_save_layout_profile / tmux_apply_layout_profile: Persist and re-apply layout profiles by name.
• tmux_readonly_state: Snapshot sessions/windows/panes/capture without touching defaults.
• tmux_batch_capture: Capture multiple panes in parallel for faster context gathering.
• tmux_run_batch: Run multiple commands in one call in the same pane (uses && by default, or ;/newline via joinWith for heredocs), auto-clean the prompt (bash/zsh: Ctrl+C then Ctrl+U) before writes by default (cleanPrompt=true), and auto-captures output with paging (starts ~20 lines, grows if needed).
• tmux_send_keys: Send keys (supports <SPACE>, <ENTER>, <TAB>, <ESC> tokens; empty + enter=true sends Enter).
• tmux_health: Quick health check (tmux reachable, session listing, host profile info).
• tmux_context_history: Pull recent scrollback (pane or session) and extract recent commands.
• tmux_quickstart: Return a concise playbook/do-don’t block for the LLM.
• tmux_multi_run: Fan-out send + capture/tail/pattern to multiple hosts/panes.
• Resource: tmux_state_resource (URI tmux://state/default) returns the current default snapshot on read.
• Logging: session logs are appended under ~/.config/mcp-tmux/logs/{host}/{session}/YYYY-MM-DD.log (override with MCP_TMUX_LOG_DIR).
• Audit logging: enable per-session via tmux_set_audit_logging to log commands and outputs verbosely (may grow large).
• tmux_list_sessions: Enumerate sessions with window/attach counts.
• tmux_list_windows: List windows (optionally scoped to a session).
• tmux_list_panes: List panes (optionally scoped to a target).
• tmux_capture_pane: Read scrollback from a pane (defaults to last ~200 lines).
• tmux_send_keys: Send keystrokes to a pane, optionally with Enter.
• tmux_new_session: Create a detached session to collaborate in.
• tmux_new_window: Create a window inside a session.
• tmux_split_pane: Split a pane horizontally/vertically, optionally with a command.
• tmux_kill_session, tmux_kill_window, tmux_kill_pane: Tear down targets (require confirm=true).
• tmux_rename_session, tmux_rename_window: Rename targets.
• tmux_command: Raw access to any tmux command/flags for advanced cases.

Targets accept standard tmux notation: session, session:window, session:window.pane, or pane/window IDs. Most tools also accept an optional host (ssh alias) and will fall back to MCP_TMUX_HOST or whatever tmux_open_session last set.