tmux-session-management - SKILL.md Agent Skill

name: tmux-session-management description: Session lifecycle management for Claude Code tmux sessions

Session Management

Session Lifecycle

create → running → [review/send-message] → kill
                     ↑                       |
                     └───────────────────────┘
                         (iterate)

Creating Sessions

Interactive session (human will attach)

scripts/session-create.sh my-agent ~/project --interactive
scripts/session-attach.sh my-agent

Automated session (agent sends a task)

scripts/session-create.sh my-agent ~/project "implement the auth module" --skip-permissions

With specific model

scripts/session-create.sh my-agent ~/project "review the codebase" --model opus --skip-permissions

Monitoring Sessions

List all sessions

# Table format
scripts/session-list.sh

# JSON for programmatic use
scripts/session-list.sh --json

# Just names
scripts/session-list.sh --quiet

Review session output

# Last 50 lines
scripts/session-review.sh my-agent --lines 50

# As JSON with metadata
scripts/session-review.sh my-agent --json

# Specific pane in multi-agent session
scripts/session-review.sh my-swarm --pane 2

Continuous monitoring

# Tail with auto-refresh
scripts/pane-tail.sh my-agent --follow 3

# Multi-agent dashboard
scripts/multi-agent-dashboard.sh my-swarm --watch 5

Stopping Sessions

Graceful stop (Ctrl-C + wait)

scripts/session-kill.sh my-agent

Default: sends Ctrl-C, waits 5 seconds, then force kills.

Immediate kill

scripts/session-kill.sh my-agent --force

Custom timeout

scripts/session-kill.sh my-agent --timeout 15

Cleanup

Pattern-based cleanup

scripts/cleanup.sh "test-*"        # Kill all test sessions
scripts/cleanup.sh "swarm"         # Kill sessions matching "swarm"
scripts/cleanup.sh --all           # Kill ALL sessions (caution!)

Dry run

scripts/cleanup.sh "old-*" --dry-run   # See what would be killed

State Files

Each session has a JSON state file at /tmp/tmux-skill/sessions/<name>.json:

{
  "name": "my-agent",
  "workdir": "/home/user/project",
  "task": "implement the auth module",
  "model": "sonnet",
  "startedAt": "2026-02-15T10:30:00Z",
  "interactive": false,
  "status": "running"
}

State files are automatically cleaned up when sessions are killed.

Error Handling

Session already exists

if tmux has-session -t my-agent 2>/dev/null; then
  echo "Session exists, killing first"
  scripts/session-kill.sh my-agent
  sleep 1
fi
scripts/session-create.sh my-agent ~/project "new task"

Session doesn't exist

All scripts validate session existence and exit with code 1 if not found.

Fuzzy name matching

session-attach.sh supports prefix matching:

# If "my-long-session-name" exists
scripts/session-attach.sh my-long    # Will match and attach