Skip to content

feat(cli): add /usage for per-turn token timeline#160

Merged
emal-avala merged 2 commits intomainfrom
feat/cmd-usage
Apr 22, 2026
Merged

feat(cli): add /usage for per-turn token timeline#160
emal-avala merged 2 commits intomainfrom
feat/cmd-usage

Conversation

@emal-avala
Copy link
Copy Markdown
Member

Summary

Adds `/usage` — a per-turn token timeline table.

# model input output cache read cache write
1 claude-opus-4-7 1204 430 0 8100
2 claude-opus-4-7 320 210 8100 0
1524 640 8100 8100

Followed by a one-line cache hit rate hint. `/cost` stays the go-to for aggregate cost; `/usage` is for "where did my tokens go this session?".

Why

`/cost` already shows per-model aggregates, but you can't see a timeline — was turn 3 the one that ate the context, or turn 7? The per-turn table answers that without needing to dig through tracing logs.

Handles mixed-model sessions: each row picks the model that turn actually used (the `model` field on the assistant message), falling back to the session's current model when it's missing.

Implementation

  • `collect_usage_rows` walks `state.messages`, picking `Message::Assistant` entries with a `Usage` payload. Turn index = 1-based counter over counted turns.
  • Column widths computed from the data (model column capped at 24 chars; long names truncated to the tail to keep family tokens visible).
  • Cache hit% = `cache_read / (input + cache_read + cache_write)` across the session.

Test plan

  • `cargo fmt --all` clean
  • `cargo check` passes
  • `cargo clippy --no-deps` clean
  • `cargo test --bin agent commands::tests::usage_rows_skip_messages_without_usage` passes (verifies rows skip assistant messages without usage and fall back to default model)
  • Manual: multi-turn session → `/usage` prints table with a row per turn
  • Manual: fresh session → `/usage` prints "No completed turns with usage data yet."

Complements /cost (aggregate totals) with a per-turn breakdown:
model, input, output, cache read, cache write — plus a total row
and a cache-hit-rate hint pulled from the totals.

Reads the `usage` payload on each assistant message. Messages without
usage (older sessions, streaming failures) are skipped rather than
shown with zeros, so the table only reports turns where data is real.
@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@emal-avala emal-avala merged commit 3baff5b into main Apr 22, 2026
13 of 14 checks passed
@emal-avala emal-avala deleted the feat/cmd-usage branch April 22, 2026 23:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant