Tmux Buddy is an MCP server that aims to increase visiblity and the safety of the commands executed by AI agents. It allows to share a tmux terminal between a human and an agent in such a way that the human has full visiblity and finer control over the commands.

• Send Command: Send a command to the terminal without executing it. Uses bracketed paste to make sure accidental execution can't occur.
• Safety Verification: Use prompt_verify_string to ensure commands are executed in the correct context. the prompt line must show the string the agent expects or the command won't be sent (e.g., specific directory or Kubernetes context)
• Capture Output: Read the last N lines of terminal output. The agent is instructed to always check the terminal current output before executing the first command.
• Color Coded Terminals: To prevent accidental confusion on the human side

• Execute Commands: Run commands in a tmux session and wait for completion - detects completion and returns immediately
• Interactive Detection: Automatically detects when a terminal enters an interactive state (e.g., vim, nano, less) so the agent doesn't need to wait for a time-out
• Command Monitoring: Wait for asynchronous commands to finish and retrieve their output.
• Send Interrupt/Exit keys: Allows the agent to exit by itself from interactive programs or commands that hang for too long.

• Python 3.10+
• tmux installed on the system.

1. Clone this repository:

   git clone git@github.com:tomklino/tmux-mcp.git
   cd tmux-mcp

2. Install dependencies (it uses mcp library):

   pip install mcp

To use the server with an MCP client, add it to your configuration. Make sure to provide the absolute path to the tmux_mcp.py script.

It's recommended to copy or reference the AGENTS.md file contents to the agent's instructions as it helps the agent use the safety guards in situations where they are required.

You can add the MCP server to Claude Code using the CLI:

claude mcp add tmux python3 /absolute/path/to/tmux-mcp/tmux_mcp.py

Or add the following to your ~/.claude.json within your project's mcpServers object:

"tmux": {
  "type": "stdio",
  "command": "python3",
  "args": ["/absolute/path/to/tmux-mcp/tmux_mcp.py"],
  "env": {}
}

Add the following to your OpenCode configuration file located at ~/.config/opencode/opencode.json under the "mcp" key:

"mcp": {
  "tmux": {
    "type": "local",
    "command": ["python3", "/absolute/path/to/tmux-mcp/tmux_mcp.py"],
    "enabled": true
  }
}

First, install the MCP adapter:

pi install npm:pi-mcp-adapter

Then, add the following to your ~/.pi/agent/mcp.json or project-specific .pi/mcp.json:

{
  "mcpServers": {
    "tmux": {
      "command": "python3",
      "args": ["/absolute/path/to/tmux-mcp/tmux_mcp.py"]
    }
  }
}

When you share a tmux session with an AI agent, permission modes let you control what the agent is allowed to do in that session.

Create sessions with:

./tmux_cli.py new <name>

The session will start by default on "deny", by won't let the agent any permissions. cycle through the modes to allow the agent to work with the terminal.

You may change the default permission level new terminals start at in the permission config file (default: $HOME/.config/tmux-mcp/permissions.json)

In the tmux session, the status bar shows the current mode:

• MCP:DENY — agent access is blocked for this session.
• MCP:READ — agent can observe only (e.g. read terminal output). No typing.
• MCP:SEND — agent can type commands into the prompt, but won’t execute them. Use this when you want to review/edit a command before running it yourself.
• MCP:EXEC — agent can type and execute commands.

To change modes from inside tmux, use CTRL + ] to cycle:

DENY → READ → SEND → EXEC → DENY

Environment override (optional): set TMUX_MCP_PERMISSIONS_FILE to use a custom permissions file location.

The project includes a CLI utility tmux_cli.py for managing sessions:

# Create a new session with the custom prompt used by the MCP
./tmux_cli.py new green

To record a new tmux session, include the --record flag. Recordings are saved to ~/.tmux-session-recordings with a filename format of <session_name>_YYYY-MM-DD_HH-MM-SS.cast. asciinema must be installed on the system to use this feature.

After creating the session, you can intract with it yourself or tell the agent to interact with it as well. For example:

use the tmux session "green" to inspect the output of my last command
and explain why it's not working.

Or

use the tmux session "green" to check if there are any pods in a
crashloop. If there are any, describe them to find the reason.

Or

in the session "green" I typed in a `kubectl` command. Extend it
with custom columns to print out the name of the pod and the image
it runs.