t-pane MCP Server

An MCP (Model Context Protocol) server that enables Claude to execute commands in tmux panes, providing a shared terminal experience between Claude and users.

Features

• Directory-Aware Pane Management: Creates separate panes for each directory/project
• Command Execution: Run commands in tmux panes with captured output
• Smart Output Capture: Uses unique markers to capture exactly the command output, regardless of buffer size
• Multiple Session Support: Each Claude instance gets its own pane based on working directory
• Session Persistence: Commands remain visible in tmux for user interaction
• Interactive Prompt Detection: Automatically detects when commands require user input (passwords, confirmations, etc.)
• Directory-Specific Logging: Commands are logged to .t-pane/logs/ in the current directory
• Background Tasks: Launch Claude instances in background panes for research/analysis tasks

Installation

cd /Users/rumen.d/github/mcp-servers/t-pane
npm install
npm run build

Configuration

Add to your Claude configuration file (~/Library/Application Support/Claude/config.json):

{
  "mcpServers": {
    "t-pane": {
      "command": "node",
      "args": ["/Users/rumen.d/github/mcp-servers/t-pane/dist/index.js"]
    }
  }
}

Usage

Once configured, Claude can use the following tools:

1. Execute Command

Executes a command in a tmux pane and captures the output.

execute_command({
  command: "ls -la",
  pane: "claude-terminal",  // optional, defaults to "claude-terminal"
  captureOutput: true       // optional, defaults to true
})

2. Create Pane

Creates a new tmux pane with a specific name.

create_pane({
  name: "my-pane",         // optional, defaults to "claude-terminal"
  split: "horizontal"      // optional: "horizontal" or "vertical"
})

3. Capture Output

Captures recent output from a tmux pane.

capture_output({
  pane: "claude-terminal",  // optional
  lines: 100               // optional, number of lines to capture
})

4. List Panes

Lists all available tmux panes.

list_panes()

5. Send Keys

Send text to a tmux pane without executing it (useful for pre-filling commands).

send_keys({
  text: "git push origin main",
  pane: "claude-terminal",  // optional, defaults to directory-specific pane
  enter: false             // optional, set to true to also send Enter
})

6. Launch Background Task

Create a background pane for running Claude with a specific research/analysis task.

launch_background_task({
  task: "Research TypeScript 5.x features and create a summary",
  outputFile: "typescript-features.md",  // saved to .t-pane/tasks/
  timeout: 300000                       // optional, default 5 minutes
})

7. Check Background Tasks

Check the status of all background tasks.

check_background_tasks()

How It Works

1. Command Execution: When Claude executes a command, it's wrapped with unique markers:

   echo '===CMD_${commandId}_START==='; <your-command>; echo '===CMD_${commandId}_END==='
   

2. Output Capture: The server:

   • Finds the START marker in the tmux buffer
   • Calculates how many lines from the end to capture
   • Extracts only the output between markers
   • Returns clean output to Claude

3. Interactive Prompt Detection: When a command requires user input:

   • Detects common prompt patterns (password, username, yes/no, etc.)
   • Returns a special response alerting Claude that user interaction is needed
   • Claude will inform you to switch to the tmux pane and provide input

4. Command Logging: All commands and outputs are logged to:

   • Primary location: .t-pane/logs/ in the current working directory
   • Fallback location: ~/.t-pane/logs/{directory-hash}/ if local directory is not writable
   • Format: JSON Lines (one JSON object per line)
   • Includes: timestamp, command, output (truncated if >2KB), exit code, duration, directory
   • Disable with: export T_PANE_DISABLE_LOGGING=true

5. Efficiency: This approach handles commands with any output size (even 100k+ lines) efficiently by:

   • Using unique IDs to avoid collision
   • Capturing from the end of the buffer
   • Only extracting the relevant portion

Example Session

When Claude uses this server, you'll see:

• A new tmux pane with directory-specific naming (e.g., claude-t-pane for the t-pane directory)
• Each directory gets its own dedicated pane
• Multiple Claude instances working in different directories won't interfere
• All commands Claude executes appear in the appropriate pane
• You can interact with the same terminal
• Command history is preserved per directory

Development

# Watch mode for development
npm run watch

# Build for production
npm run build

Requirements

• tmux installed and available in PATH
• Must be run inside a tmux session for full functionality
• Node.js 18+

Troubleshooting

1. "tmux is not installed": Install tmux using your package manager
2. "Not running inside a tmux session": Start tmux first with tmux new-session
3. Commands not appearing: Check that the pane name matches what Claude is using

Directory-Aware Sessions

The t-pane server creates separate tmux panes for each directory:

• Pane names are based on the last 2 directory components (e.g., claude-mcp-servers-t-pane)
• Each Claude instance working in a different directory gets its own pane
• Logs are stored locally in each project directory
• Multiple Claude instances can work simultaneously without interference

Interactive Prompts

When a command requires user input (like git push asking for credentials), the server will:

1. Detect the interactive prompt
2. Pre-fill the command in the tmux pane (without pressing Enter)
3. Return a message to Claude indicating user interaction is needed
4. You'll see a message like: "⚠️ User interaction required in tmux pane"
5. Switch to the tmux pane where the command is pre-filled and ready for you to review/execute

Command Logging

By default, all commands are logged to .t-pane/logs/ in the current directory:

{"timestamp":"2024-06-27T10:30:00Z","command":"git status","output":"...","exitCode":0,"duration":150,"directory":"/path/to/project"}

To disable logging:

export T_PANE_DISABLE_LOGGING=true

Background Tasks (Experimental)

The t-pane server can launch Claude instances in background panes for research or analysis:

1. Launch a task: Creates a new pane with task instructions
2. Manual execution: Switch to the pane and run claude to start the task
3. Output location: Results are saved to .t-pane/tasks/
4. Status tracking: Use check_background_tasks() to monitor progress

This feature is experimental and requires manual Claude invocation in the created pane.

Future Enhancements

• Interactive prompt detection
• Command logging
• Background task execution (experimental)
• Automatic Claude invocation for background tasks
• Support for multiple concurrent commands
• Progress indicators for long-running commands
• Integration with /resume for session continuity

8. Read File

Read file contents using cat/head commands in the tmux pane.

9. Edit File

Edit files using sed in the tmux pane (visible to user).