Session lifecycle management for Claude Code tmux sessions
create → running → [review/send-message] → kill
↑ |
└───────────────────────┘
(iterate)
scripts/session-create.sh my-agent ~/project --interactive
scripts/session-attach.sh my-agent
scripts/session-create.sh my-agent ~/project "implement the auth module" --skip-permissions
scripts/session-create.sh my-agent ~/project "review the codebase" --model opus --skip-permissions
# Table format
scripts/session-list.sh
# JSON for programmatic use
scripts/session-list.sh --json
# Just names
scripts/session-list.sh --quiet
# 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
# Tail with auto-refresh
scripts/pane-tail.sh my-agent --follow 3
# Multi-agent dashboard
scripts/multi-agent-dashboard.sh my-swarm --watch 5
scripts/session-kill.sh my-agent
Default: sends Ctrl-C, waits 5 seconds, then force kills.
scripts/session-kill.sh my-agent --force
scripts/session-kill.sh my-agent --timeout 15
scripts/cleanup.sh "test-*" # Kill all test sessions
scripts/cleanup.sh "swarm" # Kill sessions matching "swarm"
scripts/cleanup.sh --all # Kill ALL sessions (caution!)
scripts/cleanup.sh "old-*" --dry-run # See what would be killed
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.
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"
All scripts validate session existence and exit with code 1 if not found.
session-attach.sh supports prefix matching:
# If "my-long-session-name" exists
scripts/session-attach.sh my-long # Will match and attach