feat(usage): add Grok reports to desktop and mobile

[jakeleventhal]

What Changed

• Added Grok Build transcript scanning, exact provider-reported cost handling, per-model response counts, and cache-version support.
• Added Grok provider metadata to the shared desktop/web and mobile usage dashboards.
• Documented usage reports and included an example screenshot with simulated Grok activity.

Why

Usage reports scanned Claude Code and Codex transcripts but omitted Grok activity. This reads persisted Grok ACP modelUsage updates from GROK_HOME or ~/.grok without modifying provider data.

UI Changes

Before, Grok activity was absent from the usage report.

After — simulated Grok data

The screenshot uses an isolated randomized Grok transcript fixture with a 30-day total close to the Claude total. No real Grok usage data was changed.

Validation

• vp test run apps/server/src/usage apps/web/src/components/usage packages/shared/src/usageMerge.test.ts packages/shared/src/usageFormat.test.ts — 87 tests passed
• Contracts, shared, server, web, and mobile typechecks passed
• Targeted lint and format checks passed
• Read-only reconciliation against real ~/.grok transcripts matched the source totals
• Desktop usage UI verified with isolated simulated Grok data

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Built with GPT-5.6 Codex in T3 Code.

---

Note

Medium Risk
Touches usage aggregation, scan-cache invalidation (cold rescan), and contract version 5; parsing/dedupe mistakes could misstate Grok totals or costs, but changes are read-only and well covered by tests.

Overview
Adds Grok to usage reporting end-to-end: the contract now includes grok and bumps to version 5, and desktop/web/mobile charts show Grok alongside Codex and Claude.

On the server, usage scans GROK_HOME or ~/.grok/sessions for updates.jsonl, parses Grok ACP modelUsage via parseGrokLine (per-model rows, provider cost ticks, fork dedupe), and skips subagent ledgers that are already rolled into the parent session. UsageRecord.recordCount tracks bundled modelCalls; aggregation and the scan cache (v4) use it so response counts stay accurate when one line represents multiple calls.

readGrokHomeOverride normalizes GROK_HOME; user docs note Grok and deduplicated transcript directories.

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

Note

Add Grok usage parsing and reporting across platforms

• Adds parseGrokLine to parse Grok ACP transcripts into UsageRecord rows, including subagent filtering to avoid double-counting and support for the GROK_HOME environment variable.
• Introduces recordCount to UsageRecord to track multiple model calls per record, replacing fixed counts in aggregation and scan cache encoding.
• Bumps usage contract version to 5 and adds 'grok' to UsageProviderKind. Adds Grok provider charts, labels, and colors to web and mobile UI.
• Behavioral Change: Bumps USAGE_SCAN_CACHE_VERSION to 4, which invalidates existing older caches and triggers a cold rescan.

^{Macroscope summarized 9e7c555.}

[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: 5393327a-77ab-4bd0-b928-0327e5152745

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]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a new Grok transcript ingestion path with parsing, deduplication, cost handling, cache invalidation, contract changes, and desktop/mobile presentation. Because it changes production scanning and usage aggregation across multiple components, the scope warrants human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

One finding: the new Grok home resolution reads process.env imperatively inside the UsageService constructor instead of acquiring the host environment from the Effect environment. Everything else in the changed scope (pure transcript parsers, scan cache, contracts, UI provider tables) is outside the Effect service surface and follows the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One finding on the new Grok usage presentation entry: the series/swatch color is a hardcoded gray instead of a semantic token, so it does not follow theme or the contrast appearance setting.

^{Posted via Macroscope — UI Consistency}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

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

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