claude-code-tracker 1.2.3 → 1.4.0-beta.3

package/README.md

@@ -13,6 +13,8 @@ After every session, it parses the transcript, updates a `tokens.json` ledger, r
 - **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
+- **Per-agent cost breakdown**: SubagentStop hook captures each spawned agent's token usage
+  separately — see which agent types (architect, quick-fixer, Explore, etc.) drive the most cost
 
 All data lives in `<project>/.claude/tracking/` alongside your code.
 
@@ -26,7 +28,7 @@ All data lives in `<project>/.claude/tracking/` alongside your code.
 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`.
+The `postinstall` script copies the tracking scripts to `~/.claude/tracking/` and registers the Stop hook in `~/.claude/settings.json`. On Windows, the Node.js wrappers (`install.js`, `stop-hook.js`) delegate to bash automatically via Git Bash or WSL.
 
 ### Option 2 — Homebrew
 
@@ -68,7 +70,8 @@ On first use in a project, the Stop hook auto-initializes `<project>/.claude/tra
 
 ```
 .claude/tracking/
-  tokens.json          # session data (auto-updated)
+  tokens.json          # main session data (auto-updated)
+  agents.json          # per-agent invocation data (auto-updated)
   charts.html          # Chart.js dashboard (auto-updated)
   key-prompts.md       # index of logged prompts
   key-prompts/         # one .md per day
@@ -93,6 +96,22 @@ The dashboard shows cumulative cost, cost per day, sessions, output tokens, mode
 
 ---
 
+## Multi-agent tracking
+
+When using Claude Code's Task tool to spawn background agents, each agent's cost is tracked
+separately. The `SubagentStop` hook fires when each agent finishes and appends an entry to
+`agents.json` with:
+- `agent_type` — the subagent type (e.g. `architect`, `quick-fixer`, `Explore`, `Bash`)
+- token counts summed across all internal turns
+- `estimated_cost_usd` using the same list-price formula as main sessions
+
+The dashboard shows an "Agents" section with cost and invocation count by agent type, letting
+you identify which agent types are expensive relative to their output.
+
+No configuration needed — the SubagentStop hook is registered automatically on install.
+
+---
+
 ## Cost CLI
 
 ```bash
@@ -167,6 +186,23 @@ The uninstaller removes the scripts from `~/.claude/tracking/` and removes the S
 
 ---
 
+## 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.

package/bin/claude-tracker-cost.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+'use strict';
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const scriptDir = path.dirname(path.dirname(path.resolve(__filename)));
+const bashScript = path.join(scriptDir, 'bin', 'claude-tracker-cost.sh');
+
+if (process.platform === 'win32') {
+  const result = spawnSync('bash', [bashScript], {
+    stdio: 'inherit',
+    shell: false,
+  });
+  process.exit(result.status || 0);
+} else {
+  const result = spawnSync('bash', [bashScript], {
+    stdio: 'inherit',
+  });
+  process.exit(result.status || 0);
+}

package/bin/claude-tracker-setup

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PREFIX="$(brew --prefix claude-code-tracker 2>/dev/null)" || {
+  echo "Error: claude-code-tracker not found via Homebrew." >&2
+  echo "If you installed via npm or git clone, run install.sh directly." >&2
+  exit 1
+}
+
+exec "$PREFIX/libexec/install.sh"

package/install.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const scriptDir = path.dirname(path.resolve(__filename));
+const bashScript = path.join(scriptDir, 'install.sh');
+
+if (process.platform === 'win32') {
+  const result = spawnSync('bash', [bashScript, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    shell: false,
+  });
+  process.exit(result.status || 0);
+} else {
+  const result = spawnSync('bash', [bashScript, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+  });
+  process.exit(result.status || 0);
+}

package/install.sh

@@ -36,12 +36,25 @@ else
   echo "Scripts installed to $INSTALL_DIR"
 fi
 
+SUBAGENT_HOOK_CMD="${HOOK_CMD/stop-hook.sh/subagent-stop-hook.sh}"
+
+# Install skills to ~/.claude/skills/
+if [[ -d "$SCRIPT_DIR/skills" ]]; then
+  for skill_dir in "$SCRIPT_DIR/skills"/*/; do
+    skill_name="$(basename "$skill_dir")"
+    mkdir -p "$HOME/.claude/skills/$skill_name"
+    cp "$skill_dir/SKILL.md" "$HOME/.claude/skills/$skill_name/SKILL.md"
+    echo "Skill installed: $skill_name"
+  done
+fi
+
 # Patch settings.json — add Stop hook if not already present
-python3 - "$SETTINGS" "$HOOK_CMD" <<'PYEOF'
+python3 - "$SETTINGS" "$HOOK_CMD" "$SUBAGENT_HOOK_CMD" <<'PYEOF'
 import sys, json, os
 
 settings_file = sys.argv[1]
 hook_cmd = sys.argv[2]
+subagent_hook_cmd = sys.argv[3]
 
 data = {}
 if os.path.exists(settings_file):
@@ -71,12 +84,23 @@ session_hooks[:] = [
 ]
 session_hooks.append({"hooks": [{"type": "command", "command": backfill_cmd, "timeout": 60, "async": True}]})
 
+# SubagentStop hook
+subagent_entry = {"type": "command", "command": subagent_hook_cmd, "timeout": 30, "async": True}
+subagent_hooks = hooks.setdefault("SubagentStop", [])
+subagent_hooks[:] = [
+    g for g in subagent_hooks
+    if not any("subagent-stop-hook.sh" in h.get("command", "") for h in g.get("hooks", []))
+]
+subagent_hooks.append({"hooks": [subagent_entry]})
+
 # permissions.allow — clean old entries and add current
 allow_entry = f"Bash({hook_cmd}*)"
+subagent_allow = f"Bash({subagent_hook_cmd}*)"
 perms = data.setdefault("permissions", {})
 allow_list = perms.setdefault("allow", [])
-allow_list[:] = [e for e in allow_list if "stop-hook.sh" not in e]
+allow_list[:] = [e for e in allow_list if "stop-hook.sh" not in e and "subagent-stop-hook.sh" not in e]
 allow_list.append(allow_entry)
+allow_list.append(subagent_allow)
 
 os.makedirs(os.path.dirname(os.path.abspath(settings_file)), exist_ok=True)
 with open(settings_file, 'w') as f:
@@ -111,3 +135,13 @@ if [[ "$SCRIPT_DIR" != */Cellar/* ]]; then
 fi
 
 echo "claude-code-tracker installed. Restart Claude Code to activate."
+
+# Warn if .claude/ is not covered by .gitignore
+if [[ -f ".gitignore" ]]; then
+  if ! grep -q '\.claude/' .gitignore && ! grep -q '^\.claude$' .gitignore; then
+    echo ""
+    echo "WARNING: .claude/ does not appear to be in your .gitignore."
+    echo "Tracking data (tokens, agent costs, session history) will be committed to git."
+    echo "Add '.claude/' or '.claude/tracking/' to .gitignore to prevent this."
+  fi
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-tracker",
-  "version": "1.2.3",
+  "version": "1.4.0-beta.3",
   "description": "Automatic token, cost, and prompt tracking for Claude Code sessions",
   "keywords": [
     "claude",
@@ -16,18 +16,22 @@
     "url": "git+https://github.com/kelsi-andrewss/claude-code-tracker.git"
   },
   "scripts": {
-    "postinstall": "bash ./install.sh"
+    "postinstall": "node ./install.js"
   },
   "bin": {
-    "claude-tracker-cost": "src/cost-summary.py"
+    "claude-tracker-cost": "bin/claude-tracker-cost.js"
   },
   "engines": {
     "node": ">=14"
   },
   "files": [
     "src/",
+    "bin/",
+    "skills/",
     "install.sh",
+    "install.js",
     "uninstall.sh",
+    "uninstall.js",
     "README.md"
   ]
 }

package/skills/view-tracking/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: view-tracking
+description: Open the charts dashboard and today's key-prompts file for the current project. Use when the user says "open charts", "view tracking", "show dashboard", or "/view-tracking".
+---
+
+Open the tracking dashboard for the current project.
+
+Steps:
+
+1. Set the tracking directory: `$CLAUDE_PROJECT_DIR/.claude/tracking/`
+
+2. Open the charts dashboard:
+   ```bash
+   if [[ "$OSTYPE" == darwin* ]]; then
+     open "$CLAUDE_PROJECT_DIR/.claude/tracking/charts.html"
+   elif [[ "$OSTYPE" == msys* || "$OSTYPE" == cygwin* || -n "${WINDIR:-}" ]]; then
+     start "" "$CLAUDE_PROJECT_DIR/.claude/tracking/charts.html"
+   else
+     xdg-open "$CLAUDE_PROJECT_DIR/.claude/tracking/charts.html" 2>/dev/null || echo "Could not open charts.html automatically. Path: $CLAUDE_PROJECT_DIR/.claude/tracking/charts.html"
+   fi
+   ```
+   If the file doesn't exist, report: "No charts.html found at $CLAUDE_PROJECT_DIR/.claude/tracking/charts.html"
+
+3. Find and open today's key-prompts file. Today's date is available from the system. The file path is:
+   `$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md` (using today's date)
+
+   - If it exists:
+     ```bash
+     if [[ "$OSTYPE" == darwin* ]]; then
+       open "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md"
+     elif [[ "$OSTYPE" == msys* || "$OSTYPE" == cygwin* || -n "${WINDIR:-}" ]]; then
+       start "" "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md"
+     else
+       xdg-open "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md" 2>/dev/null || echo "Could not open key-prompts file automatically. Path: $CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md"
+     fi
+     ```
+   - If it doesn't exist: report "No key-prompts file for today yet." then list the most recent file in that directory:
+     ```bash
+     ls -t "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/"*.md 2>/dev/null | head -1
+     ```
+     If a recent file exists, offer: "Most recent: <filename>" and ask if the user wants to open it. If they say yes:
+     ```bash
+     if [[ "$OSTYPE" == darwin* ]]; then
+       open "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md"
+     elif [[ "$OSTYPE" == msys* || "$OSTYPE" == cygwin* || -n "${WINDIR:-}" ]]; then
+       start "" "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md"
+     else
+       xdg-open "$CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md" 2>/dev/null || echo "Could not open key-prompts file automatically. Path: $CLAUDE_PROJECT_DIR/.claude/tracking/key-prompts/YYYY-MM-DD.md"
+     fi
+     ```
+
+4. If the entire `.claude/tracking/` directory doesn't exist, report: "No tracking directory found for this project. Expected: $CLAUDE_PROJECT_DIR/.claude/tracking/"
+
+Run the bash commands using the Bash tool. Do not ask for confirmation before opening files.

package/src/backfill.py

@@ -1,55 +1,33 @@
 #!/usr/bin/env python3
 """
-Backfill historical Claude Code sessions into tokens.json.
+Backfill historical Claude Code sessions into tracking.db.
 
 Usage:
   python3 backfill.py <project_root>
 
 Scans ~/.claude/projects/<slug>/*.jsonl for transcripts belonging to the
 given project, parses token usage from each turn, and upserts entries to
-<project_root>/.claude/tracking/tokens.json. Sessions where all turns are
+<project_root>/.claude/tracking/tracking.db. Sessions where all turns are
 already present are skipped.
-
-Old-format entries (no turn_index field) are replaced with per-turn entries.
 """
 import sys, json, os, glob
 from datetime import datetime
+from platform_utils import get_transcripts_dir, slugify_path
+from cost import compute_cost
+import storage
 
 project_root = os.path.abspath(sys.argv[1])
 project_name = os.path.basename(project_root)
 tracking_dir = os.path.join(project_root, ".claude", "tracking")
-tokens_file = os.path.join(tracking_dir, "tokens.json")
 
 # Claude Code slugifies project paths: replace "/" with "-"
-slug = project_root.replace("/", "-")
-transcripts_dir = os.path.expanduser("~/.claude/projects/" + slug)
+slug = slugify_path(project_root)
+transcripts_dir = os.path.join(get_transcripts_dir(), slug)
 
 if not os.path.isdir(transcripts_dir):
     print("No transcript directory found, nothing to backfill.")
     sys.exit(0)
 
-# Load existing data
-data = []
-if os.path.exists(tokens_file):
-    try:
-        with open(tokens_file) as f:
-            data = json.load(f)
-    except Exception:
-        data = []
-
-# Remove old-format entries (no turn_index) — they will be re-processed
-old_sessions = {e.get("session_id") for e in data if "turn_index" not in e}
-data = [e for e in data if "turn_index" in e]
-
-# Build index of existing (session_id, turn_index) pairs
-existing_turns = {(e.get("session_id"), e.get("turn_index")) for e in data}
-
-# Count turns per known session
-turns_per_session = {}
-for e in data:
-    sid = e.get("session_id")
-    turns_per_session[sid] = turns_per_session.get(sid, 0) + 1
-
 def parse_turns(jf):
     """Parse a JSONL transcript into per-turn entries. Returns list of dicts."""
     msgs = []       # (role, timestamp)
@@ -58,7 +36,7 @@ def parse_turns(jf):
     first_ts = None
 
     try:
-        with open(jf) as f:
+        with open(jf, encoding='utf-8') as f:
             for line in f:
                 try:
                     obj = json.loads(line)
@@ -136,10 +114,7 @@ def compute_turns(msgs, usages, first_ts, model, session_id, project_name):
                 except Exception:
                     pass
 
-                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
+                cost = compute_cost(inp, out, cache_create, cache_read, model)
 
                 # Turn timestamp = user message timestamp
                 turn_ts = user_ts
@@ -200,33 +175,38 @@ for jf in jsonl_files:
         continue
 
     expected_count = len(turn_entries)
-    existing_count = turns_per_session.get(session_id, 0)
+    existing_count = storage.count_turns_for_session(tracking_dir, session_id)
 
-    # If all turns already present and session not in old-format set, skip
-    if existing_count >= expected_count and session_id not in old_sessions:
+    if existing_count >= expected_count:
         continue
 
-    # Upsert: replace any existing turns for this session with fresh data
-    data = [e for e in data if e.get("session_id") != session_id]
-    data.extend(turn_entries)
+    # Replace all turns for this session with fresh data
+    storage.replace_session_turns(tracking_dir, session_id, turn_entries)
     new_entries.extend(turn_entries)
     sessions_processed += 1
 
-# Sort by (date, session_id, turn_index)
-data.sort(key=lambda x: (x.get("date", ""), x.get("session_id", ""), x.get("turn_index", 0)))
-
-# Write updated tokens.json
-if new_entries:
-    os.makedirs(os.path.dirname(tokens_file), exist_ok=True)
-    with open(tokens_file, "w") as f:
-        json.dump(data, f, indent=2)
-        f.write("\n")
-
 total_turns = len(new_entries)
 print(f"{sessions_processed} session{'s' if sessions_processed != 1 else ''} processed, {total_turns} turn{'s' if total_turns != 1 else ''} written.")
 
+# Backfill friction events from the same transcripts
+from parse_friction import parse_friction, upsert_friction
+
+friction_file = os.path.join(tracking_dir, "friction.json")
+friction_count = 0
+for jf in jsonl_files:
+    session_id = os.path.splitext(os.path.basename(jf))[0]
+    try:
+        events = parse_friction(jf, session_id, project_name, "main")
+        upsert_friction(friction_file, session_id, events)
+        friction_count += len(events)
+    except Exception:
+        pass
+
+if friction_count:
+    print(f"{friction_count} friction event{'s' if friction_count != 1 else ''} backfilled.")
+
 # Regenerate charts if we added anything
-if new_entries:
+if new_entries or friction_count:
     script_dir = os.path.dirname(os.path.abspath(__file__))
     charts_html = os.path.join(tracking_dir, "charts.html")
-    os.system(f'python3 "{script_dir}/generate-charts.py" "{tokens_file}" "{charts_html}" 2>/dev/null')
+    os.system(f'python3 "{script_dir}/generate-charts.py" "{tracking_dir}" "{charts_html}" 2>/dev/null')

package/src/cost-summary.py

@@ -1,9 +1,10 @@
 #!/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)
-  python3 cost-summary.py --chart  (open tracking charts in browser)
+  python3 cost-summary.py                          (auto-discover tracking dir)
+  python3 cost-summary.py /path/to/.claude/tracking (explicit tracking dir)
+  python3 cost-summary.py /path/to/tokens.json      (legacy compat)
+  python3 cost-summary.py --chart                    (open tracking charts in browser)
 """
 import sys
 import json
@@ -12,6 +13,10 @@ import webbrowser
 from collections import defaultdict
 from datetime import date
 
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+import storage
+
 def find_git_root():
     root = os.getcwd()
     while root != "/":
@@ -20,12 +25,12 @@ def find_git_root():
         root = os.path.dirname(root)
     return root
 
-def find_tokens_file():
+def find_tracking_dir():
     root = find_git_root()
-    path = os.path.join(root, ".claude", "tracking", "tokens.json")
-    if os.path.exists(path):
+    path = os.path.join(root, ".claude", "tracking")
+    if os.path.isdir(path):
         return path
-    sys.exit(f"No tokens.json found at {path}")
+    sys.exit(f"No tracking directory found at {path}")
 
 def format_duration(seconds):
     if seconds <= 0:
@@ -44,10 +49,16 @@ if "--chart" in sys.argv:
     webbrowser.open(f"file://{chart}")
     sys.exit(0)
 
-tokens_file = sys.argv[1] if len(sys.argv) > 1 else find_tokens_file()
+# Backward compat: accept tokens.json path or tracking dir
+arg = sys.argv[1] if len(sys.argv) > 1 and sys.argv[1] != "--chart" else None
+if arg and arg.endswith('.json'):
+    tracking_dir = os.path.dirname(os.path.abspath(arg))
+elif arg:
+    tracking_dir = os.path.abspath(arg)
+else:
+    tracking_dir = find_tracking_dir()
 
-with open(tokens_file) as f:
-    data = json.load(f)
+data = storage.get_all_turns(tracking_dir)
 
 if not data:
     print("No sessions recorded yet.")
@@ -89,7 +100,8 @@ 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)))}")
+project_name = os.path.basename(os.path.dirname(os.path.dirname(tracking_dir)))
+print(f"  Cost Summary — {project_name}")
 print("=" * W)
 
 print(f"\nBy date:")
@@ -125,4 +137,29 @@ days = len(by_date)
 if days > 1:
     print(f"\n  Avg cost/day:      ${total_cost/days:>11.2f}  over {days} days")
 
+# --- Friction summary ---
+friction_file = os.path.join(tracking_dir, "friction.json")
+if os.path.exists(friction_file):
+    try:
+        with open(friction_file, encoding='utf-8') as f:
+            friction_data = json.load(f)
+        if friction_data:
+            print(f"\nFriction:")
+            friction_total = len(friction_data)
+            cat_counts = defaultdict(int)
+            tool_counts = defaultdict(int)
+            for fe in friction_data:
+                cat_counts[fe.get('category', 'unknown')] += 1
+                tn = fe.get('tool_name')
+                if tn:
+                    tool_counts[tn] += 1
+            top_cat = max(cat_counts, key=cat_counts.get)
+            print(f"  Total events:      {friction_total:>8}")
+            print(f"  Top category:      {top_cat:>8}  ({cat_counts[top_cat]} events)")
+            if tool_counts:
+                top_tool = max(tool_counts, key=tool_counts.get)
+                print(f"  Top tool:          {top_tool:>8}  ({tool_counts[top_tool]} events)")
+    except Exception:
+        pass
+
 print("=" * W)

package/src/cost.py

@@ -0,0 +1,7 @@
+def compute_cost(input_tokens, output_tokens, cache_creation, cache_read, model):
+    """Compute estimated API list-price cost in USD."""
+    if 'opus' in model:
+        return (input_tokens * 15 / 1e6 + cache_creation * 18.75 / 1e6 +
+                cache_read * 1.50 / 1e6 + output_tokens * 75 / 1e6)
+    return (input_tokens * 3 / 1e6 + cache_creation * 3.75 / 1e6 +
+            cache_read * 0.30 / 1e6 + output_tokens * 15 / 1e6)

package/src/export-json.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Export tracking.db to JSON files for portability.
+
+Usage: python3 export-json.py [<tracking_dir>]
+Defaults to .claude/tracking/ in the current git root.
+"""
+import sys, os
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+import storage
+
+def find_tracking_dir():
+    root = os.getcwd()
+    while root != "/":
+        if os.path.exists(os.path.join(root, ".git")):
+            return os.path.join(root, ".claude", "tracking")
+        root = os.path.dirname(root)
+    return os.path.join(os.getcwd(), ".claude", "tracking")
+
+tracking_dir = sys.argv[1] if len(sys.argv) > 1 else find_tracking_dir()
+
+if not os.path.exists(os.path.join(tracking_dir, "tracking.db")):
+    sys.exit(f"No tracking.db found in {tracking_dir}")
+
+storage.export_json(tracking_dir)
+print(f"Exported to {tracking_dir}/tokens.json and agents.json")