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 win

... View full README on GitHub