stacklok / stacklok/mecatl

feat(mecatui): add an interactive token-usage breakdown panel

Open
#693 0 comments 0 reactions 0 assignees View on GitHub

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/window is 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

  • /tokens opens 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 /tokens and 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.md and 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.