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
-
Command Execution: When Claude executes a command, it's wrapped with unique markers:
echo '===CMD_${commandId}_START==='; <your-command>; echo '===CMD_${commandId}_END===' -
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
-
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
-
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
- Primary location:
-
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-panefor 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
- "tmux is not installed": Install tmux using your package manager
- "Not running inside a tmux session": Start tmux first with
tmux new-session - 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:
- Detect the interactive prompt
- Pre-fill the command in the tmux pane (without pressing Enter)
- Return a message to Claude indicating user interaction is needed
- You'll see a message like: "⚠️ User interaction required in tmux pane"
- 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:
- Launch a task: Creates a new pane with task instructions
- Manual execution: Switch to the pane and run
claudeto start the task - Output location: Results are saved to
.t-pane/tasks/ - 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
/resumefor 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).