feat(usage): usage page reading provider transcripts across environments

[t3dotgg]

Problem

There is no way to see token usage or what the agents are costing. T3 Code's own orchestration projections don't record token counts at all, and even if they did they would miss every turn driven outside T3 Code.

Preview:

Approach

Read the provider CLIs' own on-disk session transcripts, which is the technique ccusage uses:

• Claude Code: ~/.claude/projects/**/*.jsonl → message.usage
• Codex: ~/.codex/sessions/**/*.jsonl → event_msg/token_count

Tokens are priced against LiteLLM's model_prices_and_context_window.json, the same rate table ccusage uses, cached to disk with a 24h TTL so the page works offline. Models with no rate are counted in token totals and reported as unpriced rather than silently costed at zero.

Each environment returns pre-aggregated (day, provider, model) buckets; raw transcripts never cross the wire. The client queries every connected environment and merges.

Two things worth reviewing closely

De-duplication is load-bearing. T3 Code writes one JSONL record per assistant content block, each repeating the parent message's complete usage object. Summing naively overcounts by ~2.4x. On a real 30-day window this drops 67,377 duplicate records out of ~132k. Deduped by message.id+requestId, keeping the first, matching ccusage.

Cross-environment double counting. Several environments on one machine (worktree servers) resolve the same provider home. Each source reports a fingerprint of hostId + resolved path, and the client lets one environment claim each fingerprint, per provider, in a stable order. Without this every worktree server would multiply your totals.

Verified against real data

A 30-day scan on this machine: 1,614 files, 3.6s cold, 127 buckets, 917 of 65,124 responses unpriced (1.4%).

Codex last_token_usage deltas were checked to reconcile with the session's final total_token_usage before being trusted.

Why WIP

• Runtime and turn-completion are not implemented. The reference mock shows "221h · 2,092 turns · 98.5% complete". Those cannot come from the transcripts; they need a join against ProjectionTurns. The metric slot currently shows responses and sessions, which are real from this data source. This is the main gap.
• Cost is API-equivalent, not money spent. Subscription plans bill separately, so the page says "raw token cost" rather than "spend".
• Codex token_count carries no model, so it is attributed from the preceding turn_context. Sessions that switch models mid-run smear across the switch.
• Priced at LiteLLM's base tier. The transcripts don't record which pricing tier served a request.
• Not visually reviewed in a browser yet.

Reference

Implements direction B, "Cost First", from https://z5mxym83xw02.postplan.dev/

---

Built with Claude Opus 5 (1M context) in T3 Code.

---

Note

Medium Risk
New filesystem scans and outbound fetch for pricing on authenticated read RPC; aggregation/dedup logic affects reported totals, with possible slow first loads on large transcript trees.

Overview
Adds a Usage experience that estimates token usage and API-equivalent cost by scanning Claude Code and Codex on-disk session JSONL transcripts (not T3 orchestration projections), priced with a LiteLLM rate table cached on disk.

On the server, a new UsageService walks configured transcript dirs, streams/parses lines with provider-specific reducers, dedupes repeated assistant usage (e.g. per content block), aggregates into (day, provider, model) buckets in the caller’s time zone, and memoizes per-file parses in a durable scan cache keyed by size/mtime. serverGetUsageSummary is wired through WS RPC with orchestration read auth and a typed @t3tools/contracts usage contract.

The web app adds /usage (sidebar entry) with cost/token charts, breakdowns, and coverage notices. useUsage queries every connected environment; mergeUsage sums distinct transcript sources and collapses duplicates when multiple environments share the same host/path/volume fingerprint, excluding stale contract versions.

^{Reviewed by Cursor Bugbot for commit 721f812. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add a Usage page that aggregates token and cost data across provider transcript directories

• Introduces a /usage route rendering an interactive dashboard with time window controls, a stacked provider chart, summary metrics, model/day breakdown tables, and cost quality indicators.
• Adds a server-side UsageService that scans Claude and Codex transcript files (.jsonl), parses them line-by-line, prices usage via a LiteLLM rate table (cached with a daily TTL), and returns a UsageSummary via a new server.getUsageSummary WebSocket RPC.
• A durable per-file scan cache avoids reparsing unchanged files across requests; cache entries are keyed by file size, mtime, and provider.
• mergeUsage on the client de-duplicates shared transcript directories across environments (identified by filesystem volumeId), excludes stale environments by contract version, and aggregates cost/token breakdowns by provider, model, and day.
• Adds a 'Usage' entry to the sidebar footer that navigates to /usage.
• Risk: transcript parsing is best-effort — read failures return null and are not cached, so a consistently unreadable file is re-attempted on every scan.

^{Macroscope summarized 721f812.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 87e9e0e5-db7c-4934-b0d8-05a286870f85

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

🟡 Medium state/usage.ts:104

isPartial can be false even when one or more connected environments are excluded from the merged totals. mergeUsage drops summaries whose contractVersion is stale, but useUsage computes isPartial solely from environment.summary !== null. A stale environment still has a non-null summary, so it counts as answered — answeredCount === environments.length, isPartial is false, and the page presents incomplete totals as complete with no coverage warning. Consider including merged.staleEnvironments in the isPartial computation so stale environments are surfaced as missing coverage.

Also found in 1 other location(s)

apps/web/src/components/usage/UsagePage.tsx:85

UsagePage does not pass or display merged.staleEnvironments in UsageCoverageNotice. mergeUsage explicitly excludes summaries whose contract version is stale, but those environments still count as answered in useUsage, so isPartial can be false. If one or more connected servers use an older contract, the page silently presents incomplete (or zero) totals as complete.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/web/src/state/usage.ts around line 104:

`isPartial` can be `false` even when one or more connected environments are excluded from the merged totals. `mergeUsage` drops summaries whose `contractVersion` is stale, but `useUsage` computes `isPartial` solely from `environment.summary !== null`. A stale environment still has a non-null summary, so it counts as answered — `answeredCount === environments.length`, `isPartial` is false, and the page presents incomplete totals as complete with no coverage warning. Consider including `merged.staleEnvironments` in the `isPartial` computation so stale environments are surfaced as missing coverage.

Also found in 1 other location(s):
- apps/web/src/components/usage/UsagePage.tsx:85 -- `UsagePage` does not pass or display `merged.staleEnvironments` in `UsageCoverageNotice`. `mergeUsage` explicitly excludes summaries whose contract version is stale, but those environments still count as answered in `useUsage`, so `isPartial` can be false. If one or more connected servers use an older contract, the page silently presents incomplete (or zero) totals as complete.

[t3dotgg]

Note

🤖 Fable 5 responding on behalf of Theo

Fixed in 4633bce. Stale-version environments are now surfaced in the coverage notice ("runs an older server version and is excluded from totals"), so excluded coverage is visible even when isPartial is false.

[macroscopeapp]

Reviewed the new usage service against the Effect service conventions. Two findings in apps/server/src/usage/UsageService.ts; the contract (packages/contracts/src/usage.ts), the pure helpers, and the web-side atoms/merge code look consistent with the conventions (subpath namespace imports, inline Context.Service interface, dependencies acquired via yield*, Schema.TaggedErrorClass with a message derived from structural attributes).

^{Posted via Macroscope — Effect Service Conventions}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.3 KiB	11.3 KiB	−24 B (−0.2%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	−8 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−16 B (−0.3%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.3 KiB	11.3 KiB	+2 B (+0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+9 B (+0.2%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−7 B (−0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: 2c7267a · PR result: 721f812 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Needs human review

1 blocking correctness issue found. This PR adds a substantial new feature (usage tracking page) with ~2500+ lines of new code, new RPC endpoints, new services, new UI components, and modifications to auth files. New features of this scope introducing new user-facing behavior warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

One convention issue found in the new usage service: UsageReadError has no cause and the wrap site stringifies the failure cause into its detail field (which is also what message is built from, and is serialized to clients over RPC).

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit af0f0ac. Configure here.}