claude-code-tracker 1.0.0

package/README.md

@@ -0,0 +1,169 @@
+# claude-code-tracker
+
+Automatic token usage, cost estimation, and prompt quality tracking for [Claude Code](https://claude.ai/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)
+
+```bash
+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
+
+```bash
+brew tap ${YOUR_USER}/claude-code-tracker
+brew install claude-code-tracker
+```
+
+### Option 3 — git clone
+
+```bash
+git clone https://github.com/kelsi-andrewss/claude-code-tracker.git
+cd claude-code-tracker
+./install.sh
+```
+
+Restart Claude Code after any install method.
+
+---
+
+## 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:
+
+```bash
+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
+
+```bash
+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:
+
+```markdown
+## 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:
+
+```markdown
+## 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
+```bash
+npm uninstall -g claude-code-tracker
+~/.claude/tracking/uninstall.sh
+```
+
+### Homebrew
+```bash
+brew uninstall claude-code-tracker
+```
+
+### Manual
+```bash
+./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.
+
+---
+
+## 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

package/install.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INSTALL_DIR="$HOME/.claude/tracking"
+SETTINGS="$HOME/.claude/settings.json"
+
+echo "Installing claude-code-tracker..."
+
+# Copy scripts
+mkdir -p "$INSTALL_DIR"
+cp "$SCRIPT_DIR/src/"*.sh "$SCRIPT_DIR/src/"*.py "$INSTALL_DIR/"
+chmod +x "$INSTALL_DIR/"*.sh "$INSTALL_DIR/"*.py
+
+echo "Scripts installed to $INSTALL_DIR"
+
+# Patch settings.json — add Stop hook if not already present
+python3 - "$SETTINGS" "$INSTALL_DIR/stop-hook.sh" <<'PYEOF'
+import sys, json, os
+
+settings_file = sys.argv[1]
+hook_cmd = sys.argv[2]
+
+data = {}
+if os.path.exists(settings_file):
+    try:
+        with open(settings_file) as f:
+            data = json.load(f)
+    except Exception:
+        data = {}
+
+hook_entry = {"type": "command", "command": hook_cmd, "timeout": 30, "async": True}
+hooks = data.setdefault("hooks", {})
+stop_hooks = hooks.setdefault("Stop", [])
+
+# Check if already registered
+for group in stop_hooks:
+    for h in group.get("hooks", []):
+        if h.get("command") == hook_cmd:
+            print("Hook already registered.")
+            sys.exit(0)
+
+stop_hooks.append({"hooks": [hook_entry]})
+
+os.makedirs(os.path.dirname(os.path.abspath(settings_file)), exist_ok=True)
+with open(settings_file, 'w') as f:
+    json.dump(data, f, indent=2)
+    f.write('\n')
+print("Hook registered in", settings_file)
+PYEOF
+
+echo "claude-code-tracker installed. Restart Claude Code to activate."

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "claude-code-tracker",
+  "version": "1.0.0",
+  "description": "Automatic token, cost, and prompt tracking for Claude Code sessions",
+  "keywords": ["claude", "claude-code", "anthropic", "tracking", "cost", "tokens"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kelsi-andrewss/claude-code-tracker"
+  },
+  "scripts": {
+    "postinstall": "bash ./install.sh"
+  },
+  "bin": {
+    "claude-tracker-cost": "./src/cost-summary.py"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "src/",
+    "install.sh",
+    "uninstall.sh",
+    "README.md"
+  ]
+}

package/src/cost-summary.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Usage:
+  python3 cost-summary.py <tokens.json>
+  python3 cost-summary.py  (defaults to .claude/tracking/tokens.json in cwd's git root)
+"""
+import sys
+import json
+import os
+from collections import defaultdict
+from datetime import date
+
+def find_tokens_file():
+    cwd = os.getcwd()
+    root = cwd
+    while root != "/":
+        if os.path.isdir(os.path.join(root, ".git")):
+            break
+        root = os.path.dirname(root)
+    path = os.path.join(root, ".claude", "tracking", "tokens.json")
+    if os.path.exists(path):
+        return path
+    sys.exit(f"No tokens.json found at {path}")
+
+tokens_file = sys.argv[1] if len(sys.argv) > 1 else find_tokens_file()
+
+with open(tokens_file) as f:
+    data = json.load(f)
+
+if not data:
+    print("No sessions recorded yet.")
+    sys.exit(0)
+
+# --- Aggregate ---
+by_date = defaultdict(lambda: {"cost": 0, "sessions": 0, "output": 0, "cache_read": 0, "cache_create": 0, "input": 0})
+by_model = defaultdict(lambda: {"cost": 0, "sessions": 0})
+total_cost = 0
+total_sessions = len(data)
+sessions_with_tokens = 0
+
+for e in data:
+    d = e.get("date", "unknown")
+    cost = e.get("estimated_cost_usd", 0)
+    model = e.get("model", "unknown")
+    short_model = model.split("-20")[0] if "-20" in model else model
+
+    by_date[d]["cost"] += cost
+    by_date[d]["sessions"] += 1
+    by_date[d]["output"] += e.get("output_tokens", 0)
+    by_date[d]["cache_read"] += e.get("cache_read_tokens", 0)
+    by_date[d]["cache_create"] += e.get("cache_creation_tokens", 0)
+    by_date[d]["input"] += e.get("input_tokens", 0)
+
+    by_model[short_model]["cost"] += cost
+    by_model[short_model]["sessions"] += 1
+
+    total_cost += cost
+    if e.get("total_tokens", 0) > 0:
+        sessions_with_tokens += 1
+
+total_output = sum(e.get("output_tokens", 0) for e in data)
+total_cache_read = sum(e.get("cache_read_tokens", 0) for e in data)
+total_cache_create = sum(e.get("cache_creation_tokens", 0) for e in data)
+total_input = sum(e.get("input_tokens", 0) for e in data)
+
+# --- Print ---
+W = 60
+print("=" * W)
+print(f"  Cost Summary — {os.path.basename(os.path.dirname(os.path.dirname(tokens_file)))}")
+print("=" * W)
+
+print(f"\nBy date:")
+print(f"  {'Date':<12} {'Sessions':>8} {'Output':>10} {'Cache Read':>12} {'Cost':>10}")
+print(f"  {'-'*12} {'-'*8} {'-'*10} {'-'*12} {'-'*10}")
+for d in sorted(by_date):
+    r = by_date[d]
+    print(f"  {d:<12} {r['sessions']:>8} {r['output']:>10,} {r['cache_read']:>12,} ${r['cost']:>9.2f}")
+
+print(f"\nBy model:")
+print(f"  {'Model':<30} {'Sessions':>8} {'Cost':>10}")
+print(f"  {'-'*30} {'-'*8} {'-'*10}")
+for m in sorted(by_model, key=lambda x: -by_model[x]["cost"]):
+    r = by_model[m]
+    print(f"  {m:<30} {r['sessions']:>8} ${r['cost']:>9.2f}")
+
+print(f"\nTotals:")
+print(f"  Sessions:          {total_sessions:>8}  ({sessions_with_tokens} with token data)")
+print(f"  Input tokens:      {total_input:>12,}")
+print(f"  Cache write:       {total_cache_create:>12,}")
+print(f"  Cache read:        {total_cache_read:>12,}")
+print(f"  Output tokens:     {total_output:>12,}")
+print(f"  Estimated cost:    ${total_cost:>11.2f}")
+
+if total_output > 0:
+    cache_pct = total_cache_read / (total_input + total_cache_create + total_cache_read + total_output) * 100
+    print(f"  Cache read share:  {cache_pct:>10.1f}%  of all tokens")
+
+days = len(by_date)
+if days > 1:
+    print(f"\n  Avg cost/day:      ${total_cost/days:>11.2f}  over {days} days")
+
+print("=" * W)

package/src/generate-charts.py

@@ -0,0 +1,497 @@
+#!/usr/bin/env python3
+"""
+Generates tracking/charts.html from tokens.json + key-prompts/ folder.
+Called by stop-hook.sh after each session update.
+
+Usage: python3 generate-charts.py <tokens.json> <output.html>
+"""
+import sys, json, os, re, glob
+from collections import defaultdict
+
+tokens_file = sys.argv[1]
+output_file = sys.argv[2]
+
+with open(tokens_file) as f:
+    data = json.load(f)
+
+if not data:
+    sys.exit(0)
+
+# --- Aggregate by date ---
+by_date = defaultdict(lambda: {"cost": 0, "sessions": 0, "output": 0,
+                                "cache_read": 0, "cache_create": 0, "input": 0,
+                                "opus_cost": 0, "sonnet_cost": 0})
+by_model = defaultdict(lambda: {"cost": 0, "sessions": 0})
+cumulative = []
+
+running_cost = 0
+for e in sorted(data, key=lambda x: (x.get("date", ""), x.get("session_id", ""))):
+    d = e.get("date", "unknown")
+    cost = e.get("estimated_cost_usd", 0)
+    model = e.get("model", "unknown")
+    short = model.split("-20")[0] if "-20" in model else model
+
+    by_date[d]["cost"] += cost
+    by_date[d]["sessions"] += 1
+    by_date[d]["output"] += e.get("output_tokens", 0)
+    by_date[d]["cache_read"] += e.get("cache_read_tokens", 0)
+    by_date[d]["cache_create"] += e.get("cache_creation_tokens", 0)
+    by_date[d]["input"] += e.get("input_tokens", 0)
+    if "opus" in model:
+        by_date[d]["opus_cost"] += cost
+    else:
+        by_date[d]["sonnet_cost"] += cost
+
+    by_model[short]["cost"] += cost
+    by_model[short]["sessions"] += 1
+
+    running_cost += cost
+    cumulative.append({"date": d, "cumulative_cost": round(running_cost, 4),
+                        "session_id": e.get("session_id", "")[:8]})
+
+dates = sorted(by_date.keys())
+total_cost = sum(e.get("estimated_cost_usd", 0) for e in data)
+total_sessions = len(data)
+sessions_with_data = sum(1 for e in data if e.get("total_tokens", 0) > 0)
+total_output = sum(e.get("output_tokens", 0) for e in data)
+total_cache_read = sum(e.get("cache_read_tokens", 0) for e in data)
+total_all_tokens = sum(e.get("total_tokens", 0) for e in data)
+cache_pct = round(total_cache_read / total_all_tokens * 100, 1) if total_all_tokens > 0 else 0
+
+project_name = data[0].get("project", "Project") if data else "Project"
+
+# --- Count total human messages per date from JSONL transcripts ---
+project_dir = os.path.dirname(os.path.dirname(os.path.dirname(tokens_file)))  # project root
+# Claude Code slugifies paths as: replace every "/" with "-" (keeping leading slash → leading dash)
+transcripts_dir = os.path.expanduser(
+    "~/.claude/projects/" + project_dir.replace("/", "-")
+)
+human_by_date = defaultdict(int)
+
+if os.path.isdir(transcripts_dir):
+    for jf in glob.glob(os.path.join(transcripts_dir, "*.jsonl")):
+        # Use session date from tokens.json if available, else file mtime
+        sid = os.path.splitext(os.path.basename(jf))[0]
+        session_date = None
+        for e in data:
+            if e.get("session_id") == sid:
+                session_date = e.get("date")
+                break
+        if not session_date:
+            import datetime
+            session_date = datetime.datetime.fromtimestamp(
+                os.path.getmtime(jf)).strftime("%Y-%m-%d")
+
+        try:
+            with open(jf) as f:
+                for line in f:
+                    try:
+                        obj = json.loads(line)
+                        # Human messages have type="user" and userType="human" at the top level
+                        if obj.get("type") != "user":
+                            continue
+                        if obj.get("userType") not in ("human", "external", None):
+                            continue
+                        if obj.get("isSidechain"):
+                            continue
+                        content = obj.get("message", {}).get("content", "")
+                        if isinstance(content, list):
+                            # Skip pure tool-result messages
+                            has_real_text = any(
+                                isinstance(c, dict) and c.get("type") == "text"
+                                and not str(c.get("text", "")).strip().startswith("<")
+                                for c in content
+                            )
+                            if has_real_text:
+                                human_by_date[session_date] += 1
+                        elif isinstance(content, str):
+                            text = content.strip()
+                            # Skip slash commands and empty
+                            if text and not text.startswith("<") and not text.startswith("/"):
+                                human_by_date[session_date] += 1
+                    except:
+                        pass
+        except:
+            pass
+
+total_human_msgs = sum(human_by_date.values())
+
+# --- Aggregate prompt data from key-prompts/ folder ---
+prompts_dir = os.path.join(os.path.dirname(tokens_file), "key-prompts")
+prompt_files = sorted(glob.glob(os.path.join(prompts_dir, "????-??-??.md")))
+
+prompt_by_date = {}   # date -> {total, by_category}
+all_categories = set()
+
+for f in prompt_files:
+    date = os.path.splitext(os.path.basename(f))[0]
+    content = open(f).read()
+    cats = re.findall(r'^\*\*Category\*\*: (\S+)', content, re.MULTILINE)
+    by_cat = defaultdict(int)
+    for c in cats:
+        by_cat[c] += 1
+        all_categories.add(c)
+    prompt_by_date[date] = {"total": len(cats), "by_category": dict(by_cat)}
+
+all_categories = sorted(all_categories)
+prompt_dates = sorted(prompt_by_date.keys())
+total_prompts = sum(v["total"] for v in prompt_by_date.values())
+
+# Build JS data structures
+dates_js = json.dumps(dates)
+cost_by_date_js = json.dumps([round(by_date[d]["cost"], 4) for d in dates])
+sessions_by_date_js = json.dumps([by_date[d]["sessions"] for d in dates])
+output_by_date_js = json.dumps([by_date[d]["output"] for d in dates])
+cache_read_by_date_js = json.dumps([by_date[d]["cache_read"] for d in dates])
+opus_by_date_js = json.dumps([round(by_date[d]["opus_cost"], 4) for d in dates])
+sonnet_by_date_js = json.dumps([round(by_date[d]["sonnet_cost"], 4) for d in dates])
+
+cumul_labels_js = json.dumps([f"{c['date']} #{i+1}" for i, c in enumerate(cumulative)])
+cumul_values_js = json.dumps([c["cumulative_cost"] for c in cumulative])
+
+model_labels_js = json.dumps(list(by_model.keys()))
+model_costs_js = json.dumps([round(by_model[m]["cost"], 4) for m in by_model])
+model_sessions_js = json.dumps([by_model[m]["sessions"] for m in by_model])
+
+# All dates union for prompts vs total chart
+all_prompt_dates = sorted(set(list(prompt_by_date.keys()) + list(human_by_date.keys())))
+all_prompt_dates_js = json.dumps(all_prompt_dates)
+total_msgs_by_date_js = json.dumps([human_by_date.get(d, 0) for d in all_prompt_dates])
+key_prompts_by_date_js = json.dumps([prompt_by_date.get(d, {}).get("total", 0) for d in all_prompt_dates])
+
+# Efficiency ratio per date (key / total * 100), None if no messages
+efficiency_by_date = []
+for d in all_prompt_dates:
+    total = human_by_date.get(d, 0)
+    key = prompt_by_date.get(d, {}).get("total", 0)
+    efficiency_by_date.append(round(key / total * 100, 1) if total > 0 else None)
+efficiency_by_date_js = json.dumps(efficiency_by_date)
+
+overall_efficiency = round(total_prompts / total_human_msgs * 100, 1) if total_human_msgs > 0 else 0
+
+# Prompt chart data
+prompt_dates_js = json.dumps(prompt_dates)
+prompt_totals_js = json.dumps([prompt_by_date[d]["total"] for d in prompt_dates])
+
+CAT_COLORS = {
+    "bug-resolution": "#f87171",
+    "architecture":   "#6366f1",
+    "feature":        "#34d399",
+    "breakthrough":   "#f59e0b",
+}
+DEFAULT_COLOR = "#94a3b8"
+
+cat_datasets = []
+for cat in all_categories:
+    cat_datasets.append({
+        "label": cat,
+        "data": [prompt_by_date[d]["by_category"].get(cat, 0) for d in prompt_dates],
+        "backgroundColor": CAT_COLORS.get(cat, DEFAULT_COLOR),
+        "borderRadius": 2,
+    })
+cat_datasets_js = json.dumps(cat_datasets)
+
+# Category totals for doughnut
+cat_totals = {c: sum(prompt_by_date[d]["by_category"].get(c, 0) for d in prompt_dates)
+              for c in all_categories}
+donut_labels_js = json.dumps(list(cat_totals.keys()))
+donut_values_js = json.dumps(list(cat_totals.values()))
+donut_colors_js = json.dumps([CAT_COLORS.get(c, DEFAULT_COLOR) for c in cat_totals])
+
+html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Claude Code — {project_name} tracking</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<style>
+  * {{ box-sizing: border-box; margin: 0; padding: 0; }}
+  body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+          background: #0f1117; color: #e2e8f0; padding: 24px; }}
+  h1 {{ font-size: 1.25rem; font-weight: 600; margin-bottom: 4px; color: #f8fafc; }}
+  .subtitle {{ font-size: 0.8rem; color: #64748b; margin-bottom: 24px; }}
+  .stats {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+             gap: 12px; margin-bottom: 28px; }}
+  .stat {{ background: #1e2330; border: 1px solid #2d3748; border-radius: 10px;
+           padding: 14px 16px; }}
+  .stat-label {{ font-size: 0.7rem; color: #64748b; text-transform: uppercase;
+                  letter-spacing: 0.05em; margin-bottom: 4px; }}
+  .stat-value {{ font-size: 1.4rem; font-weight: 700; color: #f8fafc; }}
+  .stat-sub {{ font-size: 0.7rem; color: #94a3b8; margin-top: 2px; }}
+  .grid {{ display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }}
+  .card {{ background: #1e2330; border: 1px solid #2d3748; border-radius: 10px;
+           padding: 16px; }}
+  .card.wide {{ grid-column: 1 / -1; }}
+  .card h2 {{ font-size: 0.8rem; font-weight: 600; color: #94a3b8;
+               text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 14px; }}
+  canvas {{ max-height: 220px; }}
+  .wide canvas {{ max-height: 180px; }}
+  .notice {{ font-size: 0.78rem; color: #94a3b8; background: #1e2330;
+             border: 1px solid #3b4a6b; border-left: 3px solid #6366f1;
+             border-radius: 6px; padding: 10px 14px; margin-bottom: 20px; }}
+  .notice strong {{ color: #e2e8f0; }}
+  @media (max-width: 700px) {{ .grid {{ grid-template-columns: 1fr; }} }}
+</style>
+</head>
+<body>
+<h1>Claude Code — {project_name}</h1>
+<p class="subtitle">Updated after every session &mdash; open in browser to view</p>
+<p class="notice">&#9432; Cost figures are <strong>API list-price equivalents</strong> (what pay-as-you-go API customers would be charged). If you are on a Max subscription, these are <em>not</em> amounts billed to you.</p>
+
+<div class="stats">
+  <div class="stat">
+    <div class="stat-label">API list-price equivalent</div>
+    <div class="stat-value">${total_cost:.2f}</div>
+    <div class="stat-sub">across {len(dates)} day{"s" if len(dates) != 1 else ""} (not billed)</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Sessions</div>
+    <div class="stat-value">{total_sessions}</div>
+    <div class="stat-sub">{sessions_with_data} with token data</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Output tokens</div>
+    <div class="stat-value">{total_output:,}</div>
+    <div class="stat-sub">&nbsp;</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Cache read share</div>
+    <div class="stat-value">{cache_pct}%</div>
+    <div class="stat-sub">of all tokens</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Key prompts captured</div>
+    <div class="stat-value">{total_prompts}</div>
+    <div class="stat-sub">of {total_human_msgs:,} total prompts</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Prompt efficiency</div>
+    <div class="stat-value">{overall_efficiency}%</div>
+    <div class="stat-sub">key / total (higher = better)</div>
+  </div>
+</div>
+
+<div class="grid">
+
+  <div class="card wide">
+    <h2>Cumulative cost over sessions</h2>
+    <canvas id="cumul"></canvas>
+  </div>
+
+  <div class="card">
+    <h2>Cost per day</h2>
+    <canvas id="costDay"></canvas>
+  </div>
+
+  <div class="card">
+    <h2>Sessions per day</h2>
+    <canvas id="sessDay"></canvas>
+  </div>
+
+  <div class="card">
+    <h2>Cost by model (stacked per day)</h2>
+    <canvas id="modelStack"></canvas>
+  </div>
+
+  <div class="card">
+    <h2>Output tokens per day</h2>
+    <canvas id="outputDay"></canvas>
+  </div>
+
+</div>
+
+<h2 style="font-size:0.85rem;font-weight:600;color:#94a3b8;text-transform:uppercase;
+           letter-spacing:0.05em;margin:32px 0 16px">Key Prompts</h2>
+
+<div class="grid">
+
+  <div class="card wide">
+    <h2>Total prompts vs key prompts per day</h2>
+    <canvas id="promptsVsTotal"></canvas>
+  </div>
+
+  <div class="card">
+    <h2>Prompt efficiency per day (%)</h2>
+    <canvas id="promptEfficiency"></canvas>
+  </div>
+
+  <div class="card">
+    <h2>Category breakdown (all time)</h2>
+    <canvas id="promptDonut"></canvas>
+  </div>
+
+  <div class="card wide">
+    <h2>Category breakdown per day (stacked)</h2>
+    <canvas id="promptStack"></canvas>
+  </div>
+
+</div>
+
+<script>
+const DATES = {dates_js};
+const COST_BY_DATE = {cost_by_date_js};
+const SESSIONS_BY_DATE = {sessions_by_date_js};
+const OUTPUT_BY_DATE = {output_by_date_js};
+const OPUS_BY_DATE = {opus_by_date_js};
+const SONNET_BY_DATE = {sonnet_by_date_js};
+const CUMUL_LABELS = {cumul_labels_js};
+const CUMUL_VALUES = {cumul_values_js};
+const MODEL_LABELS = {model_labels_js};
+const MODEL_COSTS = {model_costs_js};
+const MODEL_SESSIONS = {model_sessions_js};
+const PROMPT_DATES = {prompt_dates_js};
+const PROMPT_TOTALS = {prompt_totals_js};
+const PROMPT_CAT_DATASETS = {cat_datasets_js};
+const DONUT_LABELS = {donut_labels_js};
+const DONUT_VALUES = {donut_values_js};
+const DONUT_COLORS = {donut_colors_js};
+const ALL_PROMPT_DATES = {all_prompt_dates_js};
+const TOTAL_MSGS_BY_DATE = {total_msgs_by_date_js};
+const KEY_PROMPTS_BY_DATE = {key_prompts_by_date_js};
+const EFFICIENCY_BY_DATE = {efficiency_by_date_js};
+
+const GRID = '#2d3748';
+const TEXT = '#94a3b8';
+const baseOpts = {{
+  responsive: true,
+  maintainAspectRatio: true,
+  plugins: {{ legend: {{ labels: {{ color: TEXT, boxWidth: 12, font: {{ size: 11 }} }} }} }},
+  scales: {{
+    x: {{ ticks: {{ color: TEXT, font: {{ size: 10 }} }}, grid: {{ color: GRID }} }},
+    y: {{ ticks: {{ color: TEXT, font: {{ size: 10 }} }}, grid: {{ color: GRID }} }}
+  }}
+}};
+
+// Cumulative cost line
+new Chart(document.getElementById('cumul'), {{
+  type: 'line',
+  data: {{
+    labels: CUMUL_LABELS,
+    datasets: [{{ label: 'Cumulative cost ($)', data: CUMUL_VALUES,
+      borderColor: '#6366f1', backgroundColor: 'rgba(99,102,241,0.15)',
+      fill: true, tension: 0.3, pointRadius: 2 }}]
+  }},
+  options: {{ ...baseOpts, plugins: {{ ...baseOpts.plugins,
+    tooltip: {{ callbacks: {{ label: ctx => ' $' + ctx.parsed.y.toFixed(2) }} }} }} }}
+}});
+
+// Cost per day bar
+new Chart(document.getElementById('costDay'), {{
+  type: 'bar',
+  data: {{
+    labels: DATES,
+    datasets: [{{ label: 'Cost ($)', data: COST_BY_DATE,
+      backgroundColor: '#6366f1', borderRadius: 4 }}]
+  }},
+  options: {{ ...baseOpts, plugins: {{ ...baseOpts.plugins,
+    tooltip: {{ callbacks: {{ label: ctx => ' $' + ctx.parsed.y.toFixed(2) }} }} }} }}
+}});
+
+// Sessions per day
+new Chart(document.getElementById('sessDay'), {{
+  type: 'bar',
+  data: {{
+    labels: DATES,
+    datasets: [{{ label: 'Sessions', data: SESSIONS_BY_DATE,
+      backgroundColor: '#22d3ee', borderRadius: 4 }}]
+  }},
+  options: baseOpts
+}});
+
+// Model stacked per day
+new Chart(document.getElementById('modelStack'), {{
+  type: 'bar',
+  data: {{
+    labels: DATES,
+    datasets: [
+      {{ label: 'Opus', data: OPUS_BY_DATE, backgroundColor: '#f59e0b', borderRadius: 2 }},
+      {{ label: 'Sonnet', data: SONNET_BY_DATE, backgroundColor: '#6366f1', borderRadius: 2 }}
+    ]
+  }},
+  options: {{ ...baseOpts, scales: {{ ...baseOpts.scales, x: {{ ...baseOpts.scales.x, stacked: true }},
+    y: {{ ...baseOpts.scales.y, stacked: true }} }},
+    plugins: {{ ...baseOpts.plugins,
+      tooltip: {{ callbacks: {{ label: ctx => ' $' + ctx.parsed.y.toFixed(2) }} }} }} }}
+}});
+
+// Output tokens per day
+new Chart(document.getElementById('outputDay'), {{
+  type: 'bar',
+  data: {{
+    labels: DATES,
+    datasets: [{{ label: 'Output tokens', data: OUTPUT_BY_DATE,
+      backgroundColor: '#34d399', borderRadius: 4 }}]
+  }},
+  options: baseOpts
+}});
+
+// Total vs key prompts per day
+new Chart(document.getElementById('promptsVsTotal'), {{
+  type: 'bar',
+  data: {{
+    labels: ALL_PROMPT_DATES,
+    datasets: [
+      {{ label: 'Total prompts', data: TOTAL_MSGS_BY_DATE,
+         backgroundColor: 'rgba(148,163,184,0.35)', borderRadius: 4 }},
+      {{ label: 'Key prompts', data: KEY_PROMPTS_BY_DATE,
+         backgroundColor: '#a78bfa', borderRadius: 4 }}
+    ]
+  }},
+  options: baseOpts
+}});
+
+// Efficiency % per day
+new Chart(document.getElementById('promptEfficiency'), {{
+  type: 'line',
+  data: {{
+    labels: ALL_PROMPT_DATES,
+    datasets: [{{ label: 'Efficiency (%)', data: EFFICIENCY_BY_DATE,
+      borderColor: '#f59e0b', backgroundColor: 'rgba(245,158,11,0.15)',
+      fill: true, tension: 0.3, pointRadius: 3, spanGaps: true }}]
+  }},
+  options: {{ ...baseOpts, plugins: {{ ...baseOpts.plugins,
+    tooltip: {{ callbacks: {{ label: ctx => ' ' + ctx.parsed.y + '%' }} }} }},
+    scales: {{ ...baseOpts.scales,
+      y: {{ ...baseOpts.scales.y, min: 0, max: 100,
+            ticks: {{ ...baseOpts.scales.y.ticks, callback: v => v + '%' }} }} }} }}
+}});
+
+// Category doughnut
+new Chart(document.getElementById('promptDonut'), {{
+  type: 'doughnut',
+  data: {{
+    labels: DONUT_LABELS,
+    datasets: [{{ data: DONUT_VALUES, backgroundColor: DONUT_COLORS,
+      borderWidth: 2, borderColor: '#1e2330' }}]
+  }},
+  options: {{
+    responsive: true,
+    maintainAspectRatio: true,
+    plugins: {{
+      legend: {{ position: 'right', labels: {{ color: TEXT, boxWidth: 12, font: {{ size: 11 }} }} }}
+    }}
+  }}
+}});
+
+// Category stacked per day
+new Chart(document.getElementById('promptStack'), {{
+  type: 'bar',
+  data: {{
+    labels: PROMPT_DATES,
+    datasets: PROMPT_CAT_DATASETS
+  }},
+  options: {{ ...baseOpts,
+    scales: {{
+      x: {{ ...baseOpts.scales.x, stacked: true }},
+      y: {{ ...baseOpts.scales.y, stacked: true }}
+    }}
+  }}
+}});
+</script>
+</body>
+</html>
+"""
+
+with open(output_file, "w") as f:
+    f.write(html)

package/src/init-templates.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+TRACKING_DIR="$1"
+mkdir -p "$TRACKING_DIR"
+mkdir -p "$TRACKING_DIR/key-prompts"
+
+cat > "$TRACKING_DIR/tokens.json" <<'EOF'
+[]
+EOF
+
+cat > "$TRACKING_DIR/key-prompts.md" <<'EOF'
+# Prompt Journal
+
+High-signal prompts organized by day.
+
+| File | Entries | Highlights |
+|------|---------|------------|
+
+**Total**: 0 entries
+
+---
+
+New entries go in `key-prompts/YYYY-MM-DD.md` for today's date. Create the file if it doesn't exist — use the same header format as existing files.
+EOF
+
+cat > "$TRACKING_DIR/sessions.md" <<'EOF'
+# Session Log
+
+---
+EOF
+
+cat > "$TRACKING_DIR/cost-analysis.md" <<'EOF'
+# AI Cost Analysis
+
+## Development Costs
+
+| Date | Session Summary | Input | Cache Write | Cache Read | Output | Cost (USD) |
+|------|----------------|-------|-------------|------------|--------|------------|
+| | **Total** | | | | | **$0.00** |
+
+*Token counts include prompt caching. Pricing: Sonnet 4.5 -- input $3/M, cache write $3.75/M, cache read $0.30/M, output $15/M. Opus 4.6 -- input $15/M, cache write $18.75/M, cache read $1.50/M, output $75/M.*
+
+---
+
+## Anthropic Pricing Reference
+
+| Model | Input (per M) | Output (per M) | Cache Write | Cache Read |
+|-------|--------------|----------------|-------------|------------|
+| Claude Opus 4.6 | $15.00 | $75.00 | $18.75 | $1.50 |
+| Claude Sonnet 4.5 | $3.00 | $15.00 | $3.75 | $0.30 |
+| Claude Haiku 4.5 | $0.80 | $4.00 | $1.00 | $0.08 |
+EOF
+
+cat > "$TRACKING_DIR/ai-dev-log.md" <<'EOF'
+# AI Development Log
+
+**Period**: Started $(date +%Y-%m-%d)
+**Primary AI Tool**: Claude Code
+
+---
+
+## Tools & Workflow
+
+*Document your AI workflow here.*
+
+---
+
+## Effective Prompts
+
+See `key-prompts.md` for the full journal with context and analysis.
+
+---
+
+## Code Analysis
+
+*Document AI contribution estimates here.*
+
+---
+
+## Key Learnings
+
+*Document key learnings as you go.*
+EOF

package/src/stop-hook.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT="$(cat)"
+
+# Prevent loops
+STOP_ACTIVE="$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('stop_hook_active', False))" 2>/dev/null || echo "False")"
+if [[ "$STOP_ACTIVE" == "True" ]]; then exit 0; fi
+
+# Extract fields
+CWD="$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('cwd',''))" 2>/dev/null || true)"
+TRANSCRIPT="$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('transcript_path',''))" 2>/dev/null || true)"
+SESSION_ID="$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id',''))" 2>/dev/null || true)"
+
+if [[ -z "$CWD" || -z "$TRANSCRIPT" || ! -f "$TRANSCRIPT" ]]; then exit 0; fi
+
+# Find project root (walk up to .git)
+PROJECT_ROOT="$CWD"
+while [[ "$PROJECT_ROOT" != "/" ]]; do
+  [[ -d "$PROJECT_ROOT/.git" ]] && break
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+if [[ "$PROJECT_ROOT" == "/" ]]; then exit 0; fi
+
+TRACKING_DIR="$PROJECT_ROOT/.claude/tracking"
+
+# Auto-initialize if missing
+if [[ ! -d "$TRACKING_DIR" ]]; then
+  bash "$SCRIPT_DIR/init-templates.sh" "$TRACKING_DIR"
+fi
+
+# Parse token usage from JSONL and update tokens.json
+python3 - "$TRANSCRIPT" "$TRACKING_DIR/tokens.json" "$SESSION_ID" "$(basename "$PROJECT_ROOT")" <<'PYEOF'
+import sys, json, os
+from datetime import date
+
+transcript_path = sys.argv[1]
+tokens_file = sys.argv[2]
+session_id = sys.argv[3]
+project_name = sys.argv[4]
+today = date.today().isoformat()
+
+# Sum all token usage from assistant messages in this session
+inp = out = cache_create = cache_read = 0
+model = "unknown"
+with open(transcript_path) as f:
+    for line in f:
+        try:
+            obj = json.loads(line)
+            msg = obj.get('message', {})
+            if isinstance(msg, dict) and msg.get('role') == 'assistant':
+                usage = msg.get('usage', {})
+                if usage:
+                    inp += usage.get('input_tokens', 0)
+                    out += usage.get('output_tokens', 0)
+                    cache_create += usage.get('cache_creation_input_tokens', 0)
+                    cache_read += usage.get('cache_read_input_tokens', 0)
+                m = msg.get('model', '')
+                if m:
+                    model = m
+        except:
+            pass
+
+total = inp + cache_create + cache_read + out
+if 'opus' in model:
+    cost = inp * 15 / 1e6 + cache_create * 18.75 / 1e6 + cache_read * 1.50 / 1e6 + out * 75 / 1e6
+else:
+    cost = inp * 3 / 1e6 + cache_create * 3.75 / 1e6 + cache_read * 0.30 / 1e6 + out * 15 / 1e6
+
+# Load or create tokens.json
+data = []
+if os.path.exists(tokens_file):
+    try:
+        with open(tokens_file) as f:
+            data = json.load(f)
+    except:
+        data = []
+
+# Build entry
+entry = {
+    "date": today,
+    "project": project_name,
+    "session_id": session_id,
+    "input_tokens": inp,
+    "cache_creation_tokens": cache_create,
+    "cache_read_tokens": cache_read,
+    "output_tokens": out,
+    "total_tokens": total,
+    "estimated_cost_usd": round(cost, 4),
+    "model": model
+}
+
+# Update existing or append new
+found = False
+for i, e in enumerate(data):
+    if e.get('session_id') == session_id:
+        data[i] = entry
+        found = True
+        break
+if not found:
+    data.append(entry)
+
+with open(tokens_file, 'w') as f:
+    json.dump(data, f, indent=2)
+    f.write('\n')
+PYEOF
+
+# Regenerate charts
+python3 "$SCRIPT_DIR/generate-charts.py" "$TRACKING_DIR/tokens.json" "$TRACKING_DIR/charts.html" 2>/dev/null || true
+
+# Regenerate key-prompts index
+python3 "$SCRIPT_DIR/update-prompts-index.py" "$TRACKING_DIR" 2>/dev/null || true

package/src/update-prompts-index.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""
+Regenerates <tracking_dir>/key-prompts.md index from files in key-prompts/ folder.
+Called by stop-hook.sh after each session.
+
+Usage: python3 update-prompts-index.py <tracking_dir>
+"""
+import sys
+import os
+import re
+import glob
+
+tracking_dir = sys.argv[1]
+prompts_dir = os.path.join(tracking_dir, "key-prompts")
+index_file = os.path.join(tracking_dir, "key-prompts.md")
+
+if not os.path.isdir(prompts_dir):
+    sys.exit(0)
+
+files = sorted(glob.glob(os.path.join(prompts_dir, "????-??-??.md")))
+if not files:
+    sys.exit(0)
+
+rows = []
+total_entries = 0
+
+for f in files:
+    date = os.path.splitext(os.path.basename(f))[0]
+    with open(f) as fh:
+        content = fh.read()
+
+    # Count entries (## headings that are not the title line)
+    entries = len(re.findall(r'^## (?!Key Prompts)', content, re.MULTILINE))
+
+    # Extract first 3 entry titles for highlights
+    titles = re.findall(r'^## (.+)', content, re.MULTILINE)
+    # Skip the file title (first line if it matches "Key Prompts — ...")
+    titles = [t for t in titles if not t.startswith("Key Prompts")]
+    highlights = ", ".join(titles[:3])
+    if len(titles) > 3:
+        highlights += "..."
+
+    rows.append((date, entries, highlights))
+    total_entries += entries
+
+lines = ["# Prompt Journal\n",
+         "\nHigh-signal prompts organized by day.\n",
+         "\n| File | Entries | Highlights |\n",
+         "|------|---------|------------|\n"]
+
+for date, entries, highlights in rows:
+    lines.append(f"| [{date}](key-prompts/{date}.md) | {entries} | {highlights} |\n")
+
+lines.append(f"\n**Total**: {total_entries} entries across {len(rows)} day{'s' if len(rows) != 1 else ''}\n")
+lines.append("\n---\n")
+lines.append("\nNew entries go in `key-prompts/YYYY-MM-DD.md` for today's date. "
+             "Create the file if it doesn't exist — use the same header format as existing files.\n")
+
+with open(index_file, "w") as f:
+    f.writelines(lines)

package/uninstall.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_DIR="$HOME/.claude/tracking"
+SETTINGS="$HOME/.claude/settings.json"
+HOOK_CMD="$INSTALL_DIR/stop-hook.sh"
+
+echo "Uninstalling claude-code-tracker..."
+
+# Remove scripts
+if [[ -d "$INSTALL_DIR" ]]; then
+    rm -f "$INSTALL_DIR/"*.sh "$INSTALL_DIR/"*.py
+    echo "Scripts removed from $INSTALL_DIR"
+else
+    echo "Nothing to remove at $INSTALL_DIR"
+fi
+
+# Remove hook entry from settings.json
+if [[ -f "$SETTINGS" ]]; then
+    python3 - "$SETTINGS" "$HOOK_CMD" <<'PYEOF'
+import sys, json, os
+
+settings_file = sys.argv[1]
+hook_cmd = sys.argv[2]
+
+try:
+    with open(settings_file) as f:
+        data = json.load(f)
+except Exception:
+    sys.exit(0)
+
+hooks = data.get("hooks", {})
+stop_hooks = hooks.get("Stop", [])
+
+new_stop_hooks = []
+removed = False
+for group in stop_hooks:
+    new_group_hooks = [h for h in group.get("hooks", []) if h.get("command") != hook_cmd]
+    if len(new_group_hooks) < len(group.get("hooks", [])):
+        removed = True
+    if new_group_hooks:
+        new_stop_hooks.append({"hooks": new_group_hooks})
+    elif not removed:
+        new_stop_hooks.append(group)
+
+if removed:
+    hooks["Stop"] = new_stop_hooks
+    if not hooks["Stop"]:
+        del hooks["Stop"]
+    if not hooks:
+        del data["hooks"]
+    with open(settings_file, 'w') as f:
+        json.dump(data, f, indent=2)
+        f.write('\n')
+    print("Hook removed from", settings_file)
+else:
+    print("Hook not found in", settings_file)
+PYEOF
+fi
+
+echo "claude-code-tracker uninstalled."