graphtrack 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fahim Islam
+
+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,70 @@
+# Graphtrack
+
+Visualize your **Claude Code** token usage as an interactive graph.
+
+Instead of tables and bars, Graphtrack turns a session into a navigable network —
+prompts, tool calls, and their token weight rendered as nodes and edges. Node size
+is token share, color is tool type, and edges trace how your tokens actually flowed.
+Find out at a glance which tool is eating your budget, or trace a single request
+from prompt to result.
+
+```
+~/.claude/projects/<project>/<session>.jsonl  →  parse  →  graph  →  serve on localhost
+```
+
+## Why local?
+
+This is a **local-first, open-source tool**. Your logs are parsed on your machine and
+served to your own browser at `localhost`. Nothing is uploaded, stored, or shared.
+Your usage data never leaves your computer.
+
+## Getting started
+
+```bash
+# from the repo root
+npm install
+npm run build
+npm start            # starts a localhost server
+```
+
+Then open the printed URL, pick a session (or point Graphtrack at
+`~/.claude/projects`), and explore the graph.
+
+### Preview (no server needed)
+
+A standalone page is generated from a synthetic sample session so you can judge
+the visualization without any setup:
+
+```bash
+npm run build
+node scripts/build-spike.mjs
+# open public/index.html in a browser
+```
+
+## Roadmap
+
+- **Phase 0** — validate the graph metaphor on realistic data ✓ (spike shipped)
+- **Phase 1** — JSONL parser + typed model + per-tool aggregation
+- **Phase 2** — localhost web app: vis.js graph + table view
+- **Phase 3** — multi-session overview, empty state, error handling
+- **Phase 4** — install polish, docs, CI
+
+## Project layout
+
+```
+src/
+  types.ts      shared data model (Session/Turn/ToolCall/Usage)
+  parser.ts     JSONL → typed Session
+  graph.ts      Session → vis.js nodes/edges (aggregate + chronological)
+scripts/
+  build-spike.mjs  regenerates public/graph-data.js from a sample session
+public/
+  index.html       the app page (hand-authored)
+  graph-data.js    generated graph data
+test/
+  fixtures/     sample-session generator
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Graphtrack CLI — run `graphtrack` anywhere to start the local dashboard.
+ *
+ *   graphtrack                     → http://localhost:9090  (reads ~/.claude/projects)
+ *   graphtrack --dir <path>        → read logs from a custom folder
+ *   graphtrack --port <n>          → use a different port (default 9090)
+ *   graphtrack --help              → this help
+ */
+import { startServer, DEFAULT_LOGS_DIR, DEFAULT_PORT } from "./server.js";
+function printHelp() {
+    console.log(`
+Graphtrack — visualize Claude Code token usage as a graph.
+
+Usage:
+  graphtrack [options]
+
+Options:
+  --dir, -d <path>   read session logs from <path> (default: ${DEFAULT_LOGS_DIR})
+  --port, -p <n>     serve on port <n> (default: ${DEFAULT_PORT})
+  --help, -h         show this help
+
+Everything runs locally. Your logs never leave your machine.
+`);
+}
+function parseArgs(argv) {
+    const opts = { logsDir: DEFAULT_LOGS_DIR };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--dir" || a === "-d") {
+            opts.logsDir = argv[++i] ?? DEFAULT_LOGS_DIR;
+        }
+        else if (a === "--port" || a === "-p") {
+            opts.port = Number(argv[++i]);
+        }
+        else if (a === "--help" || a === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+    }
+    return opts;
+}
+startServer(parseArgs(process.argv.slice(2)));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1E,SAAS,SAAS;IAChB,OAAO,CAAC,GAAG,CAAC;;;;;;;+DAOiD,gBAAgB;mDAC5B,YAAY;;;;CAI9D,CAAC,CAAC;AACH,CAAC;AAOD,SAAS,SAAS,CAAC,IAAc;IAC/B,MAAM,IAAI,GAAe,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,gBAAgB,CAAC;QAC/C,CAAC;aAAM,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC;aAAM,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,SAAS,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/graph.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Graph builder: transforms the parsed Session into vis.js node/edge arrays.
+ *
+ * Two views are provided so Phase 0 can compare which reads better:
+ *   - aggregate:   a "hub & tool" graph — session center connected to tool nodes
+ *                  sized by cumulative token share, colored by tool type.
+ *   - chronological: the turn-by-turn chain — user prompts and tool calls in
+ *                  the order they happened.
+ *
+ * vis.js nodes use `value` (scales node size) and `color.background`.
+ */
+import type { Session, ToolAggregate } from "./types.js";
+/**
+ * Claude Code logs report usage per assistant message, not per tool call.
+ * To size tool nodes fairly, spread each turn's total tokens onto its tool
+ * calls proportional to call count. This is a heuristic — call.totalTokens is
+ * approximate per-call, exact in aggregate. Callers must invoke it after parse.
+ */
+export declare function spreadTokens(session: Session): void;
+export interface VisNode {
+    id: string;
+    label: string;
+    value?: number;
+    color?: {
+        background?: string;
+        border?: string;
+    };
+    group?: string;
+    title?: string;
+    data?: Record<string, unknown>;
+}
+export interface VisEdge {
+    from: string;
+    to: string;
+    value?: number;
+    title?: string;
+    arrows?: string;
+}
+export declare function toolColor(name: string): string;
+/** Hub-and-tool aggregate graph for one session. */
+export declare function buildAggregateGraph(session: Session): {
+    nodes: VisNode[];
+    edges: VisEdge[];
+};
+/** Turn-by-turn chronological graph: session → prompts → their tool calls. */
+export declare function buildChronologicalGraph(session: Session): {
+    nodes: VisNode[];
+    edges: VisEdge[];
+};
+export type { ToolAggregate };

package/dist/graph.js

@@ -0,0 +1,124 @@
+/**
+ * Claude Code logs report usage per assistant message, not per tool call.
+ * To size tool nodes fairly, spread each turn's total tokens onto its tool
+ * calls proportional to call count. This is a heuristic — call.totalTokens is
+ * approximate per-call, exact in aggregate. Callers must invoke it after parse.
+ */
+export function spreadTokens(session) {
+    for (const turn of session.turns) {
+        if (turn.toolCalls.length && turn.totalTokens > 0) {
+            const share = turn.totalTokens / turn.toolCalls.length;
+            for (const call of turn.toolCalls) {
+                call.totalTokens = Math.round(share);
+            }
+        }
+    }
+}
+/** Consistent color per tool name, tuned for a dark canvas. */
+const TOOL_COLORS = {
+    Bash: "#faff69",
+    Read: "#3b82f6",
+    Edit: "#22c55e",
+    Grep: "#ef4444",
+    Glob: "#a78bfa",
+    WebSearch: "#f59e0b",
+    Task: "#22d3ee",
+    Write: "#34d399",
+    default: "#888888",
+};
+export function toolColor(name) {
+    return TOOL_COLORS[name] ?? TOOL_COLORS.default;
+}
+/** Normalize raw token counts into a vis.js-friendly size (sqrt scale). */
+function scale(value) {
+    return Math.sqrt(value) / 10;
+}
+/** Hub-and-tool aggregate graph for one session. */
+export function buildAggregateGraph(session) {
+    const nodes = [];
+    const edges = [];
+    const rootId = "session";
+    nodes.push({
+        id: rootId,
+        label: `${session.project}\n${session.turns.length} turns · ${fmt(session.totalTokens)} tok`,
+        value: 6,
+        color: { background: "#faff69", border: "#e6eb52" },
+        group: "session",
+        title: "This session",
+    });
+    // Group tool calls across the whole session (reuse aggregation).
+    const byTool = new Map();
+    for (const turn of session.turns) {
+        for (const call of turn.toolCalls) {
+            const entry = byTool.get(call.name) ?? { calls: 0, tokens: 0 };
+            entry.calls += 1;
+            entry.tokens += call.totalTokens || 1;
+            byTool.set(call.name, entry);
+        }
+    }
+    const maxTokens = Math.max(1, ...[...byTool.values()].map((v) => v.tokens));
+    for (const [name, agg] of byTool) {
+        const id = `tool:${name}`;
+        nodes.push({
+            id,
+            label: `${name}\n${agg.calls}× · ${fmt(agg.tokens)}`,
+            value: 1 + 5 * (agg.tokens / maxTokens),
+            color: { background: toolColor(name), border: "#ffffff" },
+            group: "tool",
+            title: `${name}: ${agg.calls} calls, ${fmt(agg.tokens)} tokens`,
+        });
+        edges.push({ from: rootId, to: id, value: 2 + 4 * (agg.tokens / maxTokens), title: `${name}: ${fmt(agg.tokens)}` });
+    }
+    return { nodes, edges };
+}
+/** Turn-by-turn chronological graph: session → prompts → their tool calls. */
+export function buildChronologicalGraph(session) {
+    const nodes = [];
+    const edges = [];
+    nodes.push({
+        id: "session",
+        label: session.project,
+        value: 6,
+        color: { background: "#faff69", border: "#e6eb52" },
+        group: "session",
+    });
+    let prevTurnId = "session";
+    for (const turn of session.turns) {
+        const turnId = `turn:${turn.index}`;
+        nodes.push({
+            id: turnId,
+            label: truncate(turn.prompt, 22),
+            value: 2.5,
+            color: { background: "#121212", border: "#3a3a3a" },
+            group: "turn",
+            title: `Turn ${turn.index + 1}: ${turn.prompt}`,
+        });
+        edges.push({ from: prevTurnId, to: turnId, value: 1, arrows: "to" });
+        // Tool calls inside this turn.
+        for (const call of turn.toolCalls) {
+            const callId = `${turnId}:${call.id}`;
+            nodes.push({
+                id: callId,
+                label: call.name,
+                value: 1.2,
+                color: { background: toolColor(call.name), border: "#ffffff" },
+                group: "tool",
+                title: `${call.name} ${call.summary}`,
+            });
+            edges.push({ from: turnId, to: callId, value: 1, arrows: "to" });
+        }
+        prevTurnId = turnId;
+    }
+    return { nodes, edges };
+}
+function fmt(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return String(n);
+}
+function truncate(s, n) {
+    return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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"}

package/dist/parser.d.ts

@@ -0,0 +1,5 @@
+import type { Session, ToolAggregate } from "./types.js";
+/** Extracts tool calls from a session's JSONL and groups them into turns. */
+export declare function parseSession(filePath: string, project: string): Session;
+/** Aggregate tool calls across a session (the collapse-by-tool model). */
+export declare function aggregateTools(session: Session): ToolAggregate[];

package/dist/parser.js

@@ -0,0 +1,145 @@
+/**
+ * Parser: reads Claude Code JSONL log files and produces the typed Session model.
+ *
+ * Handles a single session file. Returns a Session, or throws on a completely
+ * unreadable file (callers decide how to surface partial failures).
+ */
+import { readFileSync } from "node:fs";
+/** Parse one line of JSONL into a drop of structure we care about. */
+function parseLine(raw) {
+    const line = raw.trim();
+    if (!line)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    catch {
+        return null; // malformed line — skip, don't crash
+    }
+    return obj?.message ?? null;
+}
+function contentSummary(content) {
+    if (!content)
+        return "";
+    return content
+        .map((b) => {
+        if (b.type === "text")
+            return b.text ?? "";
+        if (b.type === "tool_use")
+            return "";
+        return "";
+    })
+        .filter(Boolean)
+        .join(" ");
+}
+function tokensOf(usage) {
+    if (!usage)
+        return 0;
+    return ((usage.input_tokens ?? 0) +
+        (usage.output_tokens ?? 0) +
+        (usage.cache_creation_input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0));
+}
+/** Extracts tool calls from a session's JSONL and groups them into turns. */
+export function parseSession(filePath, project) {
+    const raw = readFileSync(filePath, "utf8");
+    const lines = raw.split("\n");
+    const session = {
+        id: filePath.split(/[\\/]/).pop()?.replace(/\.jsonl$/, "") ?? "unknown",
+        project,
+        model: "unknown",
+        startedAt: "",
+        turns: [],
+        totalTokens: 0,
+        totalInput: 0,
+        totalOutput: 0,
+        totalCacheRead: 0,
+        totalCacheWrite: 0,
+    };
+    // We walk the stream and slice it into turns. A turn starts at a user message
+    // that contains a text prompt (i.e. a real request, not a tool_result).
+    let current = null;
+    for (const line of lines) {
+        const msg = parseLine(line);
+        if (!msg)
+            continue;
+        const text = contentSummary(msg.content);
+        // Determine message kind
+        const hasText = Boolean(text.trim());
+        const content = msg.content ?? [];
+        // A new turn begins when the user speaks with text (not a tool_result).
+        if (msg.role === "user" && hasText && content.every((b) => b.type !== "tool_result")) {
+            if (current)
+                session.turns.push(current);
+            current = { prompt: text, index: session.turns.length, toolCalls: [], totalTokens: 0 };
+            continue;
+        }
+        if (!current)
+            continue;
+        // Capture tool_use blocks.
+        for (const block of content) {
+            if (block.type === "tool_use") {
+                const input = block.input ?? {};
+                const summary = Object.entries(input)
+                    .map(([k, v]) => `${k}=${String(v)}`)
+                    .slice(0, 3)
+                    .join(" ");
+                const call = {
+                    id: block.id ?? `tool_${current.index}_${current.toolCalls.length}`,
+                    name: block.name ?? "unknown",
+                    summary,
+                    totalTokens: 0,
+                };
+                current.toolCalls.push(call);
+            }
+        }
+        // Attribute usage to the current turn (assistant text replies carry usage).
+        if (msg.usage) {
+            const usage = msg.usage;
+            session.totalInput += usage.input_tokens ?? 0;
+            session.totalOutput += usage.output_tokens ?? 0;
+            session.totalCacheRead += usage.cache_read_input_tokens ?? 0;
+            session.totalCacheWrite += usage.cache_creation_input_tokens ?? 0;
+            current.totalTokens += tokensOf(usage);
+            if (msg.model && session.model === "unknown")
+                session.model = msg.model;
+        }
+    }
+    if (current)
+        session.turns.push(current);
+    session.startedAt = session.turns[0] ? String(session.turns[0]?.prompt.length) : "";
+    // Derive a pseudo start time from the file's first activity is omitted here;
+    // the fixture/deployer can supply timestamps via a richer parser later.
+    session.totalTokens = session.turns.reduce((a, t) => a + t.totalTokens, 0);
+    return session;
+}
+/** Aggregate tool calls across a session (the collapse-by-tool model). */
+export function aggregateTools(session) {
+    const map = new Map();
+    for (const turn of session.turns) {
+        for (const call of turn.toolCalls) {
+            const agg = map.get(call.name) ?? {
+                name: call.name,
+                calls: 0,
+                totalTokens: 0,
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+            };
+            agg.calls += 1;
+            agg.totalTokens += call.totalTokens;
+            const u = call.usage;
+            if (u) {
+                agg.inputTokens += u.input_tokens ?? 0;
+                agg.outputTokens += u.output_tokens ?? 0;
+                agg.cacheRead += u.cache_read_input_tokens ?? 0;
+                agg.cacheWrite += u.cache_creation_input_tokens ?? 0;
+            }
+            map.set(call.name, agg);
+        }
+    }
+    return [...map.values()].sort((a, b) => b.totalTokens - a.totalTokens);
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAgBvC,sEAAsE;AACtE,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,GAAuI,CAAC;IAC5I,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,qCAAqC;IACpD,CAAC;IACD,OAAO,GAAG,EAAE,OAAO,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED,SAAS,cAAc,CAAC,OAAiC;IACvD,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3C,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,EAAE,CAAC;QACrC,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;SACD,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,KAAwB;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,OAAO,CACL,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;QACzB,CAAC,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC;QAC1B,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,CAAC;QACxC,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,CAAC,CACrC,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,OAAe;IAC5D,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE9B,MAAM,OAAO,GAAY;QACvB,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,SAAS;QACvE,OAAO;QACP,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,EAAE;QACT,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,CAAC;QACd,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,CAAC;KACnB,CAAC;IAEF,8EAA8E;IAC9E,wEAAwE;IACxE,IAAI,OAAO,GAAgB,IAAI,CAAC;IAEhC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG;YAAE,SAAS;QAEnB,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEzC,yBAAyB;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;QAElC,wEAAwE;QACxE,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,EAAE,CAAC;YACrF,IAAI,OAAO;gBAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzC,OAAO,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;YACvF,SAAS;QACX,CAAC;QAED,IAAI,CAAC,OAAO;YAAE,SAAS;QAEvB,2BAA2B;QAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAI,KAAK,CAAC,KAAiC,IAAI,EAAE,CAAC;gBAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;qBAClC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;qBACpC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;qBACX,IAAI,CAAC,GAAG,CAAC,CAAC;gBACb,MAAM,IAAI,GAAa;oBACrB,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,QAAQ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE;oBACnE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,SAAS;oBAC7B,OAAO;oBACP,WAAW,EAAE,CAAC;iBACf,CAAC;gBACF,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YACxB,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;YAC9C,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC;YAChD,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC,uBAAuB,IAAI,CAAC,CAAC;YAC7D,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,CAAC;YAClE,OAAO,CAAC,WAAW,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC;YACvC,IAAI,GAAG,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;gBAAE,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,IAAI,OAAO;QAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEzC,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,6EAA6E;IAC7E,wEAAwE;IAExE,OAAO,CAAC,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAChC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,CAAC;gBACR,WAAW,EAAE,CAAC;gBACd,WAAW,EAAE,CAAC;gBACd,YAAY,EAAE,CAAC;gBACf,SAAS,EAAE,CAAC;gBACZ,UAAU,EAAE,CAAC;aACd,CAAC;YACF,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;YACf,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC;YACpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YACrB,IAAI,CAAC,EAAE,CAAC;gBACN,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;gBACvC,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC;gBACzC,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,uBAAuB,IAAI,CAAC,CAAC;gBAChD,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC,2BAA2B,IAAI,CAAC,CAAC;YACvD,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;AACzE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import type { Server } from "node:http";
+export declare const DEFAULT_LOGS_DIR: string;
+declare const DEFAULT_PORT = 9090;
+export interface StartOptions {
+    logsDir?: string;
+    port?: number;
+}
+/** Recursively collect *.jsonl session files under logsDir. */
+export declare function findSessionFiles(logsDir: string): string[];
+export declare function startServer(opts?: StartOptions): Server;
+export { DEFAULT_PORT };

package/dist/server.js

@@ -0,0 +1,111 @@
+/**
+ * Graphtrack localhost server.
+ *
+ * Serves the static app (public/) and exposes the user's Claude Code session
+ * logs over a small read-only API. Everything runs locally — nothing is sent
+ * anywhere.
+ *
+ *   GET /                    → public/index.html
+ *   GET /api/sessions         → lightweight list of all sessions found
+ *   GET /api/session/:slug/:id → full graph data for one session
+ */
+import express from "express";
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSession, aggregateTools } from "./parser.js";
+import { buildAggregateGraph, buildChronologicalGraph, toolColor, spreadTokens } from "./graph.js";
+export const DEFAULT_LOGS_DIR = join(homedir(), ".claude", "projects");
+const DEFAULT_PORT = 9090;
+/**
+ * public/ lives at the package root, not the caller's cwd — resolve via this
+ * module. The compiled file is at <root>/dist/server.js, so one level up.
+ */
+const PUBLIC_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "public");
+/** Recursively collect *.jsonl session files under logsDir. */
+export function findSessionFiles(logsDir) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile() && e.name.endsWith(".jsonl"))
+                out.push(p);
+        }
+    };
+    walk(logsDir);
+    return out.sort();
+}
+/** Derive the project slug from a file path relative to the logs root. */
+function projectOf(logsDir, file) {
+    const rel = relative(logsDir, dirname(file));
+    return rel ? basename(rel) : "?";
+}
+export function startServer(opts = {}) {
+    const logsDir = opts.logsDir ?? DEFAULT_LOGS_DIR;
+    const port = opts.port ?? DEFAULT_PORT;
+    const app = express();
+    // Lightweight session listing.
+    app.get("/api/sessions", (_req, res) => {
+        const sessions = findSessionFiles(logsDir).map((file) => {
+            const id = basename(file).replace(/\.jsonl$/, "");
+            return { id, project: projectOf(logsDir, file), file };
+        });
+        res.json({ sessions, logsDir });
+    });
+    // Full graph data for one session.
+    app.get("/api/session/:slug/:id", (req, res) => {
+        const { slug, id } = req.params;
+        const dir = join(logsDir, slug);
+        const file = join(dir, `${id}.jsonl`);
+        let session;
+        try {
+            session = parseSession(file, slug);
+        }
+        catch (err) {
+            res.status(404).json({ error: String(err) });
+            return;
+        }
+        spreadTokens(session);
+        const aggregates = aggregateTools(session).map((a) => ({
+            name: a.name,
+            calls: a.calls,
+            totalTokens: a.totalTokens,
+            color: toolColor(a.name),
+        }));
+        res.json({
+            session: {
+                id: session.id,
+                project: session.project,
+                model: session.model,
+                turns: session.turns.length,
+                toolCalls: session.turns.reduce((a, t) => a + t.toolCalls.length, 0),
+                totalTokens: session.totalTokens,
+                totalInput: session.totalInput,
+                totalOutput: session.totalOutput,
+                totalCacheRead: session.totalCacheRead,
+                totalCacheWrite: session.totalCacheWrite,
+            },
+            aggregate: buildAggregateGraph(session),
+            chronological: buildChronologicalGraph(session),
+            toolAggregates: aggregates,
+        });
+    });
+    // Static app (resolved relative to the installed package, not the cwd).
+    app.use(express.static(PUBLIC_DIR));
+    return app.listen(port, () => {
+        console.log(`  Graphtrack → http://localhost:${port}`);
+        console.log(`  Reading logs from: ${logsDir}`);
+    });
+}
+export { DEFAULT_PORT };
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Graphtrack data model — the typed representation of Claude Code session logs.
+ * These types are the single source of truth shared by the parser and the UI.
+ */
+/** Raw token-usage numbers as surfaced in Claude Code JSONL usage blocks. */
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+}
+/** A single tool invocation within a turn. */
+export interface ToolCall {
+    /** Stable id from the log (e.g. toolu_...) if present, else synthetic. */
+    id: string;
+    /** Tool name: "Bash", "Read", "Edit", "WebSearch", ... */
+    name: string;
+    /** Humanized args/summary, used for node labels. */
+    summary: string;
+    /** Cumulative tokens attributable to this call (input+output+cache). */
+    totalTokens: number;
+    usage?: Usage;
+}
+/** One exchange: the user's prompt + any assistant reply and tool calls. */
+export interface Turn {
+    /** The user prompt text (the thing that was asked). */
+    prompt: string;
+    /** Sequential index within the session. */
+    index: number;
+    /** Tool calls fired in service of this prompt. */
+    toolCalls: ToolCall[];
+    /** Total tokens across this turn (prompt + outputs + tools + cache). */
+    totalTokens: number;
+}
+/** A single parsed Claude Code session file. */
+export interface Session {
+    id: string;
+    /** Project slug directory the session lives under. */
+    project: string;
+    model: string;
+    /** ISO timestamp of first activity. */
+    startedAt: string;
+    turns: Turn[];
+    totalTokens: number;
+    totalInput: number;
+    totalOutput: number;
+    totalCacheRead: number;
+    totalCacheWrite: number;
+}
+/**
+ * Aggregated tool usage across a session (or across sessions).
+ * This is the collapse-by-tool model that powers the top level of the graph.
+ */
+export interface ToolAggregate {
+    name: string;
+    calls: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Graphtrack data model — the typed representation of Claude Code session logs.
+ * These types are the single source of truth shared by the parser and the UI.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "graphtrack",
+  "version": "0.1.0",
+  "description": "Visualize Claude Code token usage as an interactive graph. Local-first, open source, your logs never leave your machine.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "graphtrack": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --experimental-strip-types --test test/*.test.ts",
+    "prepublishOnly": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "files": ["dist", "public/index.html"],
+  "keywords": [
+    "claude-code",
+    "token",
+    "usage",
+    "analytics",
+    "graph",
+    "visualization"
+  ],
+  "dependencies": {
+    "express": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.5.0",
+    "typescript": "^5.5.0"
+  }
+}

package/public/index.html

@@ -0,0 +1,202 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="description" content="Graphtrack — visualize Claude Code token usage as an interactive graph." />
+<title>Graphtrack</title>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/vis-network/9.1.9/standalone/umd/vis-network.min.js"></script>
+<style>
+  :root {
+    --canvas:#0a0a0a; --card:#1a1a1a; --yellow:#faff69; --body:#cccccc; --muted:#888888;
+  }
+  * { box-sizing: border-box; }
+  html, body { height:100%; }
+  body { margin:0; font-family: Inter, system-ui, sans-serif; background:var(--canvas); color:var(--body); display:flex; flex-direction:column; }
+  header { padding:12px 28px; border-bottom:1px solid #2a2a2a; display:flex; align-items:center; gap:18px; flex: 0 0 auto; flex-wrap:wrap; }
+  header h1 { font-size:18px; margin:0; color:#fff; letter-spacing:-0.5px; font-weight:700; }
+  header .dot { color:var(--yellow); margin-right:2px; }
+  header .sub { font-size:12px; color:var(--muted); }
+  select {
+    background:var(--card); color:var(--body); border:1px solid #3a3a3a;
+    padding:6px 10px; border-radius:6px; font-size:13px; max-width:320px;
+  }
+  select:disabled { opacity:0.5; }
+  .toggle { margin-left:auto; display:flex; gap:8px; }
+  .toggle button {
+    background:var(--card); color:var(--body); border:1px solid #3a3a3a;
+    padding:6px 12px; border-radius:6px; cursor:pointer; font-size:13px;
+  }
+  .toggle button:hover { border-color:#5a5a5a; }
+  .toggle button.active { background:var(--yellow); color:#0a0a0a; border-color:var(--yellow); font-weight:600; }
+  #stats { flex: 0 0 auto; padding:12px 28px; display:flex; gap:28px; flex-wrap:wrap; font-size:13px; border-bottom:1px solid #2a2a2a; }
+  #stats .stat { display:flex; flex-direction:column; gap:2px; }
+  #stats .stat .label { color:var(--muted); font-size:11px; text-transform:uppercase; letter-spacing:0.5px; }
+  #stats .stat .value { color:#fff; font-weight:600; font-size:14px; }
+  #graph {
+    flex: 1 1 auto; min-height:0; width:100%;
+    background-color: var(--canvas);
+    background-image:
+      linear-gradient(rgba(255,255,255,0.035) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(255,255,255,0.035) 1px, transparent 1px);
+    background-size: 42px 42px;
+    position: relative;
+  }
+  #graph::after {
+    content:"";
+    position: absolute; inset: 0; pointer-events: none;
+    background: radial-gradient(ellipse at center, rgba(255,250,105,0.04) 0%, transparent 55%);
+  }
+  #graph canvas { position: relative; z-index: 2; }
+  #graph .empty {
+    position: absolute; inset:0; display:flex; flex-direction:column; align-items:center; justify-content:center;
+    gap:8px; z-index:2; text-align:center; padding:24px;
+  }
+  #graph .empty h2 { color:#fff; margin:0; font-size:20px; }
+  #graph .empty p { color:var(--muted); margin:0; font-size:13px; max-width:460px; line-height:1.5; }
+  #graph .empty code { background:var(--card); padding:2px 6px; border-radius:4px; color:var(--yellow); }
+  #spinner { display:none; position:absolute; inset:0; z-index:3; align-items:center; justify-content:center; }
+  #spinner.on { display:flex; }
+  #spinner span { color:var(--yellow); border:2px solid #3a3a3a; border-top-color:var(--yellow); border-radius:50%; width:34px; height:34px; animation:spin 0.8s linear infinite; }
+  @keyframes spin { to { transform: rotate(360deg); } }
+  #glow {
+    position: fixed; inset: 0; pointer-events: none; z-index: 9999;
+    background: radial-gradient(circle 200px at var(--gx, -9999px) var(--gy, -9999px),
+      rgba(255,250,105,0.16), rgba(255,250,105,0.05) 45%, transparent 72%);
+    opacity: 0;
+  }
+  #glow.on { opacity: 1; }
+</style>
+</head>
+<body>
+  <header>
+    <h1><span class="dot">▪</span>Graphtrack</h1>
+    <span class="sub">Claude Code token usage, as a graph</span>
+    <select id="sessionSelect" disabled title="Select a session"><option>Loading sessions…</option></select>
+    <div class="toggle">
+      <button id="btnAgg" class="active">Aggregate</button>
+      <button id="btnChain">Chronological</button>
+    </div>
+  </header>
+  <div id="stats">
+    <div class="stat"><span class="label">Model</span><span class="value" id="sModel">–</span></div>
+    <div class="stat"><span class="label">Turns</span><span class="value" id="sTurns">–</span></div>
+    <div class="stat"><span class="label">Tool calls</span><span class="value" id="sCalls">–</span></div>
+    <div class="stat"><span class="label">Total</span><span class="value" id="sTotal">–</span></div>
+    <div class="stat"><span class="label">Input</span><span class="value" id="sIn">–</span></div>
+    <div class="stat"><span class="label">Output</span><span class="value" id="sOut">–</span></div>
+    <div class="stat"><span class="label">Cache read</span><span class="value" id="sRead">–</span></div>
+    <div class="stat"><span class="label">Cache write</span><span class="value" id="sWrite">–</span></div>
+  </div>
+  <div id="graph"><div id="spinner"><span></span></div></div>
+  <div id="glow"></div>
+  <script>
+    const $ = (id) => document.getElementById(id);
+    const fmt = (n) => n == null ? "–" : n >= 1e6 ? (n/1e6).toFixed(1)+"M" : n >= 1e3 ? (n/1e3).toFixed(1)+"k" : n;
+
+    const sessionSelect = $("sessionSelect");
+    const spinner = $("spinner");
+    const container = $("graph");
+    let current = null;   // { session, aggregate, chronological, toolAggregates }
+    let view = "aggregate";
+    let network = null;
+
+    const glow = document.getElementById("glow");
+    const root = document.documentElement;
+    container.addEventListener("mousemove", (e) => {
+      root.style.setProperty("--gx", e.clientX + "px");
+      root.style.setProperty("--gy", e.clientY + "px");
+      glow.classList.add("on");
+    });
+    container.addEventListener("mouseleave", () => glow.classList.remove("on"));
+
+    const options = {
+      physics: { enabled: true, solver: "forceAtlas2Based", stabilization: { iterations: 200 } },
+      interaction: { hover: true, tooltipDelay: 200 },
+      nodes: { shape: "dot", font: { color: "#cccccc", size: 13 }, widthConstraint: { maximum: 140 } },
+      edges: { color: { color: "#3a3a3a", highlight: "#faff69" }, smooth: { enabled: true, type: "dynamic" } },
+    };
+
+    function render() {
+      if (!current) return;
+      const data = view === "aggregate" ? current.aggregate : current.chronological;
+      if (network) network.destroy();
+      network = new vis.Network(container, { nodes: new vis.DataSet(data.nodes), edges: new vis.DataSet(data.edges) }, options);
+    }
+
+    function showEmpty(title, body) {
+      if (network) network.destroy();
+      network = null;
+      container.innerHTML = '<div class="empty">' + (title ? "<h2></h2><p></p>" : "") + '</div><div id="spinner"><span></span></div>';
+      if (title) { container.querySelector("h2").textContent = title; container.querySelector("p").textContent = body; }
+      // reattach glow/spinner refs are fixed; spinner is a child now
+      spinner.classList.remove("on");
+    }
+
+    function fillStats(s) {
+      $("sModel").textContent = s.model;
+      $("sTurns").textContent = s.turns;
+      $("sCalls").textContent = s.toolCalls;
+      $("sTotal").textContent = fmt(s.totalTokens);
+      $("sIn").textContent = fmt(s.totalInput);
+      $("sOut").textContent = fmt(s.totalOutput);
+      $("sRead").textContent = fmt(s.totalCacheRead);
+      $("sWrite").textContent = fmt(s.totalCacheWrite);
+    }
+
+    async function loadSession(slug, id) {
+      spinner.classList.add("on");
+      try {
+        const r = await fetch("/api/session/" + encodeURIComponent(slug) + "/" + encodeURIComponent(id));
+        if (!r.ok) throw new Error("no data");
+        current = await r.json();
+        fillStats(current.session);
+        spinner.classList.remove("on");
+        render();
+      } catch (e) {
+        spinner.classList.remove("on");
+        showEmpty("Could not load session", "The server couldn't parse this session file. It may be malformed or the API returned no data.");
+      }
+    }
+
+    async function loadSessions() {
+      spinner.classList.add("on");
+      try {
+        const r = await fetch("/api/sessions");
+        const data = await r.json();
+        spinner.classList.remove("on");
+        if (!data.sessions || data.sessions.length === 0) {
+          showEmpty("No Claude Code sessions found",
+            "Graphtrack reads session logs from " + data.logsDir + ". Run Claude Code a few times, then restart with:  graphtrack --dir <path>  if your logs live elsewhere.");
+          return;
+        }
+        sessionSelect.disabled = false;
+        sessionSelect.innerHTML = "";
+        data.sessions.forEach((s) => {
+          const opt = document.createElement("option");
+          opt.value = s.id;
+          opt.dataset.slug = s.project;
+          opt.textContent = s.project + " · " + s.id;
+          sessionSelect.appendChild(opt);
+        });
+        const first = data.sessions[0];
+        loadSession(first.project, first.id);
+      } catch (e) {
+        spinner.classList.remove("on");
+        showEmpty("Can't reach the Graphtrack server",
+          "Start it with:  graphtrack   — this page must be served from http://localhost:9090.");
+      }
+    }
+
+    sessionSelect.addEventListener("change", () => {
+      const opt = sessionSelect.selectedOptions[0];
+      if (opt) loadSession(opt.dataset.slug, opt.value);
+    });
+    $("btnAgg").addEventListener("click", () => { view = "aggregate"; setActive("btnAgg"); render(); });
+    $("btnChain").addEventListener("click", () => { view = "chronological"; setActive("btnChain"); render(); });
+    function setActive(id) { $("btnAgg").classList.toggle("active", id==="btnAgg"); $("btnChain").classList.toggle("active", id==="btnChain"); }
+
+    loadSessions();
+  </script>
+</body>
+</html>