t-pane

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