🧠

grok-usage

Accurate, Grok-native context & token analytics for agentic development.

Grok Build's local logs only give cumulative context snapshots. Most tools produce misleading numbers. grok-usage gives you the right metrics: peak context and growth per logical session.

View on GitHub Get started

Credit & How This Is Different

This project draws strong inspiration from the excellent ccusage tool (reporting model, CLI style, JSON output, etc.). We are grateful for that foundation.

Note: A direct "Grok adapter" for ccusage would not be a good fit. ccusage is designed around standard per-turn usage data (input/output/cached tokens). Grok Build does not currently emit that kind of data for grok-build sessions — only cumulative snapshots. Trying to adapt it would require the kind of inaccurate estimation this tool deliberately avoids.

Important: Grok Build currently works differently from the competition.

Other major platforms (OpenAI, Anthropic, etc.) expose standard per-turn usage:

prompt_tokens / input_tokens
completion_tokens / output_tokens
total_tokens
Cache details (cached_tokens, cache_read_input_tokens, etc.)
Sometimes reasoning tokens or modality breakdowns

Grok Build (the local CLI) primarily only emits cumulative _meta.totalTokens snapshots for native grok-build paths. There are no clean per-turn input/output/cached/total numbers today.

As an agentic developer running optimization experiments (different prompts, markdown structures, reasoning modes, sub-agent policies, tool formatting, harness logic, etc.), accurate measurement of token and context usage is essential. You need trustworthy numbers to tune for cost, latency, and efficiency the same way you tune for output quality.

Security scanning in CI is powered by Snyk, which is free for open source projects. Thank you to Snyk for supporting the OSS community.

Protected operations run under the build-server GitHub Environment (secrets + optional approvals/restrictions).

grok-usage was built to solve exactly this: correct peak context + growth per logical session, plus agentic-specific signals (per-subagent awareness, high-context flags, rough costs based on real peaks). It aims to overdeliver for Grok power users rather than just match the baseline other tools provide.

For agentic developers

When you run experiments (control vs. different prompts, reasoning modes, sub-agent policies, markdown structures), you need trustworthy numbers to know what actually improved context efficiency, cost, or loopiness.

• Peak context reached (the expensive part)
• Net growth introduced by your changes
• Snapshot count (proxy for steps / tool calls)
• Rough cost estimates

Correct by design

Instead of summing every cumulative snapshot (which produces 30M–800M token lies), we calculate per-session peak and growth — the metrics that actually drive optimization decisions.

✓ 415k peak (real)

38 million "input tokens" (wrong)

Example output

Session                           Peak    Growth   Est. Cost
019ea4a8-6e7c-7f82-8dc7-c          415823  326015   $1.04
019f0fcc-707f-7bf1-a302-c          293519  250245   $0.73
019ea83d-86c5-71a2-a8f8-7          141984  117818   $0.36

Real data from recent sessions. Clean, comparable, useful.

Install

From source (recommended for now)

git clone https://github.com/YOURNAME/grok-usage.git
cd grok-usage
cargo build --release
cp target/release/grok-usage ~/.local/bin/

Prebuilt binaries

Binaries for macOS, Linux and Windows are built automatically via GitHub Actions whenever you push a version tag (e.g. v0.2.0) and are attached to Releases. The full build + security scanning configuration lives in the source at .github/workflows/release.yml and ci.yml (including Snyk scans), so everything is transparent and reproducible from source. Sensitive operations use the protected build-server GitHub Environment for extra controls (reviewers, branch restrictions, etc.). PRs run without it.

Optimize Grok Build + your agentic system

1. Run an experiment

Control run with your current best prompts/harness. Then a variant.

export GROK_DATA_DIR=~/.grok/sessions/%2Fpath%2Fto%2Fyour%2Fproject

# After control
grok-usage session --since 2026-06-20 --json > control.json

# After variant (new prompt structure, reasoning, sub-agent rules...)
grok-usage session --since 2026-06-21 --json > variant.json

2. Get insights

grok-usage insights --detailed --since 2026-06-20

Or load the optimizer skill and let Grok analyze for you.

3. Compare

grok-usage compare --baseline 2026-06-20 --current 2026-06-21

Useful extra commands

grok-usage report --since 2026-06-20 --format md → nice markdown for PRs or notes
grok-usage session --json → feed into your own scripts or LLM judge
grok-usage insights --detailed → actionable suggestions out of the box

The companion grok-usage-optimizer skill turns this data into intelligent suggestions inside Grok itself.

See the full README and skills/grok-usage-optimizer.md in the repo for installation and usage patterns.

Built to help people who treat Grok Build + agentic systems as something worth measuring and tuning properly.