Codex Usage Profiler

Find where your agentic coding budget actually went.

Codex Usage Profiler is a local, read-only investigation tool for Codex session logs. It turns local JSONL sessions and optional CodexBar telemetry into a compact dashboard and reports grouped by tool, project, task, staff, time, model, tokens, directional rate-card cost, and review-candidate patterns.

It is designed to answer:

• Which apps and harnesses are using the most tokens?
• Which projects, tasks, and sessions deserve inspection?
• When did usage happen?
• Which repeated patterns may be wasting quota?
• Where is attribution too weak to trust?

It is not an official billing, quota, or productivity system. Cost values are directional rate-card replacement-cost estimates. Current quota windows come from CodexBar when available, but historical local sessions are not automatically converted into true subscription quota consumption. Outcome labels are evidence buckets, not judgments.

Two-Minute Demo

git clone https://github.com/saphid/codex-usage-profiler.git
cd codex-usage-profiler
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .

codex-usage-dashboard --report samples/demo-report.json

Open the printed local URL, usually http://127.0.0.1:8765/.

You should see a dark dashboard with:

• Summary cards for sessions, tokens, rate-card cost, live quota, durable-output signals, and review candidates.
• A Sankey/alluvial flow from client to project to staff to outcome.
• Hourly timeline, day/hour heatmap, ranked comparisons, attribution coverage, and cleanup projection.
• A sortable session table and evidence drawer.

Profile Your Local Logs

Default scan:

codex-usage-profiler

Common reports:

codex-usage-profiler --days 7 --top 20
codex-usage-profiler --since 2026-06-24
codex-usage-profiler --format json --output reports/latest.json
codex-usage-profiler --days 14 --monthly-plan-price-usd 200 --plan-price Plus=20 --plan-price Pro=200
codex-usage-dashboard --report reports/latest.json

Use explicit paths when you want a bounded scan:

codex-usage-profiler --no-codexbar --paths ~/.codex/sessions

Raw prompt and response bodies are not printed by default. Use --include-snippets only when you explicitly want bounded redacted task snippets in JSON/text output.

Network Collection

For multi-machine setups, install the collector on each host and run the dashboard/report refresh on one always-on machine:

codex-usage-collector --print-default-config > ~/.config/codex-usage-profiler/collector.json
codex-usage-collector --config ~/.config/codex-usage-profiler/collector.json --once

The collector scans configurable JSON/JSONL session globs for Codex, Claude, Pi, T3Chat, Kimi, droid, Cursor, OpenCode, and Paperclip, stages changed files with metadata sidecars, and pushes them to the configured central destination. Linux systemd user units, macOS launchd plist, LXSO report refresh, dashboard service, and a rootless high-port .lan proxy are under ops/.

Central LXSO pattern:

ops/bin/codex-usage-run-report.sh
codex-usage-dashboard --report ~/.local/state/codex-usage-profiler/latest-report.json --host 0.0.0.0 --port 8775

Collector, report-refresh, and dashboard access events are written as JSONL and can also be forwarded to Orange Pi syslog and LXSO2 Loki. In Grafana, query Loki with {job="codex-usage-profiler"} and narrow by service="collector", service="report", or service="dashboard".

What The Tool Produces

• Usage grouped by client, project, task, model, day, hour, Paperclip company, Paperclip staff, and Paperclip task.
• Paperclip company spend by day/month, company 30-day projections, and configurable plan-price comparisons.
• Top sessions by observed tokens and rate-card cost.
• Current CodexBar quota windows when CodexBar is installed.
• CodexBar local-vs-cache ratio rows to reveal scope mismatch.
• Review candidates such as repeated command signatures, no-op automation, repeated queries, startup-heavy sessions, and test loops.
• A local dashboard for filtering, charting, exporting, and inspecting evidence.

How To Read The Numbers

• Tokens: observed tokens found in local session logs.
• Rate-card cost: directional replacement-cost estimate from known model rates or CodexBar pricing caches.
• Live quota now: current CodexBar quota window, not a historical usage allocation.
• Plan comparison: projected local rate-card replacement cost vs configured plan price; useful for value/scale decisions, not official quota reconstruction.
• Observed share: share of tokens within the scanned local logs.
• Durable output: sessions with observable output signals such as edits, tests, commits, PRs, or action tools. This does not prove end-user value.
• Review candidates: sessions matching patterns worth inspecting. These can overlap with durable-output sessions.
• Confidence: weakest key attribution signal across client, project, staff, and task.

CodexBar

The profiler intentionally leans on Peter Steinberger's CodexBar when available instead of reimplementing its auth and provider logic.

Supported local inputs:

• codexbar usage --provider codex --source auto --format json
• codexbar cost --provider codex --format json
• ~/Library/Application Support/com.steipete.codexbar/history/codex.json
• ~/Library/Caches/CodexBar/cost-usage/codex-v*.json
• ~/Library/Caches/CodexBar/cost-usage/pi-sessions-v*.json
• ~/Library/Caches/CodexBar/model-pricing/models-dev-v*.json

CodexBar is MIT licensed. This project uses its public CLI/cache outputs and gives attribution here.

OpenSpec Story

This project was built with OpenSpec as an explicit design trail:

• openspec/changes/build-usage-profiler/: ingestion, attribution, quota/cost estimates, outcome evidence, reporting.
• openspec/changes/add-session-dashboard-ui/: compact dashboard, user stories, mockup validation, interaction contract.
• openspec/changes/add-network-session-collection/: multi-host collection, LXSO deployment, .lan access, and Grafana-visible logging.
• docs/dashboard-final-interaction-contract.md: card-by-card interaction expectations.
• docs/critical-review.md: subagent critique summary and which critical fixes were accepted.

Architecture

flowchart LR
  A["Codex JSONL sessions"] --> B["Ingest + normalize"]
  C["CodexBar CLI/cache"] --> D["Quota + rate-card context"]
  E["Paperclip paths/metadata"] --> F["Attribution"]
  B --> F
  D --> G["Estimates + ratios"]
  F --> H["Outcome evidence + review candidates"]
  G --> I["JSON/text report"]
  H --> I
  I --> J["Local dashboard"]

Loading

Tests

PYTHONPATH=src python3 -m unittest discover -q
npm install
npm test
openspec validate add-session-dashboard-ui --strict
openspec validate build-usage-profiler --strict

The E2E dashboard test launches a local server with synthetic data, drives the browser through filters/charts/drawer/export, and saves a screenshot under reports/. It uses Google Chrome or Chromium; set CUP_E2E_CHROME=/path/to/chrome if your browser is somewhere unusual.

Limitations

• Local logs may be incomplete or duplicated across harnesses.
• Cost is a directional replacement-cost estimate, not an invoice.
• Live quota is current-window telemetry, not historical allocation.
• CodexBar ratio rows can show scope mismatch, not just missing data.
• Paperclip staff usually means agent role; task labels are strongest when explicit issue/task IDs are present.
• Review candidates are prompts for inspection; repeated command signatures are not proof of failed retry loops.

License

MIT. See LICENSE.