{
  "markdown": "# tmux-mcp\n\n<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"tmux-mcp logo\" width=\"320\" />\n</p>\n\nMCP server that gives AI assistants full visibility into your tmux sessions — browse sessions, windows, and panes, read terminal output, and send commands.\n\n**Watch your AI agent work in real-time.** Enable `TMUX_MCP_ALWAYS_USE` to force every shell command through a named tmux session instead of direct Bash — every command your AI runs appears live in your terminal, fully auditable.\n\nWorks with **Claude Code, OpenCode, Cursor, Windsurf**, and any MCP-compatible host.\n\n## What it can do\n\n**Read your terminal state**\n- List every active tmux session with window count, creation time, and attached status\n- List windows inside a session — index, name, pane count, which one is active\n- List panes inside a window — size, running command, which one is active\n\n**See what's on screen**\n- Capture the visible output of any pane — up to 5 000 lines of scrollback\n- Read logs, compiler errors, server output, test runs — anything in your terminal\n\n**Create and organise**\n- Create sessions, windows, and panes with a working directory and an initial command\n- Split panes horizontally or vertically\n- Rename sessions and windows for reliable targeting\n\n**Clean up**\n- Kill sessions, windows, or individual panes\n\n**Control panes**\n- Send shell commands to any pane and immediately read the output\n- Send raw key sequences: `C-c` to interrupt, `Escape` to exit, arrow keys, etc.\n- Configurable wait time before capturing so long-running commands have time to finish\n\n**Error-safe**\n- Bad target? No tmux server? Returns a readable error message instead of crashing\n\n## Tools\n\n### `list_sessions`\nLists all active tmux sessions. No parameters.\n\nReturns: session name, number of windows, creation time, attached/detached status.\n\n### `list_windows`\nLists windows inside a session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `session` | string | Session name (from `list_sessions`) |\n\nReturns: window index, name, pane count, whether it's the active window.\n\n### `list_panes`\nLists panes inside a session or window.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `target` | string | Session name (`work`) or `session:window` (`work:0`) |\n\nReturns: pane index, title, dimensions (e.g. `220x50`), whether it's active, running command.\n\n### `capture_pane`\nCaptures the current terminal output of a pane.\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `target` | string | — | Pane target: `session:window.pane` (e.g. `work:0.0`) |\n| `lines` | number | `150` | Lines of scrollback to include (max 5000) |\n\nReturns: raw terminal text as it appears on screen.\n\n> **Security note:** pane output can contain environment variables, API keys, tokens, and credentials if they were printed to the terminal. Only use this server in trusted local environments.\n\n### `send_keys`\nSends a command or key sequence to a pane and captures the result.\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `target` | string | — | Pane target: `session:window.pane` |\n| `keys` | string | — | Command or tmux key notation (`C-c`, `Escape`, `Up`, etc.) |\n| `enter` | boolean | `true` | Press Enter after the keys |\n| `capture_lines` | number | `50` | Lines to capture after sending |\n| `wait_ms` | number | `400` | Milliseconds to wait before capturing |\n\nReturns: confirmation + pane output after the command ran.\n\n### `new_session`\nCreates a new detached tmux session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `name` | string | Session name. Omit to let tmux auto-assign one. |\n| `cwd` | string | Working directory for the session. |\n| `command` | string | Shell command to run immediately in the first window. |\n\n### `new_window`\nCreates a new window inside an existing session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `session` | string | Session to create the window in. |\n| `name` | string | Window name. |\n| `cwd` | string | Working directory for the new window. |\n| `command` | string | Shell command to run immediately. |\n\n### `split_pane`\nSplits a pane into two.\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `target` | string | — | Pane or window to split: `session:window.pane` |\n| `direction` | `horizontal` \\| `vertical` | `horizontal` | `horizontal` = left/right split, `vertical` = top/bottom |\n| `cwd` | string | — | Working directory for the new pane. |\n| `command` | string | — | Shell command to run in the new pane. |\n| `size` | number | — | Size of the new pane as a percentage (1–99). |\n\n### `kill_session`\nKills a session and all its windows and panes. **Destructive — cannot be undone.**\n\n| Parameter | Type | Description |\n|---|---|---|\n| `session` | string | Session name to kill. |\n\n### `kill_window`\nKills a window and all its panes. **Destructive.**\n\n| Parameter | Type | Description |\n|---|---|---|\n| `target` | string | Window target: `session:window` |\n\n### `kill_pane`\nKills a single pane and its running process. **Destructive.**\n\n| Parameter | Type | Description |\n|---|---|---|\n| `target` | string | Pane target: `session:window.pane` |\n\n### `rename_session`\n\n| Parameter | Type | Description |\n|---|---|---|\n| `session` | string | Current session name. |\n| `new_name` | string | New name. |\n\n### `rename_window`\n\n| Parameter | Type | Description |\n|---|---|---|\n| `target` | string | Window target: `session:window` |\n| `new_name` | string | New name. |\n\n## Target format\n\nAll tools use tmux's standard `session:window.pane` notation:\n\n```\nwork           →  session named \"work\"\nwork:0         →  window 0 of session \"work\"\nwork:0.0       →  pane 0, window 0, session \"work\"\nwork:editor.1  →  pane 1 of window named \"editor\" in session \"work\"\n```\n\nUse `list_sessions` → `list_windows` → `list_panes` to discover the right target before calling `capture_pane` or `send_keys`.\n\n## Install\n\n```bash\nnpm install -g @fr1sk/tmux-mcp\n```\n\n## Configure\n\n### OpenCode (`~/.config/opencode/opencode.json`)\n\n```json\n{\n  \"mcp\": {\n    \"tmux\": {\n      \"type\": \"local\",\n      \"command\": [\"tmux-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code (`~/.claude/settings.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"tmux\": {\n      \"command\": \"tmux-mcp\"\n    }\n  }\n}\n```\n\n### Cursor / Windsurf (`mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"tmux\": {\n      \"command\": \"tmux-mcp\"\n    }\n  }\n}\n```\n\n## Usage examples\n\n```\nWhat tmux sessions do I have running?\n```\n```\nShow me the output of my dev server — it's in the work session\n```\n```\nMy tests are failing, check what's in work:1.0\n```\n```\nRun git status in my work session and show me the output\n```\n```\nSend Ctrl-C to work:0.0, the process is stuck\n```\n```\nTail the last 300 lines from the logs pane in my api session\n```\n```\nCreate a new session called 'dev' in ~/Projects/myapp and run npm run dev\n```\n```\nSplit work:0.0 vertically and run npm test in the new pane\n```\n```\nRename session 'new' to 'api'\n```\n```\nKill the old session named 'temp'\n```\n\n## Environment variables\n\nSet these in your MCP client config under `environment` to control agent behavior.\n\n| Variable | Default | Description |\n|---|---|---|\n| `TMUX_MCP_DEFAULT_SESSION` | — | Session name the agent routes commands to when `alwaysUseTmux` is on |\n| `TMUX_MCP_ALWAYS_USE` | `false` | Set to `\"true\"` to route all shell commands through tmux instead of direct Bash |\n\nWhen both are set, the `get_config` tool returns an `instructions` field the agent uses to automatically route every shell command through `send_keys` in the configured session.\n\nExample (OpenCode):\n\n```json\n{\n  \"mcp\": {\n    \"tmux\": {\n      \"type\": \"local\",\n      \"command\": [\"tmux-mcp\"],\n      \"environment\": {\n        \"TMUX_MCP_ALWAYS_USE\": \"true\",\n        \"TMUX_MCP_DEFAULT_SESSION\": \"dev\"\n      }\n    }\n  }\n}\n```\n\n## Security\n\nThis server provides **unrestricted local shell access** through tmux:\n\n- **`capture_pane`** — returns raw terminal output, which may include environment variables, API keys, tokens, database passwords, and SSH private keys if they were printed to the terminal.\n- **`send_keys`** — executes arbitrary shell commands in the target pane. Any command the AI sends runs in your shell with your permissions.\n- **`command` parameter** on `new_session`, `new_window`, and `split_pane` — passed directly to tmux, which runs it via `$SHELL -c`. No validation or sandboxing.\n\n**Only use this server in trusted local development environments. Never expose it to network-accessible MCP hosts or untrusted AI assistants.**\n\n## Requirements\n\n- Node.js 18+\n- tmux on `$PATH`\n",
  "bytes": 8540,
  "sha": "14057934fd74df765f5de147bca82740b1d295863fcfb48e12940d044ce5993c",
  "repo_slug": "fr1sk/tmux-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fr1sk_tmux_mcp_7abe29db/readme"
}