cmux-tui: rank agent list by who needs you

Merged
TE
17d ago
+957-196

cmux agent list printed agents in the daemon's order with no sense of which ones are waiting on you. It now ranks them by who needs you, adds a needs-me shortcut, sort and limit options, and shows each agent's age, title, folder and counts by state. This brings the useful parts of the classic-app cmux sessions live (#15319) to cmux-next. #15319 will be closed separately.

$ cmux agent list
1 blocked · 2 working · 3 idle · 0 done
STATE    AGE  AGENT   TITLE       FOLDER      TERMINAL
blocked  2m   claude  fix tests   ~/src/cmux  term_…
working  5s   codex   -           -           term_…
  • Default order changed (--sort needs-me): rows used to come in the daemon's order. Now blocked agents come first, then working, then idle and done together, then unknown. Within each group the most recently updated agent comes first, and ties go by agent id. --sort recent ignores state. --sort none restores the daemon's order.
  • --needs-me: sends state: blocked to the daemon. It's refused with any other --state.
  • --limit <n>: keeps the first n ranked rows. The counts still cover every listed agent, and the human summary line adds (showing n of m).
  • Rows: AGE counts from updated_at_ms, which is the agent's last report. The public snapshot doesn't carry the roster's since_ms, so the age restarts on a same-state report. TITLE and FOLDER come from a terminal.list read on the same connection. If that read is refused or fails, the row just leaves them out.
  • --json is still a bare array. It is the ranked agents, each the unchanged AgentSnapshot plus age_ms and, when its terminal is listed, title and cwd. web/scripts/cloud-vm/dogfood-probes.mjs reads that array. --json --counts prints {"agents": [...], "counts": {"blocked","working","idle","done","unknown","total"}} instead. --jsonl is one agent per line either way.
  • Unchanged: --state, --terminal and --all-sessions work as before. --all-sessions adds a SESSION column and joins every session's terminals.

The ranking is done on the client (cli/wire/agent_roster.rs, through a new ResponseView::AgentRoster, and cli/command/agent_list.rs for parsing). The agent.list wire operation, its schema and the MCP tool are unchanged. The spec is in cmux-tui/spec/cli.md § Agent list and docs/cli-contract.md.

Verification

  • Tests were committed before the feature in 71d7f2b. They cover the default order with its group, recency and id tie-breaks, recent and none, a limit with counts, the JSON shapes (bare array, --counts object, --jsonl, age, title, cwd, a missing terminal, clock skew), the human summary, empty and session-column output, age units, and flag parsing. The red run at 71d7f2b wasn't recorded separately.
  • PR CI doesn't run the cmux-tui crate's Rust tests (same-tree cmux-tui is skipped), so focused cmux-tui.yml runs on the exact head cover them. Results are in a PR comment.
  • Earlier at e57fcb6, a local Linux cargo test -p cmux-tui --lib run of the agent-list, agent-roster and MCP parity tests passed (16 tests).
  • scripts/check-spec-inventory.py, scripts/check-resource-api-boundary.py and rustfmt --check pass.

Changelog

  • Changed: cmux agent list ranks agents by who needs you, adds --needs-me, --sort, --limit and --counts, and shows age, title, folder and counts by state.

🤖 Generated with Claude Code