# mcp-tmux [Health: Active]
**Category:** đź’» Developer Tools
**Repository:** https://github.com/k8ika0s/mcp-tmux
**GitHub Stars:** 0
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/mcp-tmux
## Description
Model Context Protocol server that lets LLMs collaboratively drive tmux
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"mcp-tmux": {
"command": "npx",
"args": ["-y","@k8ika0s/mcp-tmux"]
}
}
```
## Documentation & README
Remote-first tmux co-pilot for humans + LLMs.
# mcp-tmux
[](https://github.com/k8ika0s/mcp-tmux/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[](https://github.com/k8ika0s/mcp-tmux/pulls?q=is%3Apr+author%3Aapp%2Fdependabot)
[](https://www.npmjs.com/package/@k8ika0s/mcp-tmux)
[](https://registry.modelcontextprotocol.io/)
## Table of Contents
- [Quickstart (2 minutes)](#quickstart-2-minutes)
- [Highlights](#highlights)
- [Prerequisites](#prerequisites)
- [Install & run](#install--run)
- [MCP client wiring (example)](#mcp-client-wiring-example)
- [Exposed tools](#exposed-tools)
- [Collaborative workflow](#collaborative-workflow)
- [How-to (verbose examples)](#how-to-verbose-examples)
- [ChatGPT / Supergateway](#chatgpt--supergateway)
- [Configuration](#configuration)
- [Safety notes](#safety-notes)
- [Tips for LLM prompts](#tips-for-llm-prompts)
- [CI, security, and governance](#ci-security-and-governance)
- [Developing](#developing)
- [License](#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:
```bash
npm install
npm run build
```
2) Run with sensible defaults:
```bash
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
| Pillar | What it covers |
| --- | --- |
| Remote orchestration | `tmux_open_session`, SSH-aware tmux spawn/attach, PATH/tmux-bin overrides, host profiles |
| Grounded control | `tmux_state`, `tmux_capture_pane`, `tmux_list_*`, default targets, pane/window labels |
| Collaboration | `tmux_new_window`, `tmux_split_pane`, sync panes, layout capture/restore, layout profiles |
| Safety | `confirm=true` on destructive calls, logging + audit logs, defaults to avoid mis-targeting |
| Automation | `tmux_multi_run`, tail/pattern/watch tasks, fan-out capture/tail/pattern modes |
## 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
```bash
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:
```bash
npm run dev
```
### MCP client wiring (example)
Add to your MCP client config (example for Claude Desktop/CLI style):
```json
{
"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 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 ``, ``, ``, `` 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.
## Collaborative workflow
1) Ensure SSH access to the remote host (configured in `~/.ssh/config` as `Host my-ssh-alias`).
2) From your MCP client, call `tmux_open_session` with `host: "my-ssh-alias"` and `session: "collab"`. It will create the remote tmux session if needed and set it as default.
3) Call `tmux_default_context` to verify layout (uses the default host/session).
4) Drive the remote session with `tmux_send_keys` and read it with `tmux_capture_pane`.
5) The human can attach directly with `ssh -t my-ssh-alias tmux attach -t collab` to collaborate in real time.
6) Re-ground anytime with `tmux_state` to see sessions/windows/panes and the recent scrollback.
## How-to (verbose examples)
- Bootstrap remote session (create if missing) and set defaults:
```json
{"name":"tmux_open_session","arguments":{"host":"my-ssh-alias","session":"collab","command":"cd /srv && bash"}}
```
- Snapshot current state (uses defaults):
```json
{"name":"tmux_state","arguments":{"captureLines":200}}
```
- Drive a shell and read results:
```json
{"name":"tmux_run_batch","arguments":{
"target":"collab:0.0",
"steps":[{"command":"ls -lah"}],
"cleanPrompt":true,
"failFast":true
}}
```
- Behavior: sends Ctrl+C then Ctrl+U to clear the line (bash/zsh) before writing, runs the commands (Enter per step), then auto-captures output with paging (starts ~20 lines, grows if needed).
- Tail a pane to watch output:
```json
{"name":"tmux_tail_pane","arguments":{"target":"collab:0.0","lines":200,"iterations":3,"intervalMs":1000}}
```
- Tail via task (poll results):
```json
{"name":"tmux_tail_task","arguments":{"target":"collab:0.0","lines":200,"iterations":5,"intervalMs":1500}}
```
- Fan-out to multiple hosts/panes:
```json
{"name":"tmux_multi_run","arguments":{
"targets":[
{"host":"web-1","target":"ops:0.0"},
{"host":"web-2","target":"ops:0.0"}
],
"keys":"ls -lah /var/log && tail -n 50 app.log",
"mode":"send_capture",
"capture":true,
"captureLines":200,
"delayMs":500
}}
```
- Tail mode: set `"mode":"tail"` with `tailIterations`/`tailIntervalMs`.
- Pattern mode: set `"mode":"pattern"` with `pattern`/`patternFlags`.
- Capture context history and recent commands:
```json
{"name":"tmux_context_history","arguments":{"session":"collab","lines":800,"allPanes":true}}
```
- Run multiple commands with per-step Enter and prompt cleanup:
```json
{"name":"tmux_run_batch","arguments":{
"target":"collab:0.0",
"steps":[
{"command":"git status"},
{"command":"npm test","enter":true}
],
"cleanPrompt":true,
"failFast":true
}}
```
- `cleanPrompt` (default true) sends Ctrl+C then Ctrl+U (bash/zsh) before the first write to clear stray input.
- `failFast=true` joins commands with `&&` (single Enter); set `failFast=false` to send each step separately (Enter per step).
- Output capture is automatic with paging: starts around 20 lines, then expands (e.g., 100/400) if needed and returns a truncation hint.
- Quickstart playbook for the LLM:
```json
{"name":"tmux_quickstart","arguments":{}}
```
- Select window/pane and toggle sync:
```json
{"name":"tmux_select_window","arguments":{"target":"collab:0"}}
{"name":"tmux_select_pane","arguments":{"target":"collab:0.1"}}
{"name":"tmux_set_sync_panes","arguments":{"target":"collab:0","on":true}}
```
- Capture and restore layouts:
```json
{"name":"tmux_capture_layout","arguments":{"session":"collab"}}
{"name":"tmux_restore_layout","arguments":{"target":"collab:0","layout":"your-layout-string"}}
```
- Save/apply layout profiles:
```json
{"name":"tmux_save_layout_profile","arguments":{"session":"collab","name":"logs"}}
{"name":"tmux_apply_layout_profile","arguments":{"name":"logs"}}
```
- Health check:
```json
{"name":"tmux_health","arguments":{"host":"my-ssh-alias"}}
```
- Split a pane and label it:
```json
{"name":"tmux_split_pane","arguments":{"target":"collab:0.0","orientation":"horizontal","command":"htop"}}
```
- Tear down (requires explicit confirm):
```json
{"name":"tmux_kill_window","arguments":{"host":"my-ssh-alias","target":"collab:1","confirm":true}}
```
- Set or view defaults:
```json
{"name":"tmux_set_default","arguments":{"host":"my-ssh-alias","session":"collab","window":"collab:0","pane":"collab:0.0"}}
{"name":"tmux_get_default","arguments":{}}
```
## ChatGPT / Supergateway
Use Supergateway and (optionally) ngrok to expose the MCP stdio server to ChatGPT (Atlas tools):
1) Install globally:
```bash
npm i -g @k8ika0s/mcp-tmux
mcp-tmux --version # verify version
```
2) Run Supergateway locally:
```bash
supergateway serve --listen 0.0.0.0:3001 --command "mcp-tmux" --env "MCP_TMUX_HOST=my-ssh-alias" --env "MCP_TMUX_SESSION=collab"
```
3) Expose with ngrok (optional):
```bash
ngrok http 3001
```
Copy the https tunnel URL.
4) In ChatGPT (Atlas) tools, add a Custom MCP server pointing to your Supergateway URL (ngrok tunnel or local if supported). Example config snippet:
```json
{
"servers": {
"tmux": {
"url": "https://your-ngrok-subdomain.ngrok.io",
"capabilities": ["tools", "resources"]
}
}
}
```
Use readonly tools (`tmux_readonly_state`, `tmux_batch_capture`, `tmux_list_*`, `tmux_capture_pane`) for information gathering; use confirm flags for destructive actions.
## Configuration
- `MCP_TMUX_SESSION`: Prefer this session when no explicit target is provided.
- `MCP_TMUX_HOST`: Preferred ssh host alias when no explicit host is provided.
- `TMUX_BIN`: Path to the tmux binary (defaults to `tmux`).
- `MCP_TMUX_TIMEOUT_MS`: Timeout in ms for tmux/ssh invocations (default 15000).
- Defaults: set via `tmux_set_default` or `tmux_select_pane`; tools like `tmux_capture_pane`, `tmux_send_keys`, and tail/pattern tasks fall back to the default pane when `target` is omitted.
- PATH fallbacks: the server automatically adds `/opt/homebrew/bin:/usr/local/bin:/usr/bin` when invoking tmux (local or remote) so Homebrew installs are found.
- Host profiles (optional): `MCP_TMUX_HOSTS_FILE` can point to a JSON file like:
```json
{
"hashimac": { "pathAdd": ["/opt/homebrew/bin"], "tmuxBin": "/opt/homebrew/bin/tmux", "defaultSession": "ka0s" }
}
```
- Layout profiles (optional): stored at `~/.config/mcp-tmux/layouts.json` by default via `tmux_save_layout_profile`/`tmux_apply_layout_profile`.
- Logging directory: defaults to `~/.config/mcp-tmux/logs` (override with `MCP_TMUX_LOG_DIR`), organized by host/session with daily log files.
## Safety notes
> Safety spotlight: destructive tools need `confirm=true`, and defaults help you avoid targeting the wrong pane. Keep logs on; review captures before acting.
- The server never bypasses tmux permissions; it inherits your user account and socket access.
- `tmux_send_keys` will happily run destructive commands—ask for confirmation before altering state or killing sessions/windows.
- Destructive tools (`tmux/kill-*`, destructive `tmux_command`) require `confirm=true`.
- `tmux_command` runs whatever you pass through to tmux; double-check args before using it.
- Captures are pull-only: the model must request `tmux_capture_pane` to read output after sending keys.
- Remote usage depends on SSH trust; the MCP server inherits your SSH agent/keys and runs commands as your user on the remote host.
## Tips for LLM prompts
- Playbook: `tmux_open_session` → `tmux_default_context` → `tmux_list_windows`/`tmux_list_panes` → `tmux_send_keys` → `tmux_capture_pane`.
- Maintain defaults with `tmux_set_default` and re-ground with `tmux_state`.
- Confirm before destructive actions; prefer helper tools over raw `tmux_command`.
- After any change, re-list windows/panes or capture to stay in sync (server is pull-only).
- Verify what’s running with `tmux_server_info` (reports package name, version, repository link, and log directory).
## CI, security, and governance
- CI: GitHub Actions (`CI` workflow) runs `npm run build`.
- Security: dependency audit job (`npm audit --audit-level=high`) runs in CI.
- Release: manual workflow `Release (manual)` builds, packs, and can publish. Inputs: `publish`, `tag`, `version`, `bump`. When `publish=true`, it publishes to npmjs (requires `NPM_TOKEN`), attempts GitHub Packages only if the package name is scoped to `@k8ika0s/...` (warns/skip otherwise), and creates a git tag plus GitHub Release with the tarball.
- Branch protection (intended): main should be protected (require PR, no branch deletion). Configure this in repository settings.
- Ownership: CODEOWNERS assigns all files to @k8ika0s.
- Project stats: TypeScript, Node >=18, publishes `mcp-tmux` CLI entrypoint, MCP stdio server.
- Tests: `npm test` (vitest) covers helper path composition.
## Developing
- TypeScript build: `npm run build`
- Linting/formatting: not configured; keep patches small and readable.
- Make targets:
- `make install` — install dependencies
- `make build` — compile to `dist/`
- `make test` — run tests (vitest)
- `make dev` — hot-reload dev mode
- `make start` — run compiled server
- `make clean` — remove `dist/`
## License
AGPL-3.0-only