cmux Session Manager Skill

cmux Session Manager

Overview

Solves the problem of unlimited session accumulation in cmux with daily management automation. Covers the full session lifecycle: creation, management, and cleanup.

Role separation: This skill is for "daily management". For post-crash/power-loss session recovery, use the cmux-recover-sessions skill.

The Iron Law

READ BEFORE CLOSE. USER CONFIRMATION REQUIRED FOR NON-AUTO CLEANUP.

Phase 1 auto_cleanup (safe orphans, crashed sessions) runs without prompting. Phase 2 idle_cleanup and Phase 3 reorganize MUST be confirmed by the user before executing — never close or rename sessions without explicit approval, because a still-running task may look idle.

When to Use

End-of-day session hygiene (status dashboard, cleanup, reorganize)
Too many orphaned or idle sessions accumulated in cmux
Before starting new work — verify no stale workspaces are consuming resources

Not for crash recovery — use cmux-recover-sessions after a power loss or cmux crash.

Commands

`status` — Session Dashboard

Displays the status of all cmux sessions in a table.

How to run:

User requests cmux-session status or cmux status
Execute the following script:

bash "$(dirname "$0")/cmux-session-status"

Show the output to the user as-is

Output includes:

Summary header: Active / Waiting / Idle / Crashed / Orphaned counts
Session table: status icon, category, name, branch
Orphan section: classified as auto-removable / named / unsafe

`cleanup [--dry-run]` — Tidy + Reorganize

Performs 3-phase cleanup. Use --dry-run flag to preview the plan without executing.

How to run:

User requests cmux-session cleanup or cmux cleanup
Check dry-run preference, then execute:

bash "$(dirname "$0")/cmux-session-cleanup" [--dry-run]

The script outputs 3 JSON blocks separated by ---PHASE_SEPARATOR---
Parse each phase's JSON and process according to the Data Handoff Protocol below

Data Handoff Protocol

The cleanup script outputs 3 JSON blocks to stdout. Claude parses them and handles user interaction.

Phase 1: `auto_cleanup` (automatic — no user confirmation needed)

{"phase":"auto_cleanup","actions":[
  {"action":"kill_orphan","session":"12","type":"safe_numeric","executed":true},
  {"action":"close_crashed","ref":"workspace:69","name":"...","executed":true},
  {"action":"report_orphan","session":"psm_...","type":"safe_named","auto_delete":false}
]}

executed: true items are already done — report results to user
auto_delete: false items are informational — notify "this session was not auto-deleted"

Phase 2: `idle_cleanup` (user confirmation required)

{"phase":"idle_cleanup","sessions":[
  {"ref":"workspace:43","name":"...","state":"IDLE","branch":"main","category":"[TMP]"},
  {"ref":"workspace:67","name":"...","state":"WAITING","branch":"main","category":"[OPS]"}
]}

How to process:

If sessions array is empty, output "No idle sessions to clean up" and proceed to Phase 3
If sessions exist, show via AskUserQuestion (multiSelect: true):
- Each option label: [STATE] [CAT] name (branch)
- For user-selected sessions, execute:
```
cmux close-workspace --workspace <ref>
```

Phase 3: `reorganize` (user confirmation required)

{"phase":"reorganize","single_window_warning":true,"changes":[
  {"ref":"workspace:30","current_name":"...","proposed_name":"[DEV] ...","category":"[DEV]","target_window":"Active Dev"}
]}

How to process:

If single_window_warning: true, show warning:

"All workspaces are currently in a single window. Reorganizing will create category-based windows (Active Dev, Ops/Debug, Research)."
If changes array is empty, output "No sessions to reorganize"
If changes exist, show preview table then confirm via AskUserQuestion:
- "Yes, reorganize" / "Skip reorganization"

If confirmed, for each change:

cmux rename-workspace --workspace <ref> "<proposed_name>"
cmux set-status category "<category>" --workspace <ref>

Apply get_or_create_window logic for window moves:
- Find a window where another workspace of the same category already exists
- If none found, create a new window and move:
```
cmux move-workspace-to-window --workspace <ref> --window <window_ref>
```

State Detection

Uses the claude_code= field from cmux sidebar-state as the primary signal:

| claude_code= | State | Cleanup target | | ---------------- | ------- | --------------- | | Running | ACTIVE | No | | Needs input | WAITING | Phase 2 (optional) | | Idle | IDLE or CRASHED | Phase 2 (IDLE) / Phase 1 (CRASHED) | | (absent) | UNKNOWN | No |

Idle workspaces are further checked via read-screen for crash signatures (bun.report, segfault, etc.).

Category Classification

Priority (highest first):

[DEV]: Branch matches issue-N-<type>-* or legacy hub-N-<type>-* (feat, refactor, docs, test, chore, fix, perf, ci, build)
[OPS]: Name contains failure, debug, error, fix, incident, etc.
[RES]: Name contains analyze, investigate, compare, check, research, etc.
[TMP]: None of the above

Init Hook (Automation)

To auto-apply categories when new sessions are created, set up a cmux hook:

# cmux hook setup (category tagging on session-start)
cmux set-hook session-start 'bash -c "
  WS=\$CMUX_WORKSPACE_ID
  NAME=\$(cmux read-screen --workspace \$WS --lines 1 2>/dev/null | head -1)
  # classify and rename logic here
"'

Or add a session-start hook to Claude Code settings.json to call cmux-session-lib's classify_category for auto rename + set-status.

Report Schedule (Automation)

To receive a daily end-of-day report, use the /schedule skill:

/schedule "Run cmux-session status daily at 18:00 and send results to Slack"

The report includes status output + PR status from sidebar-state's pr= field + cleanup recommendations.

Troubleshooting

| Problem | Cause | Fix | | --------- | ------- | ----- | | "cmux is not running" | cmux app not running | Start cmux app | | "jq is required" | jq not installed | brew install jq | | Session state UNKNOWN | No claude_code in sidebar-state | Session may not be Claude Code | | 0 orphans | All tmux sessions owned by cmux | Normal — nothing to clean |

Rationalization Prevention

| Excuse | Reality | | -------- | --------- | | "I'll approve the cleanup without looking, it's probably fine" | An IDLE session may be a long-running task paused on input. Read the category/branch first. | | "Skip the dry-run, just execute" | Dry-run takes 2 seconds and prevents closing a session you actually wanted to keep. | | "The session looks crashed, auto-close it" | Only auto_cleanup (Phase 1) kills sessions automatically. Anything in Phase 2 needs your eyes. | | "Reorganize everything into one window" | Category windows make parallel work scannable. One-window mode is a regression. |

Integration

Workflow position: Daily session lifecycle management — runs in between work sessions.

[morning: status] → [work: many sessions] → [evening: cleanup] → [snapshot if needed]

Related skills:

cmux-save-sessions: Capture current state before running cleanup (recovery point)
cmux-resume-sessions: Restore a saved layout if cleanup removes too much
cmux-recover-sessions: Post-crash recovery (different scope — not for daily use)

Automation:

Init hook: auto-classify on session-start (see "Init Hook" section)
Report schedule: daily status via /schedule (see "Report Schedule" section)

Agent Skills: cmux Session Manager

Install this agent skill to your local

Skill Files