claude-code-tracker

Automatic token usage, cost estimation, and prompt quality tracking for Claude Code sessions.

After every session, it parses the transcript, updates a tokens.json ledger, regenerates a Chart.js dashboard (charts.html), and rebuilds the key-prompts index. Zero external dependencies — pure bash and Python stdlib.

What it tracks

• Token usage per session: input, cache write, cache read, output
• Estimated API cost (list-price equivalent — not a subscription charge)
• Per-model breakdown: Opus vs Sonnet cost split
• Key prompts: high-signal prompts you log manually, with category and context
• Prompt efficiency: ratio of key prompts to total human messages

All data lives in <project>/.claude/tracking/ alongside your code.

Install

Option 1 — npm (global)

npm install -g claude-code-tracker

The postinstall script copies the tracking scripts to ~/.claude/tracking/ and registers the Stop hook in ~/.claude/settings.json.

Option 2 — Homebrew

Homebrew only knows about packages in its default registry. brew tap adds a third-party repository so Homebrew can find this package.

brew tap kelsi-andrewss/claude-code-tracker
brew install claude-code-tracker
claude-tracker-setup

The claude-tracker-setup command registers the Stop hook in ~/.claude/settings.json. This must be run separately because Homebrew's install sandbox blocks writes to user directories.

Option 3 — git clone

git clone https://github.com/kelsi-andrewss/claude-code-tracker.git
cd claude-code-tracker
./install.sh

Restart Claude Code after any install method.

Backfilling historical sessions

The installer automatically backfills all pre-existing sessions for the current project. If you run install.sh from inside a git repo, any transcripts that exist in ~/.claude/projects/ for that project will be parsed and added to tokens.json with their original dates. Re-running install won't create duplicates.

To backfill manually (e.g. for a different project):

python3 ~/.claude/tracking/backfill.py /path/to/your/project

What gets created

On first use in a project, the Stop hook auto-initializes <project>/.claude/tracking/:

.claude/tracking/
  tokens.json          # session data (auto-updated)
  charts.html          # Chart.js dashboard (auto-updated)
  key-prompts.md       # index of logged prompts
  key-prompts/         # one .md per day
    2026-02-18.md
  cost-analysis.md     # template for manual notes
  ai-dev-log.md        # template for dev log
  sessions.md          # session log template

View the dashboard

Open charts.html in a browser:

open .claude/tracking/charts.html       # macOS
xdg-open .claude/tracking/charts.html  # Linux

The dashboard shows cumulative cost, cost per day, sessions, output tokens, model breakdown, and prompt analytics — all updated automatically after each session.

Cost CLI

claude-tracker-cost
# or
python3 ~/.claude/tracking/cost-summary.py

Prints a cost summary table for the current project.

Logging key prompts

Add entries to <project>/.claude/tracking/key-prompts/YYYY-MM-DD.md (today's date). The index and charts update automatically on the next session end.

Entry format:

## 2026-02-18 — Short title

**Category**: breakthrough | bug-resolution | architecture | feature
**Context**: What problem was being solved?
**The Prompt**: (exact or close paraphrase)
**Why It Worked**: (what made the phrasing/framing effective)
**Prior Attempts That Failed**: (for bugs: what didn't work; otherwise: N/A)

Auto-logging with CLAUDE.md

Add the following to your project's CLAUDE.md to have Claude log prompts automatically:

## Tracking
After completing significant work (bug fix, feature, refactor, plan approval), append a prompt
assessment entry to `<project>/.claude/tracking/key-prompts/YYYY-MM-DD.md` (today's date).
Create the file if it doesn't exist, using the same header format as existing files.

Use this format:
  ## [date] — [short title]
  **Category**: breakthrough | bug-resolution | architecture | feature
  **Context**: What problem was being solved?
  **The Prompt**: (exact or close paraphrase)
  **Why It Worked**: (what made the phrasing/framing effective)
  **Prior Attempts That Failed**: (for bugs: what didn't work; otherwise: N/A)

Only write entries for genuinely high-signal prompts. Skip routine exchanges.
Do not ask permission — just append after significant work.

Uninstall

npm

npm uninstall -g claude-code-tracker
~/.claude/tracking/uninstall.sh

Homebrew

brew uninstall claude-code-tracker

Manual

./uninstall.sh

The uninstaller removes the scripts from ~/.claude/tracking/ and removes the Stop hook from ~/.claude/settings.json. Your project tracking data (tokens.json, charts.html, key-prompts/) is left intact.

Skills

install.sh copies bundled Claude Code skills into ~/.claude/skills/ automatically. Skills are slash commands available in any Claude Code session.

/view-tracking

Opens the tracking dashboard and today's key-prompts file for the current project.

/view-tracking

• macOS: opens files with open
• Linux / WSL: opens files with xdg-open (falls back to printing the path if unavailable)

Cost note

Figures shown are API list-price equivalents — what pay-as-you-go API customers would be charged at current Anthropic pricing. If you are on a Max subscription, these are not amounts billed to you.

Current rates used: | Model | Input | Cache write | Cache read | Output | |-------|-------|-------------|------------|--------| | Sonnet | $3/M | $3.75/M | $0.30/M | $15/M | | Opus | $15/M | $18.75/M | $1.50/M | $75/M |

License

MIT