slopmeter

The CLI exits with an error in the following scenarios:

• If provider flags are passed but the requested provider has no data.
• If no provider has any data available.
• If a JSONL record or OpenCode payload exceeds SLOPMETER_MAX_JSONL_RECORD_BYTES (this results in a clear error naming the file/line/byte cap).

The output format and filename behavior depend on your flags:

• Format Inference: If --format is omitted, the format is inferred from the --output extension. If neither --format nor a recognized extension is provided, PNG is used.
• Default Filenames: If --output is omitted, the filename is generated as follows:
  • Default: heatmap-last-year.<ext>
  • With explicit provider flags: heatmap-last-year_<providers>.<ext>
  • With --all: heatmap-last-year_all.<ext>
• Supported Extensions: .png, .svg, and .json.

# Write an SVG
slopmeter --format svg --output ./out/heatmap.svg

# Write JSON for custom rendering
slopmeter --format json --output ./out/heatmap.json

# Render a dark-theme SVG
slopmeter --dark --format svg --output ./out/heatmap-dark.svg

You can run slopmeter without a permanent installation using npx, or install it globally to use the slopmeter command directly.

Requirements

• Node.js >=22

# Run without installing
npx slopmeter

# Install globally
npm install -g slopmeter
slopmeter

To set up the slopmeter monorepo for development, use bun to install dependencies and run the check command.

bun install
bun run check

Depending on your environment, you can run the CLI in several ways:

1. From built output: After running bun run build, execute the compiled JS file with Node.
2. In dev mode: Use bun run with the --cwd flag pointing to the CLI package.
3. As a binary: If installed as a package binary, simply call slopmeter.

# Build once
bun run build

# Run from built output
node packages/cli/dist/cli.js

# Run the CLI package directly in dev mode
bun run --cwd packages/cli dev

# Or if installed as a package binary
slopmeter

The slopmeter CLI scans local usage data from various AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, Open Code, and Pi Coding Agent) and generates a contribution-style heatmap for the rolling past year.

By default, it scans all supported providers and writes a PNG file named ./heatmap-last-year.png.

slopmeter [--all] [--claude] [--codex] [--cursor] [--gemini] [--opencode] [--pi] [--dark] [--format png|svg|json] [--output ./heatmap-last-year.png]

When processing Gemini messages, tokens are categorized as follows:

• Input Tokens: Calculated as input + cached.
• Output Tokens: Calculated as output + thoughts + tool.
• Cache: Specifically tracks the cached value as input cache.

This ensures that 'thoughts' and 'tool' usage are correctly attributed to the total output consumption.

You can tune performance and memory limits using these environment variables:

You can tune the performance and limits of the CLI using the following environment variables:

• SLOPMETER_FILE_PROCESS_CONCURRENCY: A positive integer setting the file-processing limit for Claude Code and Codex JSONL files. Default: 16.
• SLOPMETER_MAX_JSONL_RECORD_BYTES: The byte cap for records in Claude Code/Codex JSONL, OpenCode JSON, and OpenCode SQLite message.data payloads. Default: 67108864 (64 MB).

The AgentUsageHeatmap uses CSS variables to drive its color scales based on the variant prop. When using a specific variant, the component applies a set of CSS variables (--heatmap-0 through --heatmap-4) to the container. These variables map to provider-specific color scales defined in your global CSS.

Supported variants and their corresponding CSS variable mappings:

• claude: --heatmap-claude-0 to --heatmap-claude-4
• codex: --heatmap-codex-0 to --heatmap-codex-4
• cursor: --heatmap-cursor-0 to --heatmap-cursor-4
• opencode: --heatmap-opencode-0 to --heatmap-opencode-4
• pi: --heatmap-pi-0 to --heatmap-pi-4

Slopmeter provides granular breakdowns of token usage and high-level insights into usage patterns.

Model Usage

Each entry in a breakdown or an insights object uses the ModelUsage structure to describe token counts for a specific model:

• name: The name of the model.
• tokens: An object containing input, output, cache (with input and output), and total counts.

Insights

The Insights object provides summarized intelligence about usage:

• mostUsedModel?: The model with the highest overall usage.
• recentMostUsedModel?: The model most frequently used in the recent period.
• streaks: An object containing longest and current usage streak counts.