feat(grok): add Grok Build CLI usage adapter - #1520
Conversation
Parse completed Grok Build turns, map token usage and LiteLLM pricing, and expose focused and unified reports. Discover data from non-empty GROK_HOME or ~/.grok, add schema and CLI integration, and document the source.
|
This PR was auto-closed. Only contributors approved with Maintainers review auto-closed issues and reopen worthwhile ones. Issues that do not meet the quality bar in CONTRIBUTING.md may not be reopened or receive a reply. If a maintainer replies See CONTRIBUTING.md. |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (4)
📒 Files selected for processing (35)
📝 WalkthroughWalkthroughAdds first-class Grok Build CLI support through a Rust adapter that reads completed session turns, generates usage and cost reports, integrates with focused and unified CLI commands, adds Grok configuration, and documents data discovery and report behavior. ChangesGrok usage reporting
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
Suggested reviewers: ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
|
@ryoppippi |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — adds a new Grok Build CLI adapter (ccusage-adapter-grok) that reads completed turns from ~/.grok/sessions/**/updates.jsonl, supporting ccusage grok daily|monthly|session and unified/all-agent reports.
- New
ccusage-adapter-grokcrate — JSONL parser forturn_completedevents withmodelUsagebreakdowns, token split (uncached = input − cache), pricing candidate lookup (strip-build, tryxai//x-ai/prefixes), intra- and cross-session dedup, andGROK_HOME→~/.grokpath resolution - CLI command wiring —
Command::Grokvariant dispatched throughparse_basic_agent_commandwithSTANDARD_AGENT_REPORTS; root help, parse shapes, and rejection test for the intentionally-unavailable--grok-pathflag - Config & schema —
GrokConfig/GrokCommandsConfigin config schema with shared options only; nogrokPathproperty; schema snapshot updated - Unified reports integration — Grok at index 15 in
BUILT_IN_AGENT_NAMESandAgentLoadSpec;agent_label("grok")and isolated-env guard; unified daily and session integration tests - Documentation — full Grok guide (
docs/guide/grok/), VitePress nav, guide index table, source-support-qa update (from "not supported" to supported), README additions, and env-only path design spec
@v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏
There was a problem hiding this comment.
Pull request overview
Adds Grok Build CLI as a first-class ccusage data source by introducing a new Rust adapter that reads turn_completed usage from Grok session logs, wires it into focused (ccusage grok ...) and unified reports, and documents the new source (including env-only path discovery via GROK_HOME → ~/.grok).
Changes:
- Introduce new
ccusage-adapter-grokcrate (path discovery, JSONL parsing, token mapping, cost estimation via existing pricing). - Wire Grok into the main CLI command enum/parser, unified loader, config schema, and snapshot tests.
- Add user documentation for Grok (guide page + nav + source-support Q&A updates) and update generated config schema outputs.
Reviewed changes
Copilot reviewed 38 out of 39 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| rust/crates/ccusage/src/main.rs | Dispatch ccusage grok to the Grok adapter and extend adapter-exposure test list. |
| rust/crates/ccusage/src/cli/last_window.rs | Include Grok in the commands that support --last window targeting. |
| rust/crates/ccusage/src/adapter/mod.rs | Re-export the new ccusage_adapter_grok crate for the runtime. |
| rust/crates/ccusage/README.md | Document the new ccusage-adapter-grok crate among adapter crates. |
| rust/crates/ccusage/Cargo.toml | Add workspace dependency on ccusage-adapter-grok. |
| rust/crates/ccusage-core/src/lib.rs | Add grok to the built-in agent name list used by unified reporting. |
| rust/crates/ccusage-config/src/snapshots/ccusage_config__config_schema__tests__snapshots_schema_agent_specific_option_edges.snap | Update schema snapshot to include the Grok namespace defaults/shape. |
| rust/crates/ccusage-config/src/config.rs | Add config test ensuring grok namespace supports shared report options. |
| rust/crates/ccusage-config/src/config_schema.rs | Add GrokConfig types and schema tests (including “no grokPath” assertions). |
| rust/crates/ccusage-cli/src/types.rs | Add Command::Grok to the shared command enum. |
| rust/crates/ccusage-cli/README.md | Update adapter count note to reflect the new adapter. |
| rust/crates/ccusage-cli-parser/src/tests.rs | Add Grok parse/help tests and representative parse-shape coverage. |
| rust/crates/ccusage-cli-parser/src/snapshots/ccusage_cli_parser__tests__snapshots_representative_cli_parse_shapes.snap | Update parse-shape snapshot to include grok daily. |
| rust/crates/ccusage-cli-parser/src/snapshots/ccusage_cli_parser__tests__root_help.snap | Update root help snapshot to list grok. |
| rust/crates/ccusage-cli-parser/src/parser.rs | Add Grok command parsing and include Grok in agent command classification/display-name handling. |
| rust/crates/ccusage-cli-parser/src/cli-commands.json | Add Grok command definitions and help wiring for daily/monthly/session. |
| rust/crates/ccusage-adapter-all/src/tests.rs | Add unified-loader tests validating GROK_HOME discovery and token mapping. |
| rust/crates/ccusage-adapter-all/src/report.rs | Provide a unified report label mapping for the grok agent. |
| rust/crates/ccusage-adapter-all/src/loader.rs | Add Grok to unified loading specs and detection logic. |
| rust/crates/ccusage-adapter-all/src/lib.rs | Re-export Grok adapter in the all-adapters crate. |
| rust/crates/ccusage-adapter-all/README.md | Update documentation and adapter list for the new adapter dependency. |
| rust/crates/ccusage-adapter-all/Cargo.toml | Add workspace dependency on ccusage-adapter-grok. |
| rust/Cargo.toml | Register the new ccusage-adapter-grok workspace member path. |
| rust/Cargo.lock | Lockfile updates for the newly added Grok adapter crate. |
| rust/adapters/grok/src/report.rs | Implement Grok-focused report JSON and daily/monthly/session summarization. |
| rust/adapters/grok/src/paths.rs | Implement env-only root resolution (GROK_HOME → ~/.grok) and session file discovery. |
| rust/adapters/grok/src/parser.rs | Parse updates.jsonl turn_completed events, map tokens, handle per-model usage, and estimate costs. |
| rust/adapters/grok/src/loader.rs | Load all Grok sessions (parallel read), apply global dedupe, and expose has_data(). |
| rust/adapters/grok/src/lib.rs | Wire adapter entrypoint (run) and shared report rendering behavior. |
| rust/adapters/grok/README.md | Document Grok adapter ownership, data source, token mapping, and pricing behavior. |
| rust/adapters/grok/Cargo.toml | Define the new adapter crate and its dependencies/dev-deps. |
| docs/superpowers/specs/2026-07-28-grok-env-only-path-design.md | Capture design decision: env-only root discovery and no --grok-path/grokPath. |
| docs/guide/source-support-qa.md | Update Q&A to reflect that Grok Build CLI is now supported and how it’s loaded. |
| docs/guide/index.md | Add Grok Build CLI to the supported-sources overview and examples. |
| docs/guide/grok/index.md | Add Grok Build CLI guide page (usage, discovery, config, troubleshooting). |
| docs/.vitepress/config.ts | Add Grok Build CLI to the guide navigation. |
| apps/ccusage/README.md | Include Grok in the app-level supported sources list and examples. |
| apps/ccusage/config-schema.json | Update generated config schema JSON to include Grok configuration namespace. |
| .agents/skills/agent-sources/SKILL.md | Add Grok Build CLI adapter reference in agent-sources skill documentation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Update after resolving conflicts with current Branch
Test hardening (new)
Local test results
Issue context: #1513 Would appreciate a reopen / |
|
Update: this PR branch is now synced to the latest Sync status
Conflict resolution notesConflicts were mostly agent inventory lists (docs / loader / CLI / schema). Resolution keeps Grok Build CLI fully wired, and does not reintroduce Antigravity (which was reverted on main in #1569). Grok remains documented as supported (Build CLI Local verification after sync
Issue context: #1513 This PR was auto-closed by the contributor gate — would appreciate a reopen / |
@ryoppippiBranch is synced to the latest Sync
Test results (local, Windows, after sync)
Real run:
|
| Date | Input | Output | Cache Read | Total Tokens | Cost |
|---|---|---|---|---|---|
| 2026-07-28 | 246,278 | 42,824 | 8,955,776 | 9,267,987 | $3.90 |
| 2026-07-30 | 1,336,630 | 155,522 | 25,235,840 | 26,810,987 | $12.67 |
| 2026-07-31 | 488,189 | 46,833 | 8,104,064 | 8,665,920 | $4.18 |
| 2026-08-01 | 174,640 | 597 | 185,088 | 360,597 | $0.46 |
| 2026-08-04 | 5,268,481 | 821,340 | 92,840,448 | 99,464,505 | $49.11 |
| 2026-08-05 | 5,886,240 | 948,862 | 120,786,432 | 128,237,288 | $60.88 |
| Total | 13,400,458 | 2,015,978 | 256,107,648 | 272,807,284 | $131.20 |
Real turn_completed usage from ~/.grok/sessions/**/updates.jsonl, all on grok-4.5-build. The cache-read split and cost estimation work end-to-end on production data.
Branch: feature/grok-build-usage-adapter @ 147e05b
This PR and the issue were auto-closed by the contributor gate — could you take a look and reopen / lgtm when you have a chance?
Issue context: #1513
Summary
Add first-class Grok Build CLI usage reporting to ccusage.
Closes #1513
What changed
ccusage-adapter-grokreads completed turns from$GROK_HOME/sessions/**/updates.jsonl(sessionUpdate == "turn_completed"+usage/modelUsage)GROK_HOME, then~/.grok(no ccusage-only path override)inputTokens - cachedReadTokens, fulloutputTokensas output,reasoningTokensin extra total only (not double-billed), ignorecostUsdTicksfor invoice USDccusage grok daily|monthly|session, config shared options, and all-agent / bareccusageloadersSessionAccumulatorsofirst_activity,last_activity, andproject_pathare present in tables and JSON (aligned with qwen/opencode/antigravity)docs/guide/grok/Why
Grok Build writes per-model token usage on completed turns, but ccusage did not load it, so unified totals were incomplete for Grok users.
Rebase / conflicts
Merged current
main(including Antigravity #1544 and related docs/wiring) intofeature/grok-build-usage-adapter. Conflicts were resolved so both Grok and Antigravity remain wired in:BUILT_IN_AGENT_NAMES, unified loader, CLI parser,last_window, config schemaBranch tip:
a3d4a2a. Merge-base withmainis currentmain(no remaining conflicts).Testing
Raised Grok adapter coverage to roughly the same bar as the Antigravity adapter (#1544): fixture-backed, behavior-named tests; synthesized
updates.jsonl(no real session trees committed).Coverage layers
paths.rsupdates.jsonlonly, nested multi-project trees, blankGROK_HOMEfallback, non-directory overrideparser.rsagentTimestampMsvs envelope seconds), summary vs line session id, URL-decoded project path, missing pricing, ignorecostUsdTicks, in-file dedupeloader.rshas_datanegative pathreport.rsprojectPathin JSONlib.rs#[ignore]real$GROK_HOMEloadAlso: CLI parser (
grokhelp / rejects--grok-path), config schema (nogrokPath), unified all-agent tests that exerciseGROK_HOME.Local results (after merge with main)
Related commits on this branch after the original adapter:
237d30bfix(grok): report session activity and project path97777cftest(grok): expand adapter coverage to antigravity-levela3d4a2amerge upstream/main (conflict resolution)