Add Grok Build CLI usage reporting

What do you want to change?

Add Grok Build CLI as a first-class usage source. This would add ccusage grok daily|monthly|session, include Grok in unified reports, and support Grok-specific path configuration.

Why?

Current Grok Build releases write per-model token usage for completed turns to ~/.grok/sessions/**/updates.jsonl, but ccusage does not read it. Grok users therefore see incomplete token and estimated-cost totals.

How? (optional)

Add a Rust adapter that reads turn_completed usage, splits cached input without double-counting reasoning tokens, and estimates cost through the existing LiteLLM pricing data. Wire it into the CLI, config schema, all-agent loader, tests, and user docs. I have a current-main implementation ready and will open the PR after contributor approval.

^{｜ Build this ➔ ｜ Make a plan ➔}

This issue was auto-closed. Issues from new contributors are auto-closed by default.

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.

Keep the issue short, concrete, and written in your own voice.

If a maintainer replies lgtmi, your future issues will stay open. If a maintainer replies lgtm, your future issues and PRs will stay open.

See CONTRIBUTING.md.

@LeeShunEE

@LeeShunEE did you really try it?
when i tried it last time it doesnt have a token usage. could you make some poc with tiny script using js/shell to extract the usage data?

it it works mention me.

@ryoppippi

@LeeShunEE did you really try it? when i tried it last time it doesnt have a token usage. could you make some poc with tiny script using js/shell to extract the usage data?

it it works mention me.

@ryoppippi
I got the PR ready for review already

my env

Windows 10 Enterprise (25H2) Build 26200.8875
Windows Terminal 1.24.11911.0
grok 0.2.112 (9bbd559437) [stable]

Grok Token Usage — Temp Q&A

ccusage branch: feature/grok-build-usage-adapter

Q1. Where are tokens stored, and what are the TTL / retention rules?

A: Two on-disk locations under Grok home:

Path	Role	Retention
`$GROK_HOME/sessions/**/updates.jsonl`	Per-session turn stream; durable `TurnCompleted` + `usage`	Time TTL default 30 days by file mtime (config: `[storage] cleanup_ttl_days`)
`$GROK_HOME/logs/unified.jsonl`	Cross-component diagnostic log	No time TTL. 5 MB cap

TTL source (one line each):

sessions: grok-build\crates\codegen\xai-grok-shell\src\session\persistence.rs:3047 (DEFAULT_CLEANUP_TTL_DAYS = 30)
unified: grok-build\crates\codegen\xai-grok-telemetry\src\unified_log.rs:29 (MAX_SIZE = 5 * 1024 * 1024)

# $GROK_HOME/config.toml
[storage]
cleanup_ttl_days = 99999

one line of session updates.jsonl example containing token usage

{
    "timestamp": 1785237763,
    "method": "_x.ai/session/update",
    "params": {
        "sessionId": "",
        "update": {
            "sessionUpdate": "turn_completed",
            "prompt_id": "",
            "stop_reason": "cancelled",
            "usage": {
                "inputTokens": 153817,
                "outputTokens": 2702,
                "totalTokens": 156519,
                "cachedReadTokens": 129408,
                "reasoningTokens": 940,
                "modelCalls": 6,
                "apiDurationMs": 39491,
                "costUsdTicks": 1038524000,
                "modelUsage": {
                    "grok-4.5-build": {
                        "inputTokens": 153817,
                        "outputTokens": 2702,
                        "totalTokens": 156519,
                        "cachedReadTokens": 129408,
                        "reasoningTokens": 940,
                        "modelCalls": 6,
                        "apiDurationMs": 39491,
                        "costUsdTicks": 1038524000
                    }
                },
                "numTurns": 6
            }
        },
        "_meta": {
            "eventId": "",
            "agentTimestampMs": 1785237763526,
            "cancelTrigger": "esc"
        }
    }
}

Q2. Which location does ccusage use for token usage?

A: Only sessions/**/updates.jsonl.

ccusage discovery (feature branch):

ccusage/rust/adapters/grok/src/paths.rs L17–L28 (resolve_root: GROK_HOME then ~/.grok)
same file L31–L35 (discover_session_files under sessions/)

logs/unified.jsonl not used for usage stats (diagnostic only; see Q1 unified sources).

Q3. How are tokens extracted?

A: Reader: ccusage Grok adapter (feature branch). Writer wire: grok-build (Q1).

Line filter — `ccusage/rust/adapters/grok/src/parser.rs`

Step	Line
Prefilter `"turn_completed"`	L178
Require `sessionUpdate == "turn_completed"`	L189–L190
Require `usage`	L192–L193
Prefer `modelUsage` rows	L203 (`model_usage_rows`; def L276+)
Split uncached vs cache	L132–L136 (`split_tokens`); apply L205–L206
Skip all-zero after split	L209–L210
Map fields	L212–L218 (`input_tokens` uncached, cache read, output); L267 (`extra_total_tokens` = reasoning)
Ignore precomputed cost	L249 (`cost_usd: None`)

Field meaning on the wire — grok-build

Wire field (camelCase)	Defined at
`inputTokens` (includes cache on ACP)	`notification.rs` L171–L175
`cachedReadTokens`	L179–L180
`outputTokens`	L176–L177
`reasoningTokens`	L181–L182
`costUsdTicks`	L187–L192

ccusage maps: uncached input − cache, cache → cache_read, full output, reasoning → extra_total only (not billed separately).

Q4. How is `GROK_HOME` resolved?

Grok CLI (grok-build)

xai-grok-config/src/paths.rs L28–L31 — default_grok_home() → ~/ .grok
same file L34–L46 — grok_home(): env GROK_HOME if set, else default_grok_home(); create_dir_all

ccusage (feature branch)

ccusage/rust/adapters/grok/src/paths.rs L9 — GROK_HOME_ENV = "GROK_HOME"
same file L18–L28 — non-empty GROK_HOME dir, else ~/.grok if exists

No CCUSAGE_GROK_PATH, no --grok-path, no config grokPath on this branch.

GROK_HOME="$HOME/.grok-alt" ccusage grok daily

PR ready

quick start

cd rust
cargo run -p ccusage --release --features fetch-litellm-pricing -- grok daily

@ryoppippi

@ryoppippi

To answer your "did you really try it?" question from before — yes, and here is the proof from a real run. The POC is the adapter itself: ccusage grok daily on my machine (grok 0.2.112, Windows), reading real turn_completed usage from ~/.grok/sessions/**/updates.jsonl:

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

The PR (#1520) is synced to the latest main (147e05b), and the full suite passes: ccusage-adapter-grok 39 passed (+ real-home smoke), ccusage-cli-parser 75, ccusage-config 26, ccusage-adapter-all 36.

Both this issue and the PR were auto-closed by the contributor gate — a reopen / lgtm when you have a chance would be much appreciated.

i'm sorry please wait for a couple of days. i don't feel well this week... i'm kind a exhausted this week. i'm sorry

Sorry for being pushy earlier. Hope you’re feeling better now :)
Btw, having an issue immediately closed by a bot and getting no reply is a little bit frustrating.

lgtmi

lgtm

@LeeShunEE

@LeeShunEE approved for issues and PRs. Your future issues and PRs will not be auto-closed.

See CONTRIBUTING.md.

Historical audit: this discussion was auto-closed by the legacy contributor gate. That closure did not assess technical importance.

Audit result: resolved. A later merged change or the current main implementation covers this request. This item is kept for history and does not need to be reopened.

Navigation Menu

Repository navigation

Add Grok Build CLI usage reporting #1513

What do you want to change?

Why?

How? (optional)

my env

Grok Token Usage — Temp Q&A

Q1. Where are tokens stored, and what are the TTL / retention rules?

one line of session updates.jsonl example containing token usage

Q2. Which location does ccusage use for token usage?

Q3. How are tokens extracted?

Line filter — `ccusage/rust/adapters/grok/src/parser.rs`

Field meaning on the wire — grok-build

Q4. How is `GROK_HOME` resolved?

Grok CLI (grok-build)

ccusage (feature branch)

PR ready

@ryoppippi

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add Grok Build CLI usage reporting #1513

Description

What do you want to change?

Why?

How? (optional)

Activity

pullfrog commented on Jul 28, 2026

github-actions commented on Jul 28, 2026

ryoppippi commented on Jul 28, 2026

LeeShunEE commented on Jul 28, 2026

my env

Grok Token Usage — Temp Q&A

Q1. Where are tokens stored, and what are the TTL / retention rules?

one line of session updates.jsonl example containing token usage

Q2. Which location does ccusage use for token usage?

Q3. How are tokens extracted?

Line filter — ccusage/rust/adapters/grok/src/parser.rs

Field meaning on the wire — grok-build

Q4. How is GROK_HOME resolved?

Grok CLI (grok-build)

ccusage (feature branch)

PR ready

LeeShunEE commented on Jul 28, 2026

LeeShunEE commented on Aug 7, 2026

@ryoppippi

ryoppippi commented on Aug 7, 2026

LeeShunEE commented on Aug 10, 2026

ryoppippi commented on Aug 10, 2026

ryoppippi commented on Aug 10, 2026

github-actions commented on Aug 10, 2026

ryoppippi commented on Aug 31, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Line filter — `ccusage/rust/adapters/grok/src/parser.rs`

Q4. How is `GROK_HOME` resolved?