feat(usage): break down usage by project by saphid · Pull Request #9015 · pingdotgg/t3code

saphid · 2026-09-01T07:34:10Z

Usage totals show which provider and model spent the money, but not which project. When several workspaces share one environment, that's the question users actually have.

Depends on #9014. This branch contains #9014's commits (cf2474d602, 0f7cd7f00d) followed by this PR's single commit 80985a75ad. Review only the project increment. Merge #9014 first; the PR stays in draft until then.

How it works

Server. Claude and Codex transcripts already record each session's working directory. The scanner now keeps that cwd (Codex follows turn_context changes). At scan time it resolves the cwd against the environment's project list (ProjectionProjectRepository.listAll, which includes soft-deleted projects so their past spend stays attributed). The deepest workspace root wins. Each bucket is tagged project, outside, or unknown. Grok logs carry no folder, and a project-list read failure also yields unknown, never a misleading "outside".
Contract. UsageBucket gains optional project, projectId, and projectAttribution; USAGE_CONTRACT_VERSION goes 5 → 6. Older servers keep merging, and their buckets count as unknown attribution. The scan cache goes v3 → v4 so cached records carry their cwd; this costs one full rescan after upgrade.
Shared merge. mergeUsage rolls buckets up into projects, keyed per environment, so equal ids or titles on two servers stay separate. An optional projectFilter narrows every other figure. Session counts can't be split by project, so they're hidden while a filter is active. Fully unpriced projects reuse main's unpriced treatment (fix(usage): flag unpriced model activity instead of showing $0.00 #11021) instead of showing $0.00.
Web. The breakdown gains a Project view, ranked by the selected metric. A project picker (All projects / each project / Outside projects) narrows the page; "All projects" clears it.
Mobile. Not in this PR. Mobile totals still merge correctly with the v6 contract; the project view can follow separately.

Screenshots

Isolated dev server, synthetic Claude transcripts for two projects (Atlas, Beacon) plus work in an unregistered folder, 30-day window.

Before (#9014 head 0f7cd7f00d): model and day breakdowns only.

After (80985a75ad): Project breakdown. The rows add up to the $36.04 headline, and unregistered work appears as "Outside projects".

After, Atlas selected in the picker: headline, chart, totals and table all narrow to $12.23.

Verification

vp test run apps/server/src/usage/ apps/web/src/components/usage/ apps/web/src/state/usage.test.tsx packages/shared/src/usageMerge.test.ts packages/shared/src/usageFormat.test.ts: 17 files, 210 tests pass. New coverage: service-level attribution (project vs outside), unknown attribution on repository failure, the resolver's nesting/boundary/deleted-project rules, scan-cache cwd round trip, Codex cwd changes, and merge filtering/namespacing/unpriced projects.
Typecheck passes for t3, @t3tools/web, @t3tools/shared, @t3tools/contracts, @t3tools/mobile. vp lint and vp fmt pass on the touched files.
A cross-provider (Codex) review was skipped because Codex weekly quota was at 7%.

Rework note

This head replaces the earlier cumulative stack. The refresh-token cache bypass, retained refresh statuses, refresh error toasts/alerts, the segmented Input variant, and the three unshipped contract bumps (v6–v8) are gone. They weren't needed for project attribution; any that are still wanted belong in their own PRs.

Coordination trace: T3 thread 7227674d-e4cd-4b7a-b0d4-08e32d2e1e0e

Reworked with Claude Opus 5 in the Claude Code harness (via T3 Code).

🤖 Generated with Claude Code

The Usage page can drill project, provider and model totals down to the threads and subagents that produced them. The server maps provider sessions and worktrees to T3 threads with bounded rows, and the web and mobile clients filter by environment, project and provider ownership. Includes the stacked usage time-range (pingdotgg#9014) and project-breakdown (pingdotgg#9015) changes this feature builds on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Carries the cumulative content of pingdotgg#9014, pingdotgg#9015 and pingdotgg#9016, rebased onto current main. This PR's own change is the following commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Price cache creation as its own estimated component in usage summaries, the model/project/thread breakdowns and the daily thread chart, keeping unknown cache-write cost unavailable rather than zero. Carries the stacked usage work from pingdotgg#9014, pingdotgg#9015, pingdotgg#9016 and pingdotgg#9017, rebased onto main and reconciled with upstream's per-model unpriced flag (pingdotgg#11021). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Usage totals now split by the T3 project whose workspace root contains each session's working directory. The server records the cwd from Claude and Codex transcripts, resolves it against the project list at scan time, and tags each bucket as project, outside, or unknown. The web Usage page gains a Project breakdown and a project picker that narrows every figure on the page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:L 100-499 changed lines (additions + deletions). labels Sep 1, 2026