TMUX-Aware Process Management

Overview

When running inside a TMUX session, manage services in dedicated panes without cluttering the current view. All Claude-created panes go in a dedicated "claude-controlled" window.

For the visual workflow diagram, see ./references/workflow.mmd.

Key Principles

Never clutter the current window - Always create panes in the "claude-controlled" window
Find panes by name - Search for existing panes/windows by title, not by process
Verify commands worked - Capture output after sending commands to detect errors
Ask when uncertain - If a pane can't be found by name, list options and ask the user

Starting a Service

When the user asks to start a service (e.g., "start the API server"):

Step 1: Check for claude-controlled window

# List windows, look for claude-controlled
tmux list-windows -F '#{window_index}:#{window_name}' | grep ':claude-controlled$'

Step 2: Create window if needed

# Create the claude-controlled window
tmux new-window -n "claude-controlled"

Step 3: Create a named pane for the service

# If claude-controlled window already has panes, split it
tmux split-window -t claude-controlled -v

# Name the pane after the service
tmux select-pane -t claude-controlled -T "api-server"

Step 4: Send the start command

tmux send-keys -t "claude-controlled:0.api-server" "npm run dev" Enter

Step 5: Verify it started (capture output after brief delay)

sleep 2
tmux capture-pane -t "claude-controlled:0.api-server" -p -S -20

Check the output for errors. Report success or detected issues.

Naming Convention

Window: claude-controlled (all Claude-created panes go here)
Pane titles: Lowercase, hyphenated, match the service (e.g., api-server, redis, vite-dev, postgres)

Finding Existing Panes

When the user asks to interact with a process (e.g., "check the redis logs"):

Step 1: List panes with names

tmux list-panes -a -F '#{window_name}:#{pane_index}:#{pane_title}'

Step 2: Search for match

Look for exact or partial match (e.g., "redis" matches pane titled "redis" or "redis-server").

Step 3: If found

Interact with it:

# Capture output
tmux capture-pane -t "window:pane" -p -S -50

# Send command (e.g., restart)
tmux send-keys -t "window:pane" C-c  # Stop first
tmux send-keys -t "window:pane" "redis-server" Enter  # Restart

Step 4: If not found

List available panes and ask:

I couldn't find a pane named 'redis'. Here's what I see:

[0:main] pane 0: "zsh"

[1:dev] pane 0: "vim"

[2:claude-controlled] pane 0: "api-server"

Which one should I use, or should I create a new one?

Capturing Output

Use capture-pane to read recent output:

# Last 50 lines
tmux capture-pane -t "pane-target" -p -S -50

# Last 100 lines (for more context)
tmux capture-pane -t "pane-target" -p -S -100

Error Detection

After sending commands, capture output and look for common error patterns:

Error:, ERROR, error:
Exception, exception
Failed, FAILED, failed
Cannot, cannot
Exit codes in prompts
Stack traces

Report issues proactively: "Started the server but detected an error: [snippet]"

Stopping a Service

# Send Ctrl+C to stop
tmux send-keys -t "pane-target" C-c

# Verify it stopped
sleep 1
tmux capture-pane -t "pane-target" -p -S -10

Multiple Services

When running multiple services:

Split panes vertically (-v) for side-by-side logs
Name each pane after its service for easy targeting
Use tmux select-layout -t claude-controlled even-vertical to rebalance
If more than 3 services, consider separate windows instead of more pane splits

For the full command reference (window/pane management, sending commands, capturing output, target syntax), see ./references/commands.md.

Example Workflow

User: "Start a Redis server"

Check for claude-controlled window (exists)
Create new pane: tmux split-window -t claude-controlled -v
Name it: tmux select-pane -T "redis"
Start Redis: tmux send-keys -t "claude-controlled:redis" "redis-server" Enter
Wait and capture: sleep 2 && tmux capture-pane -t "claude-controlled:redis" -p -S -20
Report: "Started Redis server in pane 'redis' (claude-controlled window). Server is ready on port 6379."

User: "Check if Redis is still running"

List panes, find "redis"
Capture output: tmux capture-pane -t "claude-controlled:redis" -p -S -30
Report status based on output

When NOT to Use

One-off commands that don't need a persistent pane (e.g., git status, ls)
User's existing layout - don't create panes in the user's current window
Non-tmux environments - if tmux detection fails, fall back to standard Bash
Quick checks where capturing output with Bash tool is sufficient

Cleanup

When the user's task is complete:

Don't auto-kill panes - the user may want to keep services running
Offer cleanup if asked: tmux kill-window -t claude-controlled
Report what's running: List active panes so the user can decide
If you started a service and the task failed, mention the pane is still running

tmux-aware