feat(usage): show today's agent spend beside Send #2985

Problem

Usage (Settings → Plugins → Usage) already estimates what your agents' Claude Code, Codex and goose sessions cost on this computer. To see it, you leave the conversation and open Settings. While you work, there's no sign of how much your agents have spent today, so cost only shows up after the fact.

Proposal

An opt-in Show today's spend beside Send switch on the Usage page. When it's on, a small amount sits just before Send in each conversation's composer: your agents' estimated spend since local midnight.

Screenshots (light and dark, a 480 px window with 20 agents, and the setting) are in the first comment.

Behavior

• Off by default, on top of Usage itself being off by default. Saved on this device, like Send with ⌘ Enter.
• Only you. It shows your own agents' usage, never per conversation, and nothing is sent anywhere.
• Same scope and numbers as the Usage page. It counts the same agents the Usage page does (your agents here, in the community you're in) and reuses Usage's session reads and stats() for one day. The harness's own cost wins; otherwise tokens are priced at published API rates from @pydantic/genai-prices. "Estimated" stays in the card header.
• Unknown stays unknown. An agent whose cost can't be estimated shows —, never $0.00. When some costs are unknown, the amount shows what's known and the card says "Some costs are unknown." If price data fails to load, costs the harnesses recorded still count, as on the Usage page, and the card says prices couldn't load.
• The card. It opens and closes like Buzz's other hover cards: on hover (the design guide's Preview timing), on click, or with Enter; Escape or clicking outside closes it. It shows "Today", the total, then every agent by spend. Past about five agents the list scrolls inside the card, as the Working now card's does, so the card keeps its size and place. Selecting an agent closes the card and opens its latest conversation from today, the same navigation as Usage's costliest sessions.
• Not in threads. A thread's composer shows no amount, so a thread open beside its channel doesn't repeat it.
• Cost to run. All open composers share one read. It reads again at once when the agents load or change (including switching communities, where the previous community's total stops showing), and at local midnight. A composer appearing or the card opening reads again if the last read is over a minute old; the window coming back does if it's over five minutes old. There's no polling timer, so the amount can lag while you stay in one conversation.
• What a read does. Each read runs the harnesses' existing Usage readers on this computer, so it costs what refreshing the Usage page costs: Claude Code reads its session files (the first read after launch parses them, later reads only changed ones); Codex starts a short codex app-server per agent to list today's threads and opens only rollouts that changed; goose lists the workspace once for all its agents. Nothing goes over the network: relay reads per client: 0.
• Measured with the readers' own code against real local history (Node, outside the app):
  • Claude Code, agent workspace holding about 860 MB of other Claude Code sessions (one worst case: an agent pointed at a folder you also use Claude Code in): the first read after launch took 17 s and about 84 s of CPU across cores, nearly all of it grep searching every session file for a Buzz prompt. Later reads took 1.3 s and 1.3 s of CPU. Ten agents in that workspace cost the same as one: they share the search.
  • The default workspace, ~/.buzz, holds only Buzz's own sessions, so this search is small there.
  • Codex: 0.2–0.6 s per agent per read; ten agents, about 3 s of CPU per read.
  • The Usage page pays the same costs when it opens; with the amount on, the first read happens at launch instead.

Host change it needs

Composer tools render in the tool row on the left today. Putting a control next to Send needs a small, generic extension to the ComposerTool contract (contracts.ts is FOUNDATION):

/** `send` places a compact status control just before Send instead of in
 * the tool row. The host hides it while a sent message is being edited. */
placement?: "send" | undefined;

Any value other than "send" is rejected at registration, so a plugin that passes another value no longer activates (today the field is ignored). Tools without a placement are unchanged. I'd like a maintainer's OK on this contract addition before I open the PR. If you'd rather not extend the contract, the fallback is to register it as an ordinary tool at the end of the tool row (no host change), at the cost of sitting further from Send.

Reader fixes it needs

The amount reads from midnight while the Usage page reads 30 days, so two readers need small fixes to share a cache with two ranges:

• goose: a read that joined one already under way used that read's range, so opening the Usage page during the amount's read could show only today's goose sessions. A wider read now waits and reads its own range.
• goose and Codex: a read from midnight dropped older sessions from the reader's cache, so the Usage page re-read them each time. They're now kept.

Out of scope (possible follow-ups)

• A context-window ring next to the amount. usage_update context is already parsed into turn.context {used, size} in activity-transcript.ts, but nothing exposes it to plugins yet. It would hide when a harness reports no real limit.
• Agents not running on this computer. Like the Usage page, this counts agents running here only:
  • Hosted agents run on their provider's machines, and elsewhere agents on your other computers, so their session files aren't here. Covering them needs the provider, or each device, to report usage to the app.
  • Claude Code and Codex agents set to run on a remote machine can't be read yet either; they show — and make the total partial, as on the Usage page.
• A smaller first Claude Code read. The search for Buzz prompts reads whole session files that aren't Buzz's; stopping at each file's first prompt would make the first read after launch much cheaper, for the Usage page too.
• Budgets, alerts, other periods (Usage already has 7 and 30 days).

Related

• Estimate Codex costs in Usage with genai-prices #1458: Usage prices Codex with genai-prices (this builds on it).
• feat(usage): move Usage from the sidebar into Settings #2742: Usage moved into Settings.
• feat(usage): SessionUsage.limits for usage a harness never reports #2926 (open): adds SessionUsage.limits. This reuses merge and stats, so it picks that change up as is.
• fix(deps): update all non-major dependencies #873 (open): Renovate's grouped update, which includes genai-prices 0.1.13 → 0.2.1. Until it lands, Codex agents on GPT-6.1 Terra show —, as they do on the Usage page.
• Agent API budgets and owner-wide spend visibility buzz#5652 asks for owner-wide spend visibility (0.X tracker). This covers its "today, on this computer" slice.
• I searched this repo for spend, cost, budget and composer usage and found no duplicate.