tmux-mcp-claude

MCP server that gives Claude Code full control over tmux sessions, windows, and panes — plus an optional AI safety classifier that uses Claude Sonnet to gate destructive commands.

What's included

Component	Description
server.mjs	MCP server exposing 11 tmux tools
hooks/notify-attention.sh	Desktop notification when Claude needs input
hooks/tmux-compact-hook.sh	Re-injects tmux workspace state after context compaction
Settings snippets (below)	Sonnet-based safety classifier for tmux_send_keys

Quick start

git clone <repo-url> ~/.claude/mcp-servers/tmux-mcp
cd ~/.claude/mcp-servers/tmux-mcp
npm install

Then add the MCP server to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "tmux": {
      "command": "node",
      "args": ["<path-to>/tmux-mcp-claude/server.mjs"]
    }
  }
}

Restart Claude Code — the 11 tmux_* tools will appear automatically.

Tools

Listing

Tool	Description	Parameters
tmux_list_sessions	List all tmux sessions	(none)
tmux_list_windows	List windows in a session	session?
tmux_list_panes	List panes in a window	target?

Sending commands and reading output

Tool	Description	Parameters
tmux_send_keys	Send keys/command to a pane	target, keys, enter? (default: true)
tmux_capture_pane	Capture visible content of a pane	target, start?, end?

Creating windows and panes

Tool	Description	Parameters
tmux_new_window	Create a new window	session?, name?, command?
tmux_split_window	Split a pane	target?, horizontal?, percent?, command?

Navigation and cleanup

Tool	Description	Parameters
tmux_select_window	Switch to a window	target
tmux_select_pane	Switch to a pane	target
tmux_kill_pane	Kill a pane	target
tmux_kill_window	Kill a window	target

Target syntax

Tmux targets follow the format session:window.pane:

• mysession — the session
• mysession:0 — window 0
• mysession:0.1 — pane 1 in window 0

Safety classifier hook (optional but recommended)

The MCP server itself has no guardrails — it will happily rm -rf / if asked. The safety comes from a PreToolUse hook that intercepts every tmux_send_keys call and uses Claude Sonnet to classify the command before it executes:

• Safe commands (reads, builds, navigation) → auto-allowed, no prompt
• Destructive commands (rm, kill, force-push, DROP, etc.) → asks for user permission

Setup

Add these sections to your ~/.claude/settings.json:

1. Auto-allow the tmux tools (so Claude doesn't ask permission for each call)

{
  "permissions": {
    "allow": [
      "mcp__tmux__tmux_list_sessions",
      "mcp__tmux__tmux_list_windows",
      "mcp__tmux__tmux_list_panes",
      "mcp__tmux__tmux_capture_pane",
      "mcp__tmux__tmux_new_window",
      "mcp__tmux__tmux_split_window",
      "mcp__tmux__tmux_select_window",
      "mcp__tmux__tmux_select_pane",
      "mcp__tmux__tmux_kill_pane",
      "mcp__tmux__tmux_kill_window",
      "mcp__tmux__tmux_send_keys"
    ]
  }
}

2. Sonnet safety classifier (PreToolUse hook)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__tmux__tmux_send_keys",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are a security classifier for tmux_send_keys. The tool input is: $ARGUMENTS\n\nExtract the \"keys\" field from tool_input. Classify the command that is about to be sent to a tmux pane.\n\nBLOCK (return permissionDecision: \"ask\") if the command would:\n- Delete files or directories (rm, rmdir, shred)\n- Overwrite or truncate files (>, tee without -a on important files)\n- Kill processes (kill, killall, pkill, xkill)\n- Modify system state dangerously (systemctl stop/disable, shutdown, reboot, halt)\n- Drop databases/tables or delete data (DROP, DELETE without WHERE, TRUNCATE)\n- Force-push, hard-reset, or destructive git ops (git push --force, git reset --hard, git clean -f, git checkout .)\n- Modify permissions broadly (chmod -R 777, chown -R)\n- Send mutating requests to external services (curl -X POST/PUT/DELETE/PATCH, wget --post)\n- Remove packages (dnf remove, apt remove/purge, pip uninstall)\n- Run anything else that is hard to reverse or could cause data loss\n\nALLOW (return permissionDecision: \"allow\") if the command:\n- Only reads data (ls, cat, grep, find, git status/log/diff, kubectl get/describe, oc get)\n- Runs builds or tests (make, go build/test, npm test/build, mvn, gradle)\n- Navigates (cd, pushd, popd)\n- Sets environment variables or exports\n- Echoes/prints output\n- Creates new files/dirs without overwriting (touch, mkdir -p)\n- Installs packages (generally reversible)\n- SSH, scp, rsync (read-like or additive)\n- Any other read-only or easily reversible operation\n\nRespond with a JSON object. For safe commands: {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\"}}. For destructive commands: {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"<brief reason>\"}}.",
            "model": "claude-sonnet-4-6",
            "statusMessage": "Classifying tmux command safety..."
          }
        ]
      }
    ]
  }
}

3. Optional companion hooks

Desktop notification when Claude stops and waits for input:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "<path-to>/tmux-mcp-claude/hooks/notify-attention.sh"
          }
        ]
      }
    ]
  }
}

Re-inject tmux state after context compaction:

{
  "hooks": {
    "PostCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "<path-to>/tmux-mcp-claude/hooks/tmux-compact-hook.sh"
          }
        ]
      }
    ]
  }
}

Security

• server.mjs uses execFile (no shell) — immune to command injection
• Arguments passed as arrays, never string-interpolated
• Only calls tmux subcommands, no arbitrary shell execution
• The Sonnet safety hook adds a semantic layer on top, catching destructive intent even in complex or piped commands

How it works

Claude Code ──▶ tmux_send_keys("rm -rf /tmp/old")
                       │
                       ▼
              PreToolUse hook fires
                       │
                       ▼
              Sonnet classifies: "destructive — file deletion"
                       │
                       ▼
              User prompted: "Allow rm -rf /tmp/old?"
                       │
                  ┌────┴────┐
                  ▼         ▼
               Allow     Deny
                  │
                  ▼
           tmux send-keys executes

Example workflow

# Claude discovers your tmux sessions
tmux_list_sessions()
tmux_list_windows(session="work")

# Creates a window for a task
tmux_new_window(session="work", name="build")

# Runs a command (auto-allowed by Sonnet — it's a build)
tmux_send_keys(target="work:build", keys="make test")

# Reads the output
tmux_capture_pane(target="work:build")

# Tries something destructive (Sonnet asks permission)
tmux_send_keys(target="work:build", keys="rm -rf ./dist")
# → User prompted before execution

Toggle/disable

Action	How
Disable all hooks	"disableAllHooks": true in settings.json
Re-enable all hooks	Remove/set false "disableAllHooks"
Review hooks in UI	/hooks inside Claude Code
Remove safety hook only	Delete the PreToolUse entry from settings.json

License

MIT