feat(mecatui): add an interactive token-usage breakdown panel
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
Problem
The mecatui footer exposes compact usage facets such as ↑ input, ↓ output, ⊕ cache write, and cache N%, but the symbols and their scopes are not self-explanatory. The footer also cannot show a useful breakdown across main work, Subagents, Parallel branches, and Team members.
Desired change
Add a /tokens TUI panel that explains and breaks down token usage. Make the footer usage segment clickable so mouse users can discover the panel directly; keep the slash command and the ? help legend so the feature is accessible and discoverable without a mouse.
Panel content
- Explain the footer symbols and their scopes:
ctx used/windowis current context occupancy, not a cumulative spend total.↑and↓are session-cumulative input and output.⊕is cache-write input, a subset of input rather than an extra total.cache N%is cache-read input divided by total input.
- Show raw usage facets for the main session and a grand total across the main session and all observed delegated work.
- Break usage down by Subagent, Parallel branch, and Team member, including running/completed state and enough identity/goal context to distinguish entries.
- When weighted-cost accounting from #687 exists, show its estimated-cost unit separately from raw tokens and name the active multiplier configuration.
Acceptance criteria
/tokensopens a dedicated, keyboard-navigable panel from mecatui.- Clicking the footer usage segment opens the same panel; click hit-testing must not interfere with existing footer actions or narrow-layout behavior.
- The
?overlay names/tokensand includes the symbol legend. - The panel distinguishes current context occupancy from cumulative usage and explains cache-write subset semantics.
- Raw usage is shown for the main session, each observed delegation child/branch/member, and a grand total.
- Grand totals do not double-count aggregate Team or Parallel totals and their constituent members/branches. Any unavoidable reporting gap is explicit rather than fabricated.
- Usage values come from authoritative relayed server events or a dedicated server projection; the UI does not independently infer provider usage or cache semantics.
- Rendering remains useful in narrow terminals and is covered by focused UI tests.
- Update
docs/tui.mdand public mecatui documentation.
Context
The current footer implementation is cmd/mecatui/ui/footer.go (renderUsageFacets), and the existing help overlay has the compact usage legend in cmd/mecatui/ui/help.go. The footer currently renders session-cumulative ↑/↓/⊕ totals while the context meter is current occupancy. See docs/tui.md “Footer usage segment” and #687.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with cmd/mecatui/ui/footer.go, especially renderUsageFacets, and cmd/mecatui/ui/help.go; read docs/tui.md and issue #687 for the existing usage model. Trace how authoritative usage events reach mecatui before planning the panel and focused UI tests. Done means /tokens, footer click handling, help text, narrow-terminal rendering, correct non-duplicated totals, and documentation updates are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend, cli, documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100