tmux-aware

# TMUX-Aware Process Management

## Overview

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

## Key Principles

1. **Never clutter the current window** - Always create panes in the "claude-controlled" window
2. **Find panes by name** - Search for existing panes/windows by title, not by process
3. **Verify commands worked** - Capture output after sending commands to detect errors
4. **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

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

### Step 2: Create window if needed

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

### Step 3: Create a named pane for the service

```bash
# 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

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

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

```bash
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

```bash
tmux list-panes -a -F '#{wi