Agent usage records: one honest view of how we use AI tools

[vinceferro]

DRAFT — basecamp/omarchy discussion post (operator review before posting)

Agent usage records: one honest view of how we use AI tools

Most of us now run several AI coding tools side by side — Claude Code,
opencode, Codex, Cline — and each one keeps its own private tally of what
we did. The agents panel is the natural place to reunite them: one panel
that answers the questions every user eventually asks. When do I actually
use these tools? Which model gets my tokens? How close am I to my plan's
limits?

Where we are today

#8862 took the first step: an activity punchcard fed by one small field,
usageByHour — and @Brams-s proposed the natural next one, a model-aware
today view. The raw pieces for the rest already exist too (daily series,
plan-limit meters), but each lives in its own world: every new view starts
from scratch, with its own conventions, and nothing tells the reader what
the numbers actually cover.

What it looks like after

The same panel grows a small family of views, all speaking the same
language: the punchcard for your long-term rhythm, a today strip for
which model got your tokens, a calendar for history, meters for how close
you are to your plan's windows. Every view is opt-in, every one declares
what it measures (this device, or the whole account), and any tool joins
by emitting one small field — the panel renders whatever exists.

Field	Grain	Window	Time basis	Status
usageByHour	weekday × hour	all-time	local	in #8862
recentModelUsageByHour	hour × model	UTC-stamped hourly buckets (hourStart, tokensByModel) over recent history — the panel derives the viewer local day	UTC	proposed
usageByDay	daily series	trailing 90d	local dates	staged
limits	windowed meters	5h / weekly	provider	existing

The rules that keep it honest

• Declare your scope. Every collector says what it measured — this
  device, or the whole account. Readers should never have to guess.
• Absent means nothing. No usage is an absent cell; a missing field
  hides the section. Never render a zero that isn't real.
• One grain, one PR. Views land and improve independently instead of
  stretching one field to answer every question.

The z.ai plugin already emits usageByHour from OpenCode today
(https://github.com/vinceferro/omarchy-zai-usage) — a working example any
tool can copy.

Asks

Does this framing fit? Where should the schema doc live? And who wants to
join the first collector adoption — a Claude collector patch is already
prototyped.

[Brams-s]

Thanks for pulling this together. The mention accurately reflects the direction I proposed in #8862.

I agree with the overall framing: keep usageByHour as the provider-agnostic, all-time local weekday/hour view, and give a model-aware today view its own optional field and focused follow-up PR. The different grains should not be stretched into one contract.

I would make one semantic adjustment to the table. I would not describe recentModelUsageByHour as “today (rolling UTC).” My proposal was to emit UTC-stamped hourly buckets, with entries such as hourStart and tokensByModel, over enough recent history for the panel to derive the viewer’s local calendar day. That keeps collection timezone-neutral while making the TODAY view match what the person using the panel considers today.

For documentation, I would put the normative record contract in shell/plugins/agents/README.md initially, alongside the existing collector and sync documentation. Each optional field should document its shape, grain, window, time basis, scope, merge rule, and absence semantics. If the contract grows substantially, it can move into a dedicated SCHEMA.md linked from the README.

For first adoption, I am still happy to take the Codex follow-up after #8862 lands, using the collector’s existing native Codex, pi/omp, and OpenCode scan paths. I would keep that PR focused on emitting the new field and rendering the compact TODAY MODELS view. Unsupported collectors would simply omit the field.

[vinceferro]

Agreed on all points — the hourStart / tokensByModel UTC-stamp correction is right, and our collector already emits that shape; I have amended the table. README.md placement and the per-field documentation list adopted as the normative home. The Codex follow-up is yours once #8862 lands — the zai collector stays available as the bucketing reference.

[Brams-s]

Here is the concrete local prototype behind the model-aware today idea:

The visual direction is the top TODAY strip: 24 viewer-local hour columns colored by model. The TOKENS BY DAY model stacks and tooltips below it are a separate experiment.

The screenshot also gives us a useful failure case for the “honest view” rule. The Tue 9/1 tooltip shows a 779.1M total, while the visible named model buckets add up to about 614.9M, leaving roughly 164.2M unattributed. The current local bar stretches the known model colors across the filled width, which is not honest enough for upstream.

For the focused follow-up after #8862, I would keep the scope we agreed: an optional UTC-stamped recentModelUsageByHour, converted to the viewer's local day, with Codex as the first adopter. Its collector must cover all native Codex, pi/omp, and OpenCode scan paths—or the panel must render an explicit unattributed remainder. Unsupported collectors should omit the field. The current prototype's local wall-clock buckets are visual exploration, not yet that proposed contract.

The BY DEVICE / BY SOURCE rows are a separate attribution experiment tracked in #9792, not part of the focused model-aware-today follow-up.

[vinceferro]

One downstream use-case strengthening the case for recentModelUsageByHour: a rolling last-7-days punchcard with today as the highlighted last column. usageByHour's all-time weekday/hour grain cannot express recency, so that view waits on the new field — noting it as a viz goal for the follow-up.

[vinceferro]

The presentation pattern we shipped in #8862 for exactly this reading problem — week ordered around the viewer, today highlighted last, header states all-time explicitly:

Once recentModelUsageByHour exists, the same treatment on true per-date buckets becomes the rolling last-7-days view: today genuinely last, not just ordered there.

[Brams-s]

A concrete failure from the local prototype today strengthens the collector-coverage requirement we discussed: the 13:00 hour displayed zero while native Codex had about 15.0M tokens in that hour. The daily total included native sessions, but the prototype's hourly enrichment only read OpenCode. This was a bug in my user-owned prototype, not in #8862.

The corrected local scan builds hourly, daily, and model totals together across native Codex, pi/omp, and OpenCode. For the same scope/window/token definition, those totals now reconcile. I would make that an acceptance criterion for the follow-up: cover every supported scan path, or explicitly represent incomplete coverage rather than showing a false zero or stretching known model colors over the remainder.

The audit also exposed repeated native token_count notifications inflating the stock collector. I have submitted that small, separate fix as #10531; its tests distinguish repeated cumulative snapshots from legitimate equal-size requests and invalidate old cached totals.

The agreed upstream direction is unchanged: recentModelUsageByHour with UTC hourStart / tokensByModel, integrated into the existing collector scans, and viewer-local day selection in the panel. The local wrapper and local-time recentHours remain prototype details. I have retained the rolling seven-day use case in the follow-up checklist; it should inform the retention window without expanding the initial Today UI scope. #8862 is still open, so the focused hourly follow-up remains sequenced after it.