AI Coding Usage Tracker

Local-first usage analytics for Codex, Claude Code, and Cursor.

Repo: github.com/SuvenSeo/ai-coding-usage-tracker · CLI: ai-coding-usage-tracker · PyPI: codex-usage-tracker · v0.2.6

AI Coding Usage Tracker reads local AI coding data and generates a private
dashboard for token usage, app/source totals, estimated Codex credits,
estimated USD, project breakdowns, terminal reports, and optional WakaTime
ai coding time.

Why

AI coding tools can burn through tokens, but it is hard to answer basic questions:

• Which project used the most tokens?
• Which thread was the most expensive?
• How much active AI coding time did I spend today?
• How much of my input was cached?
• Can my Codex app activity show up in WakaTime?

This tool gives you those answers locally, without uploading Codex transcripts to another service.

Features

• Reads local Codex app rollout logs from ~/.codex
• Reads Claude Code project transcripts from ~/.claude/projects
• Reads Cursor from Agent transcripts, Composer bubbles, agentKv cache, and the AI tracking DB
• Estimates Cursor tokens with Claude-style context cache replay when exact counts are missing locally
• Generates HTML, CSV, and JSON reports
• Serves a live local web dashboard with auto-refresh on 127.0.0.1
• Shows trend bars, provider comparison tabs, budget signals, and connector status
• Native GUI with combined lifetime totals, per-app cards, brand logos, and a Lifetime Totals tab
• GUI disk cache for instant startup and incremental refresh across Codex, Claude, and Cursor logs
• Prints daily, weekly, monthly, session, project, model, and source terminal reports
• Estimates Codex credits from input, cached input, and output tokens
• Shows estimated USD for Codex, Claude Code, and Cursor where local token logs and known rates exist
• Checks optional official billing connectors without printing configured keys
• Includes doctor and demo commands for first-run confidence
• Supports date filters with --days, --since, --until, and --timezone
• Supports share-safe output with --redact and --hash-projects
• Sends optional WakaTime ai coding heartbeats
• Works without an OpenAI API key

Install

Install from PyPI with pipx:

pipx install codex-usage-tracker
ai-coding-usage-tracker demo

Or install with pip:

python -m pip install codex-usage-tracker
ai-coding-usage-tracker demo

The PyPI package is still named codex-usage-tracker for compatibility. New
installs expose ai-coding-usage-tracker; the legacy codex-usage-tracker
command remains available.

For local development, clone the repo:

git clone https://github.com/SuvenSeo/ai-coding-usage-tracker.git
cd ai-coding-usage-tracker

Run directly with Python:

python codex_app_tracker.py report

Or install the CLI locally:

pip install -e .
ai-coding-usage-tracker report

Windows users can also download AICodingUsageTracker.exe from the
latest release.
The release includes a SHA256 checksum file.

Quick Start

Check your machine:

ai-coding-usage-tracker doctor

Generate the full local dashboard:

ai-coding-usage-tracker report

Include Codex, Claude Code, and Cursor in one report:

ai-coding-usage-tracker --sources all report

Open:

out/dashboard.html

Serve a live local web dashboard:

ai-coding-usage-tracker --sources all --days 14 serve

By default this opens http://127.0.0.1:8765/, reloads the page every 10
seconds, and keeps all data local. Use serve --port 0 --no-open when you want
an auto-selected port without launching a browser.

Open the live native desktop dashboard:

ai-coding-usage-tracker --sources all gui

The GUI uses Python's built-in Tkinter toolkit and polls selected local sources
every 10 seconds by default. It opens in dark mode and shows:

• Overview — combined lifetime hero with token-mix bars and a provider donut,
  Codex / Claude / Cursor cards with cached token breakdown and brand logos,
  quick stats, app/daily charts, and a live activity indicator
• Lifetime Totals — full provider table plus project/model charts
• Apps, Daily, Projects, Models, Threads, Signals, Billing — sortable tables
  (large tables are capped for responsiveness; HTML report keeps the full dataset)

On launch, the GUI restores the last dashboard from
~/.codex-usage-tracker/report_cache/ when available, then syncs in the
background. Incremental refresh re-parses only log files whose size or
modification time changed.

The packaged Windows EXE defaults to --sources all. The first Cursor refresh can
take up to a minute while local transcripts and cache blobs are scanned.

Buttons include Refresh now, HTML report, and Open live web dashboard.
Change the refresh interval with:

ai-coding-usage-tracker gui --refresh-seconds 5

After rebuilding the EXE, update Desktop and Start Menu shortcuts:

.\scripts\build_windows_exe.ps1
.\scripts\install_windows_app.ps1

Close the running app first if the install step reports the EXE is in use.

Try a safe public demo:

ai-coding-usage-tracker demo

That writes synthetic reports to out/demo/.

Build a double-clickable Windows EXE:

python -m pip install -e ".[build]"
.\scripts\build_windows_exe.ps1

The generated app is written to dist\AICodingUsageTracker.exe. Double-clicking it
opens the live GUI with Codex, Claude Code, and Cursor selected. It reads only
local data folders on your machine and bundles provider brand logos from
assets/gui/brands/.

Install it as a normal user-level Windows app:

.\scripts\install_windows_app.ps1

That copies the EXE to %LOCALAPPDATA%\Programs\AICodingUsageTracker and creates
Start Menu plus Desktop shortcuts. Remove it with:

.\scripts\uninstall_windows_app.ps1

CLI Reports

Global scope and privacy flags go before the command:

ai-coding-usage-tracker --days 7 daily
ai-coding-usage-tracker --since 2026-05-01 --until 2026-05-24 weekly
ai-coding-usage-tracker --timezone Asia/Colombo monthly
ai-coding-usage-tracker --sources all source
ai-coding-usage-tracker session --limit 10 --compact
ai-coding-usage-tracker project --format json
ai-coding-usage-tracker model --format csv

Create a share-safe report:

ai-coding-usage-tracker --sources all --redact --hash-projects report

Source selection is opt-in. The default is --sources codex; use
--sources claude, --sources cursor, or a comma-separated list such as
--sources codex,claude.

Audit every local and official source the tracker knows about:

ai-coding-usage-tracker --sources all source-audit

The audit writes out/source_audit.json and out/source_audit.md. It separates
exact local metrics from estimates and blocked sources. Cursor token totals are
estimated from local Agent transcripts, Composer bubbles, and agentKv blobs
with context-cache replay (similar in spirit to Claude's cache-read accounting).
Vendor admin APIs can provide deeper billing detail only when the matching admin
key is configured.

Check optional official billing connector status:

ai-coding-usage-tracker billing

Set provider admin keys only when you want official account-side checks, then
run an explicit fetch:

ai-coding-usage-tracker billing --fetch --format json

Supported environment variable names are OPENAI_ADMIN_KEY,
ANTHROPIC_ADMIN_KEY, and CURSOR_ADMIN_API_KEY. Keys are never printed.

Add dashboard budget signals with global flags before the command:

ai-coding-usage-tracker --sources all --daily-token-budget 250000 --daily-usd-budget 5 --monthly-usd-budget 100 report

WakaTime

WakaTime sync is optional. It requires wakatime-cli and a normal ~/.wakatime.cfg file.

Generate reports and sync recent Codex activity:

ai-coding-usage-tracker run --sync-wakatime

The tracker sends conservative heartbeats with:

• category: ai coding
• entity type: app
• project name/folder
• timestamp

It does not send prompts, responses, transcripts, or token totals to WakaTime.
WakaTime sync currently uses Codex records only; Claude Code and Cursor are
included in reports but not synced as WakaTime heartbeats.

On Windows, you can install a scheduled task:

.\install_scheduled_task.ps1

Remove it:

.\uninstall_scheduled_task.ps1

Output

By default, reports are written to out/:

• dashboard.html
• codex_usage_summary.json
• threads.csv
• daily.csv
• sources.csv
• projects.csv
• models.csv
• source_audit.json and source_audit.md (from source-audit)

The GUI also writes a local disk cache under ~/.codex-usage-tracker/report_cache/
for faster startup and incremental refresh. That cache can include token totals,
project names, and thread metadata from your machine.

Do not commit generated reports. They can include private local paths, project names, thread titles, and usage details unless you use privacy flags.

Cost Estimates

The tracker reports local token counts where app logs provide them.

Cost estimates are not an invoice:

• estimated_codex_credits uses OpenAI's current Codex token-based rate card for Codex records.
• estimated_api_usd_equiv uses public OpenAI API standard short-context prices for Codex and Anthropic token prices for Claude Code when known local model rates exist.
• Cursor totals are estimates from local logs: Agent transcripts under
  ~/.cursor/projects, Composer bubbles and agentKv blobs in Cursor's
  state.vscdb, plus AI edit activity from ~/.cursor/ai-tracking. When Cursor
  stores zero token counts, the tracker estimates from character length and
  applies context-cache replay so cached input is visible like Claude Code.
• The included rates were verified against official OpenAI and Anthropic docs on 2026-05-31.
• Real billing/credit balance, fast-mode uplifts, taxes, and any workspace exceptions should be checked with the vendor.

Pricing can change. The current source pages are OpenAI's Codex rate card, OpenAI API pricing, Anthropic Claude pricing, and Cursor pricing. Review and update MODEL_RATES in codex_app_tracker.py when vendor rates change.

Privacy

This is a local parser. Depending on --sources, it reads from ~/.codex,
~/.claude/projects, ~/.cursor/projects (Agent transcripts),
%APPDATA%\Cursor\User\globalStorage\state.vscdb (Composer/agent cache), and/or
~/.cursor/ai-tracking. It writes local reports.

Use --redact to hide thread titles, local folders, and log paths. Use --hash-projects to replace project names with stable anonymous labels.

See docs/PRIVACY.md before sharing dashboards or CSV files.

Comparison

The near-term goal is to keep Codex as the deepest parser while adding honest local visibility for adjacent AI coding tools.

Development

Repository layout:

Run checks:

python -m py_compile codex_app_tracker.py report_cache.py gui_visuals.py
python -m unittest discover -s tests -v

Build package artifacts:

python -m pip install build
python -m build

New contributors can start with
good first issues
or the current roadmap. See CONTRIBUTING.md
for the privacy rules and PR checklist.

Roadmap

See docs/ROADMAP.md.

Architecture

See docs/ARCHITECTURE.md for module layout, data flow, parsers, and output surfaces.

GitHub Profile

Repo description, topics, and social copy: docs/GITHUB_PROFILE.md.
Repository rename options: docs/RENAMING.md.

Built By

Built by SuvenSeo for developers who want local visibility into AI coding usage.

Status

Early alpha. Codex, Claude Code, and Cursor local storage formats may change, so
parser compatibility can break. v0.2.6 adds a GUI disk cache for instant
startup and incremental refresh, bundled provider brand logos, and responsive
table caps for large local histories. The Python package is published on
PyPI and can be installed with
pipx install codex-usage-tracker or python -m pip install codex-usage-tracker.
Issues and PRs are welcome.