Multi-agent token usage: show combined totals and per-agent breakdown in TUI #14642

What variant of Codex are you using?

App / TUI (multi-agent)

What feature would you like to see?

In multi-agent sessions, Codex should expose both:

1. Combined token usage across the whole session (main thread + all agent threads)
2. Per-agent token usage for users who want to inspect where tokens went

Today the TUI appears to show token usage only for the currently displayed thread / active agent. That makes sense for local context-window UX, but it hides the total session cost/usage when multi-agent is doing work in the background.

Requested UX:

• /statusline should have an optional combined token metric in addition to the current-thread metric.
  • Example: keep the existing current-thread used-tokens / input / output items, but add parallel combined-used-tokens, combined-input-tokens, and combined-output-tokens items.
  • If maintainers want less statusline surface area, even a single combined total item would still be useful.
• /status should show both:
  • current thread token usage
  • combined token usage across all threads in the multi-agent session
• Add a slash command for curiosity/debugging, or extend /status, to show per-agent token usage.
  • Example command names: /agent-usage, /agents-usage, or a dedicated section in /status
  • The per-agent output should list main + each agent thread with totals and, ideally, input/output split

This would make multi-agent sessions much easier to reason about, especially when background agents consume a meaningful amount of tokens while the visible thread appears inexpensive.

Additional information

I searched existing issues before filing and did not find an exact duplicate for combined multi-agent token usage or per-agent token reporting. Closest related issues I found:

• Tokens usage breakdown #13222 Tokens usage breakdown — related, but focused on /status breakdown/statusline metrics rather than multi-agent aggregation
• Session Statistics Feature #10588 Session Statistics Feature — related to a broader /stats idea, but not specifically multi-agent combined/per-agent usage
• Support multiple bottom airline/statusline rows in the CLI #14047 Support multiple bottom airline/statusline rows in the CLI — relevant to statusline space/layout, but not this metric itself
• CLI: show agent/thread attribution on action status rows (read/search/update/exec) #11815 CLI: show agent/thread attribution on action status rows — adjacent multi-agent UX work, not token accounting

Implementation notes from source inspection:

• The TUI currently appears to read token usage from the currently displayed thread only.
  • codex-rs/tui/src/chatwidget.rs uses self.token_info for /status and statusline values.
  • status_line_total_usage() returns self.token_info.as_ref().map(|info| info.total_token_usage.clone()).unwrap_or_default().
  • App::token_usage() forwards self.chat_widget.token_usage().
• Existing statusline items include only current-session/current-thread token items (UsedTokens, TotalInputTokens, TotalOutputTokens), with no combined multi-agent variants.
• The backend already seems to have the primitives needed:
  • codex-rs/core/src/agent/control.rs exposes get_total_token_usage(agent_id)
  • codex-rs/core/src/codex_thread.rs exposes total_token_usage() per thread
  • the app-server already emits thread/tokenUsage/updated

That suggests this is mostly a product/UI aggregation gap rather than missing token telemetry.

Possible implementation direction:

• Keep current-thread token metrics as-is because they are still useful for context-window awareness on the visible thread.
• Add a small aggregation layer in the TUI that tracks token totals per known thread and computes:
  • visible/current-thread totals
  • combined totals across all known threads in the session
• Surface combined totals in /statusline as separate optional items so users can choose one or both.
• Surface per-agent totals in either:
  • a new slash command, or
  • a new section inside /status / future /stats
• For per-agent display, listing thread label/nickname/role plus total/input/output would likely be enough.
• Unknown or zero-usage agent threads can be omitted or shown as pending/unknown.

The main user value here is not billing accuracy; it is observability. Multi-agent sessions are harder to reason about when only the foreground thread’s usage is visible.