Local usage

What you see

Each turn can record input tokens, cached-read tokens, output tokens, reasoning tokens, model-call count, API time, and an optional cost estimate. /usage and /usage show open that ledger.

What you see depends on screen mode:

• Fullscreen — a modal. /usage lands on the Usage limit tab. The useful content is the session usage block (and the Context usage / Session info tabs). The Usage limit tab may still show leftover account-allowance copy such as No billing data available. or Usage limits are managed by your team. Those lines are not a MatchaCode subscription and not a procedure. Ignore them.
• Minimal — the same session-usage text is written into scrollback as a system block. There is no billing follow-up.

Typical session-usage text:

Session usage (since start or last resume):
  Input tokens:   1,234,567 (1,000,000 cached)
  Output tokens:  45,678 (12,000 reasoning)
  Total tokens:   1,280,245
  Model calls:    42 · API time: 3m12s
  Cost:           $1.2345

If you switched models in the session, a By model: breakdown is appended. Before the first model call:

Session usage: no model calls yet in this session.

Cost is whatever the Provider reported in this session's ledger. When the Provider omits it (Ollama's built-in descriptor does not advertise usage; some gateways skip cost), the line is not available (not reported) — that is not a claim that the call was free. Incomplete tracking is called out so a zero is never implied.

/usage is hidden or refused when the session cannot offer local diagnostics (/usage is not available. / Local usage diagnostics are unavailable.).

Related, local-only commands:

• /context — context-window breakdown (system prompt, messages, reasoning overhead, free space), plus informational rows for tools, skills, and MCP announcements.
• /session-info — auth method, model, turn count, context usage.
• /privacy — Settings row Coding data (local). Prompts, traces, and metrics stay on this machine. Remote sharing and training opt-in are not offered.

You run /usage when you want to know how heavy this conversation has become before you compact, raise effort, or switch the assistant to a cheaper model. That is a local steering signal. Paying the Provider still happens on that Provider's own site or invoice — Matcha CLI does not collect it.

Show this session's ledger

In the TUI:

/usage
/usage show
/cost

In fullscreen, switch tabs in the modal to Context usage or Session info when you want window fill or session metadata instead of the ledger. In minimal mode, read the system block in scrollback.

Read the numbers as local diagnostics

• Input / cached — tokens sent, including cache hits the Provider reported.
• Output / reasoning — completion tokens; reasoning is a subset when the model reports it (see Reasoning effort).
• Model calls / API time — how many Provider round-trips and how long they took.
• Cost — local estimate from reported ticks, or not available.

Do not treat the block as a weekly allowance, a SuperGrok quota, or a MatchaCode invoice.

What to do instead of manage billing

/usage manage is unavailable. To understand or pay for Provider spend, use that Provider's own console (xAI, OpenAI, Anthropic, your gateway). Matcha CLI will not open a product billing URL.

To reduce local spend on the next turns: pick a cheaper id with /model, lower /effort, or /compact so later prompts carry less history.

Keep secrets out of shared logs

Local logs can be written with MATCHA_LOG_FILE. Crash dumps stay on disk. Do not put API keys in paths you will share. Nothing in this article uploads those files.

What Matcha CLI does not do

You may still see leftover modal labels such as Usage limit. They are not a procedure and not a MatchaCode bill.