grok-usage

A Grok-first, portable, high-performance terminal tool + skill for analyzing xAI Grok Build token and context usage.

Designed to help agentic developers get accurate, actionable data for optimizing Grok Build itself, agentic harnesses (sub-agents, tools, resume patterns), instructions/prompts, and source code.

Credit and relation to ccusage

This tool draws strong inspiration from the excellent ccusage project. We reuse many of the same high-level ideas around reports, JSON output, date filtering, and CLI experience.

However, Grok Build currently works differently from the competition, which creates unique challenges:

• Most other vendors (OpenAI, Anthropic, etc.) expose clean per-turn usage in their APIs and tooling:

  • prompt_tokens / input_tokens
  • completion_tokens / output_tokens
  • total_tokens
  • Cache details (cached_tokens, cache_read_input_tokens, cache_creation_input_tokens)
  • Sometimes reasoning tokens or other breakdowns

• Grok Build (the local CLI) primarily only emits cumulative _meta.totalTokens snapshots. There is no standard per-turn input / output / cached / total breakdown for native grok-build paths.

This is a real limitation today for anyone doing serious agentic work. As an agentic developer who runs optimization experiments (control vs. variants with different prompts, markdown structures in instructions, reasoning modes, tool output formatting, sub-agent policies, etc.), having reliable token and context metrics is essential. You need to measure, compare, and tune for cost, latency, and context efficiency the same way you tune for output quality.

Most tools that simply sum the cumulative values produce wildly inflated and useless numbers (38M–800M+ "tokens" when the actual peak context usage in a session was only a few hundred thousand). This makes quantitative optimization extremely difficult.

Why grok-usage is different

grok-usage was built specifically for Grok's data format and for agentic optimization loops:

• It correctly computes Peak Context (the highest context window size reached) and Growth (net new context introduced) per logical session instead of summing every cumulative snapshot.
• It focuses on the metrics that actually matter for long-running agents and harnesses (peak pressure, growth rate, snapshot efficiency, model-specific behavior).
• It goes beyond matching what others provide by surfacing agentic-relevant signals (per-subagent session awareness, high-context warnings, efficiency heuristics, rough cost estimates based on real peaks).
• It ships with an accompanying skill so Grok itself can help you analyze runs and turn the numbers into concrete improvements to instructions, harness configuration, and source code.

In short: it gives you accurate, usable data to actually optimize Grok Build + your agentic system instead of guessing or fighting misleading aggregates.

Credit to ccusage

This project draws strong inspiration from the excellent ccusage tool. We reuse many of the same high-level ideas around reports, JSON output, date filtering, and a pleasant CLI experience. We are grateful for that foundation.

Note that a "Grok adapter" for ccusage would not be a natural fit. ccusage is built around standard per-turn usage data (prompt_tokens / input_tokens, completion_tokens / output_tokens, cached tokens, etc.). Grok Build currently does not emit that kind of data for grok-build sessions — it only provides cumulative totalTokens snapshots. Trying to force Grok data into ccusage's model would require estimating or summing in ways that produce inaccurate results (which is exactly the problem this library was created to avoid).

This is why a dedicated library makes sense: it works directly with what Grok actually emits, deriving the most meaningful signals possible (peak context and growth per logical session) rather than trying to emulate data that isn't there.

Grok Build's current data model

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, cache_creation_input_tokens)
• 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 in the local logs today.

As an agentic developer, being able to accurately measure and optimize token/context usage is critical. You run experiments with different instructions, markdown structures, reasoning modes, sub-agent patterns, and harness logic. Without trustworthy numbers you cannot know whether a change improved (or hurt) cost, latency, or context efficiency.

Most existing tools that simply sum the cumulative snapshots produce wildly misleading results (38M–800M+ "input tokens" when the actual peak context in a session was only a few hundred thousand). This is exactly the problem grok-usage was built to solve.

How grok-usage is different (and aims to overdeliver)

This tool does not try to pretend Grok emits the same data as other platforms. Instead, it works within the data Grok actually provides (cumulative totalTokens snapshots) and extracts the most useful, accurate signals possible for real agentic work:

• Correct Peak Context (highest context window reached) and Growth (net new context introduced) per logical session — instead of summing every snapshot.
• Strong support for agentic patterns (per-directory sub-agent awareness, resume_from flows, high-context detection).
• Rough but grounded cost estimates based on actual peaks and the model used.
• An accompanying skill so Grok can help analyze runs and propose improvements to prompts, instructions, harness logic, and code.
• Actionable commands (insights, compare, report) built specifically for control-vs-variant optimization.

The goal is not to match other tools on their data model, but to give Grok users meaningful numbers they can actually use to optimize.

Why This Tool Exists (technical background)

Grok Build only emits cumulative _meta.totalTokens snapshots. Most other tools sum these values, producing wildly inflated and useless numbers (38M–800M+ "tokens" when real peak context was < 500k).

grok-usage gives you the correct, comparable metrics:

• Peak Context — highest context window size reached (the number that actually drives cost, latency, and quality)
• Growth — net new context introduced during the session
• num_snapshots (proxy for turns/tool calls)
• Rough cost estimates
• Per logical session (each directory = one conversation or sub-agent run)

These are the numbers that let you run real optimization experiments instead of guessing.

Installation (one line)

# One-liner (recommended)
curl -fsSL https://raw.githubusercontent.com/simnova/grok-usage/main/install.sh | bash

Or manually:

cd /path/to/grok-usage
cargo build --release
cp target/release/grok-usage ~/.local/bin/   # or anywhere in $PATH

Single static binary. No runtime dependencies.

After install, add ~/.local/bin to your PATH if it isn't already:

export PATH="$HOME/.local/bin:$PATH"

Test:

grok-usage --help

Prebuilt Binaries

Binaries for macOS (Intel + Apple Silicon), Linux, and Windows are automatically built and attached to GitHub Releases whenever a new version tag (e.g. v0.2.0) is pushed.

The entire build process is defined in the repository source under .github/workflows/release.yml (and basic CI verification in ci.yml), so you can always see exactly how the binaries are produced from source.

CI and Release Process

• On every push and PR to main: the project is built and tested on Ubuntu, macOS, and Windows. Dependency vulnerability scanning is performed with Snyk (see .github/workflows/ci.yml).
• On new version tags (e.g. git tag v0.2.0 && git push --tags): full multi-platform release binaries are produced and uploaded (see .github/workflows/release.yml).

Sensitive operations (Snyk token access and release builds) run under the protected build-server GitHub Environment. This allows additional controls such as required reviewers or branch restrictions (configured in repo settings). On PRs the environment is not used so scans still run for forks.

Core Usage

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

# Best for optimization work
grok-usage session --limit 30 --json
grok-usage session --since 2026-06-20 --json > before.json

# Daily trends
grok-usage daily --since 2026-06-01

# Actionable optimization insights (recommended)
grok-usage insights --detailed

Important JSON Fields for Optimization

• peak_context: Your #1 metric to minimize (while holding quality constant).
• growth: How much the context expanded. High growth usually points to verbose instructions or missing summarization.
• num_snapshots: Rough measure of agent "chattiness".
• estimated_cost_peak / estimated_cost_growth: Ballpark costs using the dominant model in the session.
• models: Which backend was used.

Optimization Workflow

1. Run your current best configuration (control) on a fixed set of tasks.
2. Capture:

   grok-usage session --since <start> --json > control.json

3. Change one thing (prompt structure, reasoning instruction, sub-agent policy, tool result formatting, code, etc.).
4. Run the variant on the same tasks.
5. Capture new data.
6. Compare peaks and growth (lower peak + lower growth + same/better quality = win).
7. Use the optimizer skill (see below) to turn the numbers into the next concrete change.

Repeat.

This is how you turn "I think this prompt is better" into measurable improvements in context efficiency, cost, and reliability.

The grok-usage-optimizer Skill

The most powerful way to use this tool is with the companion skill.

Install the Skill

mkdir -p ~/.grok/skills
cp skills/grok-usage-optimizer.md ~/.grok/skills/

(You may also need to reference it in your .grok/config.toml.)

Once loaded, you can talk to Grok like this:

• "Use grok-usage to analyze the last two days and tell me whether variant-B was better on context."
• "Run grok-usage insights on everything since last week and give me the top 3 things causing high peak context."
• "Compare control vs the new sub-agent instructions. Suggest the next minimal experiment based on the growth numbers."

The skill knows how to invoke the binary, interpret the metrics, map bad numbers to common agentic anti-patterns, and propose testable improvements to instructions, harness logic, or code.

See skills/grok-usage-optimizer.md for the full skill definition.

Full Optimization Loop (with Skill)

1. Baseline run + grok-usage ... --json
2. One deliberate change
3. Variant run + new data
4. Ask Grok (with the optimizer skill) to analyze using the tool output
5. Apply the highest-leverage suggestion
6. Repeat

The combination of accurate local metrics + an agent that knows how to interpret them for Grok-specific agentic work is extremely effective.

Environment Variables

• GROK_DATA_DIR — strongly recommended. Point it at the encoded session directory for the specific project you're optimizing.
• GROK_HOME

Development

cargo run -- session --limit 5
cargo run -- insights --detailed
cargo build --release

Philosophy

• Correct semantics for Grok's actual data format (peak + growth, not summed snapshots).
• Numbers that drive real decisions when tuning agentic systems.
• Extremely portable and scriptable.
• Purpose-built to help people get the best possible results out of Grok Build + complex agent harnesses.

Built with ❤️ for developers who treat prompt engineering, harness design, and context management as first-class engineering problems.

Credit to Snyk

This project uses Snyk for automated dependency and vulnerability scanning as part of CI. Snyk is free for open source projects, and we are grateful for the support they provide to the OSS community.

Security scanning is configured in .github/workflows/ci.yml (and protected via the build-server GitHub Environment for secrets and controls). The Snyk badge above reflects the current status of the main branch.

License

This project is licensed under the MIT License — see the LICENSE file for details.