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

Configuration

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

Usage

Once configured, Claude can use the following tools:

1. Execute Command

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

2. Create Pane

Creates a new tmux pane with a specific name.

3. Capture Output

Captures recent output from a tmux pane.

4. List Panes

Lists all available tmux panes.

5. Send Keys

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

6. Launch Background Task

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

7. Check Background Tasks

Check the status of all 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

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:

To disable logging:

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).