# 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

```bash
npm install -g tmux-mcp-shell-tool
```

Or use directly with npx:

```bash
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):

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

### 2. Start Tmux

```bash
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:**
```typescript
// 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:**
```json
{
  "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](./CONCEPT.md).

## Development

```bash
# 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](./CONCEPT.md) to understand the design constraints.

## License

MIT

## Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Tmux Manual](https://man.openbsd.org/tmux)
- [GitHub Issue #2](https://github.com/ketema/tmux-mcp-shell-tool/issues/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.