@abnersajr/claude-timeline 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 claude-timeline contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+<p align="center">
+  <img src="packages/web/public/logo.svg" alt="claude-timeline" width="400" />
+</p>
+
+<p align="center">
+  <strong>Extract and visualize Claude Code session timelines</strong><br/>
+  Conversations · Tool calls · Pricing · Tokens · Subagents
+</p>
+
+<p align="center">
+  <a href="https://github.com/abnersajr/claude-timeline/actions"><img src="https://github.com/abnersajr/claude-timeline/workflows/CI/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@abnersajr/claude-timeline"><img src="https://img.shields.io/npm/v/@abnersajr/claude-timeline" alt="npm version" /></a>
+  <a href="https://github.com/abnersajr/claude-timeline/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@abnersajr/claude-timeline" alt="license" /></a>
+  <a href="https://ko-fi.com/abnersajr"><img src="https://img.shields.io/badge/Ko--fi-Support%20the%20project-ff5e5b?logo=ko-fi&logoColor=white" alt="Ko-fi" /></a>
+</p>
+
+> **👋 About me:** I'm Abner — a dev from Brazil 🇧🇷 now living in Montreal 🍁. This project started because I was frustrated with existing tools and decided to vibe-code my own. It grew into something real, and now I'm sharing it with the community.
+>
+> **☕ Donations** will support continued development of this project, and a portion will be donated to an NGO that takes care of animals 🐾. If this tool saved you time, consider fueling the next feature!
+
+---
+
+## Installation
+
+```bash
+npm install -g @abnersajr/claude-timeline
+```
+
+Or run directly with npx (no install needed):
+
+```bash
+npx @abnersajr/claude-timeline
+```
+
+**Requirements:** Node.js >= 22
+
+## Usage
+
+### Web UI (recommended)
+
+Start the server and open the interactive timeline in your browser:
+
+```bash
+claude-timeline serve
+```
+
+Opens `http://localhost:5199` automatically. Use `--port` to change the port:
+
+```bash
+claude-timeline serve --port 3000
+```
+
+### CLI
+
+List recent sessions:
+
+```bash
+claude-timeline list
+```
+
+Extract a specific session to JSON:
+
+```bash
+claude-timeline extract --session-id <id>
+```
+
+### Cost Capture Setup
+
+Get real-time per-turn cost tracking by installing the statusline wrapper:
+
+```bash
+claude-timeline setup
+```
+
+This hooks into Claude Code's statusline and captures token usage, pricing, and model data to a local SQLite database. The web UI reads this data for live cost streaming.
+
+To uninstall, remove the `statusLine` key from `~/.claude/settings.json` and run:
+
+```bash
+rm -rf ~/.claude-timeline/
+```
+
+## What is this?
+
+Claude Code stores rich session data in local SQLite and JSONL files, but there's no built-in way to see the full picture. **claude-timeline** extracts, merges, and visualizes everything — conversations, tool calls, token usage, costs, and subagent activity.
+
+### Features
+
+- 📊 **Full session timelines** — conversations, tool calls, file edits, all in order
+- 💰 **Cost tracking** — per-turn and per-model pricing with token breakdowns
+- 🤖 **Subagent detection** — automatically identifies and resolves subagent sessions
+- 🧠 **Context analysis** — tracks context window usage, phases, and injections
+- 🎨 **Web UI** — interactive timeline visualization with dark/light themes
+- ⚡ **CLI tool** — extract session data from the command line
+
+## CLI Reference
+
+```
+claude-timeline <command> [options]
+
+Commands:
+  serve [--port <port>]    Start web UI + API server (default: 5199)
+  extract --session-id <id> Extract a specific session to JSON
+  list                     List all available sessions
+  setup                    Install cost-capture statusline wrapper
+  update-pricing           Fetch latest model pricing from Anthropic
+  --help                   Show help
+
+Options:
+  --port <port>            Server port (serve mode, default: 5199)
+  --db-path <path>         SQLite DB path (default: ~/.claude/usage.db)
+  --projects-dir <path>    Projects directory (default: ~/.claude/projects)
+  --output <path>          Write JSON to file instead of stdout
+```
+
+## Understanding Claude Code Sessions
+
+To get the most out of claude-timeline, it helps to understand how Claude Code works under the hood.
+
+### Core Concepts
+
+| Concept | What it is |
+|---------|------------|
+| **Session** | A single Claude Code interaction lifecycle. Started when you launch `claude` or run a slash command. All work shares a persistent conversation history. |
+| **Turn** | A single API call to the Claude model. Each turn includes cached context, new input, and model output. |
+| **Token** | A unit of text (~4 English characters). All billing is token-based. "Hello world" is roughly 3 tokens. |
+| **Prompt Caching** | Claude caches repeated context (system prompt, conversation history) to avoid re-processing. Cached context is billed at 10% of standard input rates. |
+
+### How Tokens Are Billed
+
+Every Claude Code interaction uses four billable token types:
+
+| Token Type | What it means | Cost (Sonnet 4) |
+|------------|---------------|-----------------|
+| **Input** | New text sent to the model that is NOT cached. Usually tiny (1-2 tokens). | $3.00 / MTok |
+| **Output** | Model-generated text, tool requests, thinking. The most expensive type. | $15.00 / MTok |
+| **Cache Creation** | One-time cost to write context to the cache. | $3.75 / MTok |
+| **Cache Read** | Per-turn cost to retrieve cached context. Compounds over turns. | $0.30 / MTok |
+
+> **Key insight**: `input_tokens` is NOT the total input. It's the non-cached delta (typically 1-2 tokens). The bulk of your context is in `cache_read_input_tokens`.
+
+### How Cache Read Compounds
+
+Each turn reads the entire cached context (system prompt + all previous conversation). As the conversation grows, so does cache read:
+
+| Session Length | Avg Cache Read/Turn | Total Cache Read | Cache Read Cost |
+|----------------|---------------------|------------------|-----------------|
+| 1 turn | 12k | 12k | ~$0.004 |
+| 10 turns | 34k | 340k | ~$0.10 |
+| 28 turns | 33k | 929k | ~$0.28 |
+| 100 turns | 35k | 3.5M | ~$1.05 |
+
+The 929k number sounds large, but at $0.30/MTok it costs less than a quarter. **Output tokens are 5x more expensive** than cache read.
+
+### How Tool Calls Affect Cost
+
+Tool results (success or failure) are added to conversation history. Large tool outputs compound:
+
+- Reading a 100k-token file in Turn 5 adds 100k tokens to history
+- Turns 6-28 each read that extra 100k in cache
+- Cost: 23 turns × 100k × $0.30/MTok = ~$0.69 extra
+
+This is why targeted searches (`grep "ERROR" app.log`) are cheaper than reading entire files (`cat app.log`).
+
+## Tips for Efficient Sessions
+
+| Strategy | Impact |
+|----------|--------|
+| **Start in the project directory** | `cd ~/projects/my-app && claude` instead of `cd ~ && claude "fix X in my-app"`. Broader scope = more file discovery = more cache bloat. |
+| **Use exact file paths** | "Edit `src/components/Button.tsx`" instead of "edit the button component". Reduces discovery turns. |
+| **Batch related tasks** | "Fix X, Y, Z" in one session vs three separate sessions. Fewer turns = less cumulative cache read. |
+| **Keep sessions under 15 turns** | After 10-15 turns, restart to reset cache accumulation. A 10-turn session costs ~$0.18 vs ~$0.63 for 28 turns. |
+| **Watch tool output sizes** | Use `head`, `tail`, `grep` to limit output. A 100k-token file read adds ~$0.69 in cache bloat over 28 turns. |
+| **Use `.claudeignore`** | Exclude `node_modules/`, `dist/`, `*.log` from discovery to prevent unrelated files from entering context. |
+
+## Data Sources
+
+| Source | Location | Contents |
+|--------|----------|----------|
+| SQLite | `~/.claude/usage.db` | Sessions, turns, token counts |
+| JSONL | `~/.claude/projects/<project>/<session>.jsonl` | Full message content, tool calls, file paths |
+
+## Troubleshooting
+
+### Find your recent sessions
+
+```bash
+sqlite3 ~/.claude/usage.db "SELECT session_id, project_name, total_cache_read, turn_count, last_timestamp FROM sessions WHERE last_timestamp > datetime('now', '-1 day') ORDER BY total_cache_read DESC LIMIT 5;"
+```
+
+### Get full token breakdown for a session
+
+```bash
+sqlite3 ~/.claude/usage.db "SELECT timestamp, cache_read_tokens, cache_creation_tokens, input_tokens, output_tokens, tool_name FROM turns WHERE session_id='YOUR_SESSION_ID' ORDER BY timestamp;"
+```
+
+### Calculate session cost (Sonnet 4 rates)
+
+```bash
+sqlite3 ~/.claude/usage.db "SELECT
+  session_id,
+  ROUND(total_cache_read * 0.30 / 1000000, 4) AS cache_read_USD,
+  ROUND(total_output_tokens * 15.00 / 1000000, 4) AS output_USD,
+  ROUND(total_cache_creation * 3.75 / 1000000, 4) AS creation_USD,
+  ROUND(total_input_tokens * 3.00 / 1000000, 4) AS input_USD,
+  ROUND((total_cache_read * 0.30 + total_output_tokens * 15.00 + total_cache_creation * 3.75 + total_input_tokens * 3.00) / 1000000, 4) AS total_USD
+FROM sessions WHERE session_id='YOUR_SESSION_ID';"
+```
+
+### Check which files were read in a session
+
+```bash
+cat ~/.claude/projects/YOUR_PROJECT_DIR/YOUR_SESSION_ID.jsonl | jq -r 'select(.type == "assistant" and .message.content) | .message.content[]? | select(.type == "tool_use" and .name == "Read") | .input.filePath' 2>/dev/null
+```
+
+## Development
+
+```bash
+git clone https://github.com/abnersajr/claude-timeline.git
+cd claude-timeline
+pnpm install
+pnpm dev
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/capture.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { getDb, upsertSnapshot, upsertSessionSummary } from "./db.js";
+
+const CONFIG_PATH = join(process.env.HOME, ".claude-timeline", "config.json");
+
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function parseStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve(null);
+
+    let raw = "";
+    let settled = false;
+    let firstByteTimer;
+    let idleTimer;
+
+    const cleanup = () => {
+      clearTimeout(firstByteTimer);
+      clearTimeout(idleTimer);
+      process.stdin.off("data", onData);
+      process.stdin.off("end", onEnd);
+      process.stdin.pause();
+    };
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+
+    const tryParse = () => {
+      const trimmed = raw.trim();
+      if (!trimmed) return null;
+      try { return JSON.parse(trimmed); } catch { return undefined; }
+    };
+
+    const onData = (chunk) => {
+      clearTimeout(firstByteTimer);
+      raw += String(chunk);
+      const parsed = tryParse();
+      if (parsed !== undefined) return finish(parsed);
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => finish(tryParse() ?? null), 30);
+    };
+
+    const onEnd = () => finish(tryParse() ?? null);
+
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    firstByteTimer = setTimeout(() => finish(null), 250);
+  });
+}
+
+function extractCostData(json) {
+  const cost = json.cost ?? {};
+  const ctx = json.context_window ?? {};
+  const current = ctx.current_usage ?? {};
+
+  return {
+    session_id: json.session_id ?? null,
+    total_cost_usd: typeof cost.total_cost_usd === "number" ? cost.total_cost_usd : null,
+    duration_ms: cost.total_duration_ms ?? null,
+    api_duration_ms: cost.total_api_duration_ms ?? null,
+    input_tokens: ctx.total_input_tokens ?? current.input_tokens ?? 0,
+    output_tokens: ctx.total_output_tokens ?? current.output_tokens ?? 0,
+    cache_read_tokens: current.cache_read_input_tokens ?? 0,
+    cache_creation_tokens: current.cache_creation_input_tokens ?? 0,
+    model: json.model?.display_name ?? json.model?.id ?? null,
+    lines_added: cost.total_lines_added ?? 0,
+    lines_removed: cost.total_lines_removed ?? 0,
+  };
+}
+
+function killOtherInstances() {
+  try {
+    const myPid = process.pid;
+    const pids = execSync("pgrep -f 'node.*capture\\.js'", { encoding: "utf-8" })
+      .trim().split("\n").filter(Boolean).map(Number).filter((p) => p !== myPid);
+    for (const pid of pids) {
+      try { process.kill(pid, "SIGTERM"); } catch {}
+    }
+  } catch {}
+}
+
+async function main() {
+  killOtherInstances();
+  const data = await parseStdin();
+  if (!data?.session_id) {
+    process.exit(0);
+  }
+
+  const costData = extractCostData(data);
+
+  try {
+    const db = getDb();
+    upsertSnapshot(db, { ...costData, raw_json: JSON.stringify(data) });
+    if (costData.total_cost_usd !== null) {
+      upsertSessionSummary(db, {
+        session_id: costData.session_id,
+        total_cost_usd: costData.total_cost_usd,
+        model: costData.model,
+      });
+    }
+    db.close();
+  } catch (e) {
+    process.stderr.write(`[cost-capture] DB error: ${e.message}\n`);
+  }
+
+  const config = loadConfig();
+  if (config.originalStatusLine?.command) {
+    try {
+      const { spawnSync } = await import("node:child_process");
+      const result = spawnSync("sh", ["-c", config.originalStatusLine.command], {
+        input: JSON.stringify(data),
+        encoding: "utf-8",
+        timeout: 2000,
+        env: { ...process.env, COLUMNS: process.env.COLUMNS ?? "80" },
+      });
+      if (result.stdout) process.stdout.write(result.stdout);
+    } catch {
+      // Original statusline failed — not our problem
+    }
+  }
+
+  process.exit(0);
+}
+
+main();

package/dist/classifier.d.ts

@@ -0,0 +1,37 @@
+import type { ClassifiedMessage, MessageCategory, RawJsonlRecord } from "./types";
+/**
+ * Hard noise: system/summary/file-history-snapshot/queue-operation/attachment/last-prompt/permission-mode types,
+ * sidechain, synthetic assistant, hard noise tags, interruptions.
+ */
+export declare function isHardNoise(record: RawJsonlRecord): boolean;
+/** Compact messages are marked by isCompactSummary flag */
+export declare function isCompactMessage(record: RawJsonlRecord): boolean;
+/**
+ * System messages: user-type messages that contain command output
+ * (local-command-stdout/stderr). These arrive as type="user" in JSONL
+ * but represent command output, not user input.
+ */
+export declare function isSystemMessage(record: RawJsonlRecord): boolean;
+/**
+ * User messages: type=user, isMeta=false, has text/image content
+ * (not just tool_result blocks). Meta messages (tool results) are
+ * classified as assistant because they represent assistant context.
+ * Tool-result-only records (isMeta=null, content is array of tool_result)
+ * are also classified as assistant — they're CLI tool outputs, not user input.
+ */
+export declare function isUserMessage(record: RawJsonlRecord): boolean;
+/**
+ * Classify a single JSONL record into a category using the priority cascade:
+ * 1. hardNoise — noise types, sidechain, synthetic, hard noise tags, interruptions
+ * 2. compact — isCompactSummary === true
+ * 3. system — user messages with command output (local-command-stdout/stderr)
+ * 4. user — type=user, not meta, has text/image content
+ * 5. assistant — everything else (catch-all)
+ */
+export declare function classifyMessage(record: RawJsonlRecord): MessageCategory;
+/**
+ * Classify an array of messages, returning ClassifiedMessage objects
+ * that pair each record with its category.
+ */
+export declare function classifyMessages(records: RawJsonlRecord[]): ClassifiedMessage[];
+//# sourceMappingURL=classifier.d.ts.map

package/dist/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../src/classifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AA4CjF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAwB3D;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAK/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAe7D;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAMvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAK/E"}

package/dist/classifier.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=classifier.test.d.ts.map

package/dist/classifier.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.test.d.ts","sourceRoot":"","sources":["../src/classifier.test.ts"],"names":[],"mappings":""}

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}