# 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
```bash
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`):
```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.
```typescript
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.
```typescript
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.
```typescript
capture_output({
pane: "claude-terminal", // optional
lines: 100 // optional, number of lines to capture
})
```
### 4. List Panes
Lists all available tmux panes.
```typescript
list_panes()
```
### 5. Send Keys
Send text to a tmux pane without executing it (useful for pre-filling commands).
```typescript
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.
```typescript
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.
```typescript
check_background_tasks()
```
## How It Works
1. **Command Execution**: When Claude executes a command, it's wrapped with unique markers:
```bash
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
```bash
# 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:
```json
{"timestamp":"2024-06-27T10:30:00Z","command":"git status","output":"...","exitCode":0,"duration":150,"directory":"/path/to/project"}
```
To disable logging:
```bash
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
- [x] Interactive prompt detection
- [x] Command logging
- [x] 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).
