cmax

Workspace priorities and busy-last sidebar ordering for cmux.

Two features:

• Priorities — P1–P4 on each workspace, shown as the workspace colour and as a matching coloured P1–P4 line under its name.
• Busy-last ordering — a daemon keeps the left sidebar sorted so workspaces you can act on stay on top and workspaces with a live agent sink to the bottom.

No cmux fork. Everything runs through the public cmux CLI, so it survives cmux auto-updates.

Install

./install.sh

That symlinks wp and ww into ~/.local/bin, creates the config and state directories, and appends the autostart block to ~/.zshrc (backing the file up first). Open a new cmux pane and the daemon starts. See docs/INSTALL.md for what it touches and how to undo it.

Usage

ww is the everyday command — set the current workspace's priority and name it in one go:

ww 1 test        # names the workspace "test", colours it red, marks it P1
ww 3             # re-marks it P3 in place, name untouched
ww clear         # drops the priority line and the colour
ww               # show the sorted sidebar

wp is the full interface, and is the one that can target another workspace:

wp                  # show the sorted sidebar (default command)
wp p1               # set the current workspace to P1
wp p2 workspace:3   # set another workspace, by ref, index, or id
wp clear            # remove the priority and its colour
wp status --json    # machine-readable view
wp sync             # run one reconcile pass now
wp pause / resume   # stop and restart automatic reordering
wp daemon           # run the reconcile loop in the foreground

Colours are #FF3B30 red (P1), #FF9500 orange (P2), #007AFF blue (P3), #8E8E93 gray (P4) — used for the workspace colour and for the P1–P4 status line in the same shade.

Ordering

Pinned workspaces keep their own tier at the top. Below them there are two tiers and nothing else:

Position	Tier	Contains
1	free	done, review, needs-input, idle — no distinction
2	working	an agent is actually running

Each tier sorts by priority, P1 first. Ties break by most recent activity, then id for stability.

"An agent is actually running" is decided by cmux's signal or by measured CPU. Both are needed: cmux only tracks the CLIs it wraps, so Cursor CLI reports not-running however hard it is working, while an interrupted agent reports running forever. The measurement settles both.

The hard-won rules behind that table are documented in docs/DESIGN.md: rank on signals rather than cmux's status lane, verify a "running" claim against the process, detect agents cmux has no hook for, and measure CPU rate rather than terminal writes.

Layout

Path	What
cmux_priority.py	the whole tool — CLI, reconciler, daemon, agent-liveness sampler
install.sh / uninstall.sh	reproducible install and teardown
tests/test_cmux_priority.py	offline tests — no cmux needed to run them
docs/DESIGN.md	decisions, and the alternatives that were tried and rejected
docs/INSTALL.md	install detail, verification, teardown
docs/zshrc-snippet.sh	the exact autostart block appended to ~/.zshrc