tmux-spawn

gistfile1.txt

Skill goes in ~/.claude/skills
tmux-spawn.md Command goes in ~/.claude/commands

SKILL.md

name	description
tmux-claude	Expert guidance for managing multiple Claude Code sessions in tmux. Helps with creating and organizing windows/panes for parallel AI coding sessions, navigating between sessions, naming conventions, and efficient multi-agent workflows. Use when users need help running multiple Claude Code instances, organizing tmux layouts for AI-assisted development, or orchestrating parallel coding tasks.

tmux Multi-Session Claude Code Expert

You are an expert at managing multiple Claude Code sessions using tmux. You help users efficiently run, organize, and navigate parallel AI coding sessions.

Core Concepts

Why Multiple Claude Code Sessions?

Running multiple Claude Code sessions in tmux enables:

• Parallel tasks: Work on multiple features/bugs simultaneously
• Separation of concerns: Isolate different parts of a codebase
• Agent orchestration: Run specialized agents in parallel
• Context preservation: Keep each session focused on its task
• Easy switching: Navigate between tasks without losing state

tmux Hierarchy

tmux server
└── Sessions (named groups of windows)
    └── Windows (tabs within a session)
        └── Panes (splits within a window)

For Claude Code, the typical setup:

• One session per project or workstream
• Multiple windows for different tasks (feature, bugfix, research)
• Panes for side-by-side Claude Code instances or reference material

Essential Commands

Session Management

# Create new session
tmux new-session -s claude-project

# Create session with specific working directory
tmux new-session -s claude-project -c ~/projects/my-app

# List sessions
tmux list-sessions
tmux ls

# Attach to existing session
tmux attach -t claude-project

# Kill session
tmux kill-session -t claude-project

# Rename session
tmux rename-session -t old-name new-name

Window Management

# Create window with name
tmux new-window -n "feature-auth"

# Create window with command
tmux new-window -n "claude-feature" "claude"

# List windows
tmux list-windows

Pane Management

# Horizontal split (top/bottom)
tmux split-window -v

# Vertical split (left/right)
tmux split-window -h

# Resize panes
tmux resize-pane -D 10  # Down
tmux resize-pane -U 10  # Up
tmux resize-pane -L 10  # Left
tmux resize-pane -R 10  # Right

# Kill pane
tmux kill-pane

Sending Commands to Panes

# Send command to specific pane
tmux send-keys -t <session>:<window>.<pane> "command" Enter

# Examples
tmux send-keys -t claude:0.0 "claude" Enter
tmux send-keys -t claude:feature.1 "cd ~/project && claude" Enter

# Send to all panes in window (synchronize)
tmux set-window-option synchronize-panes on
# Type command, it goes to all panes
tmux set-window-option synchronize-panes off

Claude Code Multi-Session Workflows

Workflow 1: Parallel Feature Development

Create separate windows for each feature branch:

#!/bin/bash
# Create a multi-feature development session

SESSION="project-dev"
PROJECT_DIR="$HOME/projects/my-app"

# Create session with first window
tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR" -n "main"

# Create feature windows
tmux new-window -t "$SESSION" -n "feature-auth" -c "$PROJECT_DIR"
tmux new-window -t "$SESSION" -n "feature-api" -c "$PROJECT_DIR"
tmux new-window -t "$SESSION" -n "bugfix-123" -c "$PROJECT_DIR"

# Start Claude in each window
tmux send-keys -t "$SESSION:feature-auth" "git checkout feature/auth && claude" Enter
tmux send-keys -t "$SESSION:feature-api" "git checkout feature/api && claude" Enter
tmux send-keys -t "$SESSION:bugfix-123" "git checkout bugfix/123 && claude" Enter

# Attach to session
tmux attach -t "$SESSION"

Workflow 2: Multi-Agent Setup

Run multiple specialized agents in panes:

#!/bin/bash
# Multi-agent window with different Claude Code specializations

SESSION="agents"
PROJECT_DIR="$HOME/projects/my-app"

# Create session
tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR" -n "agents"

# Split into 4 panes (2x2 grid)
tmux split-window -v -t "$SESSION:agents"
tmux split-window -h -t "$SESSION:agents.0"
tmux split-window -h -t "$SESSION:agents.2"

# Start different tasks in each pane
tmux send-keys -t "$SESSION:agents.0" "claude 'Review the recent changes for code quality'" Enter
tmux send-keys -t "$SESSION:agents.1" "claude 'Security review of authentication module'" Enter
tmux send-keys -t "$SESSION:agents.2" "claude 'Analyze test coverage and suggest improvements'" Enter
tmux send-keys -t "$SESSION:agents.3" "claude" Enter  # Main implementation session

tmux attach -t "$SESSION"

Workflow 3: Worktree Multi-Session

For git worktrees (parallel branches in separate directories):

#!/bin/bash
# Multi-worktree Claude Code session

SESSION="worktrees"
MAIN_DIR="$HOME/projects/my-app"

# Ensure worktrees exist
git -C "$MAIN_DIR" worktree add ../my-app-feature1 feature/branch1 2>/dev/null || true
git -C "$MAIN_DIR" worktree add ../my-app-feature2 feature/branch2 2>/dev/null || true

# Create session
tmux new-session -d -s "$SESSION" -c "$MAIN_DIR" -n "main"

# Create windows for each worktree
tmux new-window -t "$SESSION" -n "feature1" -c "${MAIN_DIR}/../my-app-feature1"
tmux new-window -t "$SESSION" -n "feature2" -c "${MAIN_DIR}/../my-app-feature2"

# Start Claude in each
tmux send-keys -t "$SESSION:main" "claude" Enter
tmux send-keys -t "$SESSION:feature1" "claude" Enter
tmux send-keys -t "$SESSION:feature2" "claude" Enter

tmux attach -t "$SESSION"

Workflow 4: Code + Reference Layout

Main Claude Code with reference panes:

#!/bin/bash
# Layout: Large Claude pane with smaller reference panes

SESSION="dev"
PROJECT_DIR="$HOME/projects/my-app"

tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR" -n "work"

# Create layout: large left pane (70%), small right column
tmux split-window -h -t "$SESSION:work" -p 30

# Split right column into 3 panes
tmux split-window -v -t "$SESSION:work.1"
tmux split-window -v -t "$SESSION:work.2"

# Left: Claude Code (main work)
# Right-top: logs
# Right-middle: git status
# Right-bottom: tests

tmux send-keys -t "$SESSION:work.0" "claude" Enter
tmux send-keys -t "$SESSION:work.1" "tail -f logs/app.log" Enter
tmux send-keys -t "$SESSION:work.2" "watch -n 5 git status" Enter
tmux send-keys -t "$SESSION:work.3" "npm test --watch" Enter

tmux attach -t "$SESSION"

Naming Conventions

Use consistent, descriptive names:

Session Names

<project>-<purpose>

Examples:

• myapp-dev - Main development
• myapp-review - Code review tasks
• infra-terraform - Infrastructure work
• docs-update - Documentation

Window Names

<task-type>-<detail>

Examples:

• feat-auth - Authentication feature
• fix-api-timeout - API timeout bugfix
• review-pr-123 - PR review
• research-caching - Research task

Common Operations

Starting Fresh Multi-Session Setup

#!/bin/bash
cd ~/projects/my-app

# Kill existing session if present
tmux kill-session -t dev 2>/dev/null

# Create new session
tmux new-session -d -s dev -n "main"

# Add windows
tmux new-window -t dev -n "claude-1"
tmux new-window -t dev -n "claude-2"
tmux new-window -t dev -n "logs"

# Start Claude in claude windows
tmux send-keys -t dev:claude-1 "claude" Enter
tmux send-keys -t dev:claude-2 "claude" Enter

# Attach
tmux attach -t dev

Checking What's Running

# List all sessions with windows
tmux list-sessions
tmux list-windows -a

# See all panes in current session
tmux list-panes -s

Graceful Cleanup

# Close a specific Claude session (will prompt in Claude)
tmux send-keys -t dev:claude-1 "/exit" Enter

# Kill pane without prompt (if Claude is stuck)
tmux kill-pane -t dev:claude-1.0

# Kill entire session
tmux kill-session -t dev

Troubleshooting

Claude Code Won't Start in Pane

# Check if pane is ready
tmux list-panes -t <session>:<window>

# Ensure directory exists
tmux send-keys -t <target> "pwd" Enter

# Check for shell initialization issues
tmux send-keys -t <target> "echo $SHELL" Enter

Pane Frozen/Unresponsive

# Try sending interrupt
tmux send-keys -t <target> C-c

# If truly frozen, kill pane
tmux kill-pane -t <target>

Window Numbering Gaps

# Renumber windows starting from 1
tmux move-window -r

Status Commands

/tmux-claude-status

Show all Claude Code sessions across tmux with idle time and token usage:

=== Claude Code Sessions ===

[dev:1] cc-fix-auth
  Idle: 2m
  Tokens: 12.5k tokens
  Last: I've updated the authentication handler...

[dev:2] cc-api-refactor
  Idle: 45s
  Last: Let me run the tests to verify...

Useful for:

• Monitoring parallel sessions
• Finding idle sessions to close
• Checking token consumption across agents

Quick Reference Card

Action	Command
New session	tmux new -s name
Attach session	tmux attach -t name
New window	tmux new-window -n name
Split horizontal	tmux split-window -v
Split vertical	tmux split-window -h
Kill pane	tmux kill-pane
Kill session	tmux kill-session -t name
List sessions	tmux ls
Send keys	tmux send-keys -t target "cmd" Enter
Sync panes	tmux setw synchronize-panes on
Spawn session	/tmux-spawn <task>
Session status	/tmux-claude-status

Best Practices

1. Name everything: Use descriptive session and window names
2. One task per window: Keep Claude sessions focused
3. Use panes sparingly: More than 4 panes gets hard to manage
4. Save layouts: Create scripts for your common setups
5. Regular cleanup: Kill unused sessions to avoid confusion

Integration with Other Skills

With /worktree

# Create worktree, then start Claude session
/worktree feature-xyz
# Opens Claude in worktree, create matching tmux window

With /review-pr

# Dedicated review window
tmux new-window -n "review-pr-123"
tmux send-keys "claude '/review-pr 123'" Enter

With Beads

# Window per beads issue
tmux new-window -n "beads-42"
tmux send-keys "claude '/beads:start-work 42'" Enter

Spawning Sessions from Current Context

Use /tmux-spawn <task> to create a new window with a seeded Claude Code session:

/tmux-spawn fix the authentication timeout bug

This creates a new tmux window named cc-fix-auth with Claude Code started and seeded with:

• Current working directory
• Current git branch
• The task description

Manual Spawn Pattern

If you need more control:

# Get current context
BRANCH=$(git branch --show-current 2>/dev/null || echo "none")
DIR=$(basename "$PWD")

# Create window with seeded Claude
tmux new-window -n "cc-task" -c "$PWD" \
  "claude 'Starting work in $DIR on branch $BRANCH. Task: <your task here>'"

Passing More Context

To seed with specific files or deeper context:

# Seed with specific files to review
tmux new-window -n "cc-review" -c "$PWD" \
  "claude 'Review these files for security issues: src/auth.ts, src/api/login.ts'"

# Seed with recent git changes
CHANGES=$(git diff --stat HEAD~3 | head -20)
tmux new-window -n "cc-recent" -c "$PWD" \
  "claude 'Recent changes to review: $CHANGES'"

Response Strategy

When helping users:

1. Understand their workflow: Single project or multi-project? Feature branches or worktrees?
2. Suggest appropriate structure: Sessions for projects, windows for tasks, panes for agents
3. Provide runnable commands: Give copy-paste ready commands
4. Create scripts when needed: For repeatable setups, provide shell scripts
5. Respect existing setup: Don't suggest killing their sessions without asking

tmux-spawn.md

description	arguments
Spawn a new tmux window with a Claude Code session seeded from current context	name description required task Brief description of the task for the new session (used for window name and seed prompt) true

Spawn a new tmux window with a fresh Claude Code session, seeded with context from the current session.

Steps

1. FIRST capture the current context before doing anything else:

   pwd
   git branch --show-current 2>/dev/null || echo ""

   Save the working directory and branch - these must be captured immediately to avoid issues if the user switches panes during execution.

2. Determine the window name from the task argument:

   • Take the first 2-3 words of the task
   • Convert to lowercase, replace spaces with hyphens
   • Prefix with "cc-" (e.g., "cc-fix-auth")

3. Construct the seed prompt for the new Claude Code session using the captured context:

   You are starting a new session in <captured directory> on branch <captured branch>.
   
   Task: <task description from user>
   
   Start by understanding the codebase context relevant to this task.
   

4. Create and execute the tmux command using the captured directory (not $PWD):

tmux new-window -n "<window-name>" -c "<captured-directory>" "claude '<seed-prompt>'"

IMPORTANT: Use the directory captured in step 1, not $PWD, to ensure the window spawns in the correct location.

5. Confirm to the user:
   • Tell them the window name that was created
   • Remind them how to switch to it (e.g., Prefix + n for next window, or Prefix + <number>)

Example

If the user runs /tmux-spawn fix authentication timeout bug:

• Window name: cc-fix-auth
• Seed prompt includes the full task description
• New Claude Code starts focused on that specific task

Notes

• The new session runs independently - changes in one don't affect the other
• Both sessions share the same filesystem, so be mindful of conflicting edits
• Consider using different git branches or worktrees for parallel work