---
alwaysApply: true
---

# Claude Delegation via tmux MCP Server

## Overview

This guide explains how to delegate tasks to Claude Code (claude-yolo) using the tmux MCP server. claude-yolo is a version of Claude Code that automatically performs many tasks in the background without needing as much user interaction as regular claude code (claude). This setup allows you to run Claude in a persistent tmux session and communicate with it programmatically through MCP server tools.

## Prerequisites

### Required Software
- **tmux**: Terminal multiplexer for persistent sessions
- **claude-yolo**: Claude Code CLI tool
- **Node.js/npm**: For running the tmux MCP server
- **Cursor IDE**: With MCP server support

### MCP Server Configuration

#### ~/.cursor/mcp.json or ./cursor/mcp.json Configuration

Add a tmux MCP server to your MCP configuration.

```json
{
  "mcpServers": {
    "tmux": {
      "command": "npx",
      "args": ["-y", "tmux-mcp@latest"]
    }
  }
}
```

## Step-by-Step Setup

### Step 1: Install Required Tools

1. **Install tmux** (if not already installed):
   ```bash
   # macOS
   brew install tmux

   # Ubuntu/Debian
   sudo apt-get install tmux

   # CentOS/RHEL
   sudo yum install tmux
   ```

2. **Install claude-yolo**:
   ```bash
   # Install claude-yolo CLI
   npm install -g claude-yolo
   ```

3. **Verify installations**:
   ```bash
   tmux -V
   claude --version  # or claude-yolo --version
   ```

### Step 2: Configure MCP Servers

1. **Create ~/.cursor/mcp.json** with the configuration shown above
2. **Create .claude/settings.local.json** in your project root with the permissions shown above
3. **Restart Cursor IDE** to load the new MCP server configurations

### Step 3: Start Your First Session

Use the MCP tools to create and manage your tmux session:

```javascript
// Create a new tmux session
mcp_tmux_create-session({
  name: "claude-session"
})

// Create a window in the session
mcp_tmux_create-window({
  sessionId: "$0",  // Use the session ID returned above
  name: "claude-window"
})

// Start claude-yolo in the session with isolated config
mcp_tmux_execute-command({
  paneId: "%0",  // Use the pane ID
  command: "cd /path/to/your/project && CLAUDE_CONFIG_DIR=$(pwd) claude-yolo",
  rawMode: true
})
```

At this point BEFORE passing instructions to Claude you must always open the tmux screen in a backgrounded terminal command so that the user can see the Claude session:
bash({
  command: "tmux attach-session -t claude-session"
})

// use bash to sleep for 5 seconds to let claude-yolo start
bash({
  command: "sleep 5"
})



## Communication Protocol

### Sending Messages to Claude

1. **Send the message content**:
   ```
   mcp_tmux_execute-command({
     paneId: "%0",
     command: "Your message to Claude here",
     rawMode: true
   })
   ```

2. **Submit the message** (send empty string):
   ```
   mcp_tmux_execute-command({
     paneId: "%0",
     command: "",  // Empty string to submit
     rawMode: true
   })
   ```

### Receiving Responses from Claude

1. **Check for responses**:
   ```
   mcp_tmux_capture-pane({
     paneId: "%0",
     lines: 30  // Number of lines to capture. Generally 30 is enough.
   })
   ```

2. **Monitor ongoing execution**:
   - Look for status indicators like "Incubating…", "Smooshing…", etc.
   - Wait for completion indicators or prompts

## Example Workflow

### Bootstrapping the Session

// Check for existing tmux session
mcp_tmux_list-sessions()

// If no session exists, create one
// Note: Creating a session automatically creates one window (@0) and one pane (%0)
mcp_tmux_create-session({
  name: "claude-session"
})

// Check for existing pane in the default window
mcp_tmux_list-panes({ windowId: "@0" })

// Note: We don't need to create additional windows or panes
// The session comes with one window (@0) and one pane (%0) by default

// check if claude-yolo is already running using capture-pane and start it if it is not running
mcp_tmux_capture-pane({
  paneId: "%0",
  lines: 30
})

mcp_tmux_execute-command({
  paneId: "%0",
  command: "cd /path/to/your/project && CLAUDE_CONFIG_DIR=/Users/andy/.claude-project-isolated claude-yolo", // ALWAYS cd to the project root first!
  rawMode: true
})

Once you have a pane running claude-yolo, you must ALWAYS open the tmux screen in a backgrounded terminal command so that the user can see the Claude session:
bash({
  command: "tmux attach-session -t claude-session"
})

Once you have a session running you can skip to just using capture-pane to check that it's still running.
// Wait for completion (UI tests take longer)
mcp_tmux_capture-pane({
  paneId: "%0",
  lines: 30
})
### Check the README.md for typos

```
// Populate the instructions for claude
mcp_tmux_execute-command({
  paneId: "%0",
  command: "Check the README.md for typos",
  rawMode: true
})

// Submit the instructions
mcp_tmux_execute-command({
  paneId: "%0",
  command: "",
  rawMode: true
})

// Wait for execution to complete
// Check every 5-10 seconds
mcp_tmux_capture-pane({
  paneId: "%0",
  lines: 30
})
```

### Running UI Tests

```javascript
// Populate the instructions for claude
mcp_tmux_execute-command({
  paneId: "%0",
  command: "Run the UI tests using the XCodeBuild MCP server",
  rawMode: true
})

// Submit the instructions
mcp_tmux_execute-command({
  paneId: "%0",
  command: "",
  rawMode: true
})

// Wait for completion (UI tests take longer)
mcp_tmux_capture-pane({
  paneId: "%0",
  lines: 30

## Troubleshooting

### Debug Commands

```javascript
// Get session info
mcp_tmux_list-sessions({ random_string: "dummy" })

// Get window info (session creates one window by default)
mcp_tmux_list-windows({ sessionId: "$0" })

// Get pane info (default window has one pane by default)
mcp_tmux_list-panes({ windowId: "@0" })

// Capture full pane content for debugging
mcp_tmux_capture-pane({
  paneId: "%0",
  lines: 1000
})
```