Tmux MCP Shell Tool

An MCP (Model Context Protocol) server that enables AI agents to read tmux pane content on-demand, providing context-aware assistance during interactive terminal sessions.

Problem

AI agents can't see what's happening in your terminal during interactive commands like git rebase -i, vim, or when resolving merge conflicts. This forces you to manually describe your terminal state, breaking your workflow.

Solution

This MCP server lets AI agents read your tmux pane content when you ask for help, enabling them to see exactly what you're seeing and provide context-aware guidance.

Key Constraint: LLM input cannot be streamed, so this tool uses a reactive reading approach rather than passive real-time monitoring. The agent only reads your terminal when you explicitly request assistance.

Features

• On-demand pane reading: AI reads tmux pane content only when you ask
• Scrollback support: Access terminal history, not just visible content
• Multi-pane/session support: Target specific tmux sessions, windows, and panes
• Privacy-focused: No background monitoring, explicit user control
• Rich metadata: Cursor position, pane dimensions, active command

Installation

npm install -g tmux-mcp-shell-tool

Or use directly with npx:

npx tmux-mcp-shell-tool

Requirements

• tmux version 2.0 or later
• Node.js version 18 or later
• Active tmux session

Quick Start

1. Configure MCP Client

Add to your MCP settings (e.g., Claude Desktop):

{
  "mcpServers": {
    "tmux-shell": {
      "command": "npx",
      "args": ["tmux-mcp-shell-tool"]
    }
  }
}

2. Start Tmux

tmux new-session -s work

3. Use with AI Agent

You: *runs git rebase -i and encounters conflict*
You: "I'm stuck in a rebase with conflicts. Can you help?"
Agent: *uses read_tmux_pane tool*
Agent: "I can see you have a conflict in src/main.rs between lines 45-67.
       The conflict shows your changes vs. the upstream changes..."

MCP Tools

read_tmux_pane

Reads content from a tmux pane.

Parameters:

• target (string, optional): Tmux target in format session:window.pane (default: current pane)
• start_line (number, optional): Start line (negative for scrollback, default: visible area)
• end_line (number, optional): End line (default: end of visible area)
• include_trailing_spaces (boolean, optional): Preserve trailing spaces (default: false)

Example:

// Read visible area of current pane
{
  "target": null
}

// Read last 100 lines of scrollback
{
  "target": "mysession:1.0",
  "start_line": -100,
  "end_line": -1
}

list_tmux_sessions

Lists all tmux sessions, windows, and panes.

Parameters: None

Returns:

{
  "sessions": [
    {
      "name": "work",
      "windows": [
        {
          "index": 1,
          "name": "editor",
          "panes": [
            {
              "index": 0,
              "command": "vim"
            }
          ]
        }
      ]
    }
  ]
}

Use Cases

Git Rebase Conflicts

User: "I'm in the middle of a rebase and git is showing conflicts"
Agent: *reads pane* "You have conflicts in 2 files: src/app.js and
       config.yaml. Let's resolve them one at a time..."

Vim Navigation

User: "I'm stuck in vim and can't exit"
Agent: *reads pane* "You're in NORMAL mode. Type :q and press Enter to quit,
       or :wq to save and quit"

Debugging Session

User: "The debugger is showing something weird"
Agent: *reads pane* "Looking at your debugger output, the variable 'user'
       is undefined at line 42. This suggests..."

Privacy & Security

What This Tool Does

• Reads tmux pane content ONLY when AI agent invokes the tool
• Requires user to actively request help (agent can't read unprompted)
• Only accesses tmux panes you specify

What This Tool Does NOT Do

• ❌ Monitor keystrokes in real-time
• ❌ Run background processes watching your terminal
• ❌ Automatically filter sensitive data (passwords, API keys)
• ❌ Store or log terminal content

Best Practices

1. Be mindful of sensitive data: Avoid asking for help when passwords/keys are visible
2. Use specific pane targets: Specify exact panes rather than reading all sessions
3. Review tool invocations: Check what your AI agent is reading in the MCP logs
4. Clear sensitive content: Clear your terminal or switch panes before requesting help

Architecture

┌─────────────────┐
│   AI Agent      │  User: "I'm stuck in vim"
│  (Claude, etc)  │  Agent: *invokes read_tmux_pane*
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  MCP Server     │  Executes: tmux capture-pane -p
│  (This Tool)    │  Returns: Terminal content
└────────┬────────┘
         │
┌────────▼────────┐
│   Tmux Pane     │  Current content: "-- INSERT --"
│  (User Shell)   │
└─────────────────┘

Concept Document

For detailed architectural decisions and technical rationale, see CONCEPT.md.

Development

# Clone repository
git clone https://github.com/ketema/tmux-mcp-shell-tool.git
cd tmux-mcp-shell-tool

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Test
npm test

Contributing

Contributions welcome! Please read CONCEPT.md to understand the design constraints.

License

MIT

Related

• Model Context Protocol
• Tmux Manual
• GitHub Issue #2 - Original feature request

FAQ

Q: Can the AI see my keystrokes in real-time? A: No. The agent only reads pane content when you explicitly ask for help. There's no real-time monitoring.

Q: What if I have sensitive data on screen? A: Clear your screen or switch panes before asking for help. This tool does not filter sensitive data automatically.

Q: Does this work without tmux? A: No. This tool specifically uses tmux's capture capabilities. You must be running tmux.

Q: Can I use this with any AI agent? A: Yes, any agent that supports the Model Context Protocol (MCP) can use this tool.

Q: Why not just use terminal sharing/recording? A: This provides programmatic access for AI agents to read terminal state, enabling context-aware assistance during your workflow without manual copy-paste.