Skip to content

[Feature]: Sessions page: roster overview tiles, kind avatars, and context-usage meters #102517

Description

@steipete

Summary

Redesign the Control UI Sessions page main view: overview stat tiles above the roster, per-row kind avatars with live-run dots, compact token values with context-window usage meters, initial-load skeleton rows, and clearer empty states.

Problem to solve

The Sessions page renders a flat data table with weak hierarchy:

  • Fleet state (how many sessions are live, unread, how much context is burning) is invisible without reading every row; the header only says "N sessions".
  • The Tokens column prints raw integers (123456 / 200000), which is hard to scan, and context pressure (session close to the model context window) is not surfaced at all — it only exists implicitly in the drawer.
  • Rows have no visual identity anchor; key, kind, and status all compete as plain text/pills.
  • The first load flashes the "No sessions found." empty state before the first sessions.list result arrives.
  • On narrow layouts, long label chips can paint over the sticky status column.

Proposed solution

  • Overview tiles (Sessions / Live / Unread / Tokens) computed from the loaded roster, with live/unread tiles picking up semantic tones when non-zero.
  • Kind avatar tile per row (direct/group/cron/global glyphs, tint mapping mirroring the kind badges) with a pulsing status dot when the session has an active run.
  • Tokens column: compact 156k / 200k values plus a context-usage meter with ok/warn/danger tones at 65%/85%, exact numbers in the tooltip and drawer.
  • Skeleton shimmer rows during the initial load instead of the flashing empty state.
  • Icon-led empty states; label chips ellipsize instead of overflowing the sticky columns on mobile.

Alternatives considered

  • Card-based list instead of a table: loses density, bulk selection, and column sorting; the table layout is load-bearing for operators.
  • Keeping counts as header text: too weak to scan and does not scale to tokens/unread.
  • Surfacing context usage only in the row drawer: stays hidden exactly when an operator needs to spot a session near its context limit.

Impact

  • Affected: anyone operating the Control UI Sessions page (multi-agent/multi-channel deployments especially).
  • Severity: quality-of-life; no functional loss today, but state discovery requires opening drawers row by row.
  • Frequency: every Sessions page visit.
  • Consequence: slower triage of live/stuck/context-saturated sessions.

Evidence/examples

Current behavior: ui/src/pages/sessions/view.ts renders the flat table; formatSessionTokens prints raw integers; empty state renders while loading && !result.

Redesign proof shots (mocked Gateway, deterministic data):

desktop dark
row drawer

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low-priority cleanup, docs, polish, ergonomics, or speculative work.clawsweeper:linked-pr-openClawSweeper found an open linked pull request for this issue.clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.enhancementNew feature or requestimpact:ux-frictionUser-facing flow adds avoidable confusion or support burden without fully blocking progress.issue-rating: 🌊 off-meta tidepoolIssue quality rating does not apply to this item.maintainerMaintainer-authored PR

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions