copilot-tracer 1.0.7 → 1.0.9

package/README.md

@@ -32,7 +32,9 @@ This will:
 2. Patch `~/.zshrc` with OTEL env vars
 3. Patch VS Code `settings.json` with terminal env vars
 4. Enable Claude Code OTLP logs/events and enhanced beta traces
-5. Start the daemon on port 4747
+5. Install Claude Code hooks into `~/.claude/settings.json` (merged with any hooks you
+   already have — nothing is overwritten)
+6. Start the daemon on port 4747
 
 Then apply env vars in your current shell:
 
@@ -40,9 +42,10 @@ Then apply env vars in your current shell:
 source ~/.zshrc
 ```
 
-Restart VS Code once. After that, the daemon collects traces from all your Copilot
-and Claude Code sessions automatically. Claude Code content flags are enabled by
-setup so prompts and responses can be displayed in the local dashboard.
+Restart VS Code once, and restart Claude Code to pick up the hooks. After that, the
+daemon collects traces from all your Copilot and Claude Code sessions automatically.
+Claude Code content flags are enabled by setup so prompts and responses can be
+displayed in the local dashboard.
 
 Open **http://localhost:4747** to see the dashboard.
 
@@ -196,6 +199,45 @@ Claude Code exports standard OTLP logs/events and optional beta traces. See
 [Anthropic's monitoring documentation](https://code.claude.com/docs/en/monitoring-usage)
 for protocol and content controls.
 
+### Claude Code hooks (required for full session capture)
+
+Telemetry alone can't reconstruct a multi-prompt Claude session: its log events are
+correlated by `prompt.id` while its spans are correlated by OTLP `traceId`, and neither
+key is always present. The result is turns with no token usage that never leave the
+`running` state.
+
+So the tracer also registers [hooks](https://code.claude.com/docs/en/hooks), which give
+it an ordered, complete lifecycle — every prompt, every tool call, every turn boundary.
+The two halves join on `prompt_id`, which Claude documents as matching the OTLP
+`prompt.id` attribute:
+
+- **Hooks** own the turn and tool lifecycle.
+- **OTLP** enriches those turns with tokens, model and cost.
+
+`copilot-tracer --setup` writes this for you. To add it by hand, merge the following into
+`~/.claude/settings.json` (keep any hooks you already have — Claude runs all of them):
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "http", "url": "http://localhost:4747/claude/hook", "timeout": 5 }] }
+    ]
+  }
+}
+```
+
+Setup subscribes to `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
+`PostToolUseFailure`, `Stop`, `StopFailure` and `SessionEnd` using the same handler.
+
+The receiver always answers `204 No Content`, which the hooks spec defines as "no
+decision", so it can never block a tool call, deny a permission, or stop a turn. If the
+daemon isn't running, Claude treats the connection failure as a non-blocking error and
+your session continues normally.
+
+If hooks are unavailable (older Claude Code, `disableAllHooks`, remote sessions), the
+tracer falls back to its original OTLP-only handling.
+
 For VS Code, add to `~/Library/Application Support/Code/User/settings.json`:
 
 ```json

package/dist/claudeHooks.js

@@ -0,0 +1,145 @@
+/**
+ * Claude Code hook receiver.
+ *
+ * Claude Code posts each lifecycle event here as a native `type: "http"` hook, giving
+ * the tracer an ordered, complete view of a session: every prompt, every tool call, and
+ * every turn boundary — the things OTLP alone can't correlate reliably across a
+ * multi-prompt session.
+ *
+ * Safety contract (this runs inside the user's Claude session, so it must never interfere):
+ *   - Always answer 204 No Content. Per the hooks spec a 2xx with an empty body means
+ *     "no decision", so the tracer can never block a tool call, deny a permission, or
+ *     stop a turn — even if the handler hits an unexpected payload.
+ *   - Never throw. Any error is swallowed and logged; the session continues.
+ *   - Do no blocking work. Everything here is in-memory plus one SQLite upsert.
+ */
+import { startTurn, finishTurn, startToolCall, finishToolCall, endSession, registerSession, } from './claudeSession.js';
+import { ensureProject } from './db.js';
+function str(value) {
+    if (typeof value === 'string' && value.trim())
+        return value;
+    return undefined;
+}
+function errorText(payload) {
+    const raw = payload.tool_error ?? payload.error;
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw === 'string')
+        return raw || undefined;
+    try {
+        return JSON.stringify(raw);
+    }
+    catch {
+        return String(raw);
+    }
+}
+/**
+ * Claude reports the working directory it's actually in (worktree-aware), which is the
+ * best project signal available from a hook. Falls back to no project — traces still
+ * show up on the live page.
+ */
+function resolveProject(cwd) {
+    if (!cwd)
+        return undefined;
+    try {
+        return ensureProject(cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function handleClaudeHook(payload) {
+    const event = str(payload.hook_event_name);
+    const sessionId = str(payload.session_id);
+    if (!event || !sessionId)
+        return;
+    const promptId = str(payload.prompt_id);
+    const projectId = resolveProject(str(payload.cwd));
+    const toolName = str(payload.tool_name) ?? 'Claude Code tool';
+    switch (event) {
+        case 'SessionStart':
+            registerSession(sessionId, projectId);
+            return;
+        case 'UserPromptSubmit':
+            startTurn({
+                sessionId,
+                promptId,
+                prompt: str(payload.prompt) ?? '[Claude Code prompt]',
+                projectId,
+            });
+            return;
+        case 'PreToolUse':
+            startToolCall({
+                sessionId,
+                promptId,
+                toolUseId: str(payload.tool_use_id),
+                name: toolName,
+                toolInput: payload.tool_input,
+                projectId,
+            });
+            return;
+        case 'PostToolUse':
+        case 'PostToolUseFailure':
+            finishToolCall({
+                sessionId,
+                promptId,
+                toolUseId: str(payload.tool_use_id),
+                name: toolName,
+                toolInput: payload.tool_input,
+                output: payload.tool_response,
+                error: event === 'PostToolUseFailure' ? (errorText(payload) ?? 'tool failed') : errorText(payload),
+                projectId,
+            });
+            return;
+        case 'Stop':
+        case 'SubagentStop':
+            finishTurn({
+                sessionId,
+                promptId,
+                response: str(payload.last_assistant_message),
+            });
+            return;
+        case 'StopFailure':
+            finishTurn({
+                sessionId,
+                promptId,
+                error: errorText(payload) ?? str(payload.reason) ?? 'Claude Code turn failed',
+            });
+            return;
+        case 'SessionEnd':
+            endSession(sessionId);
+            return;
+        default:
+            // Unknown or unsubscribed event — ignore rather than guess.
+            return;
+    }
+}
+export function registerClaudeHookRoutes(app) {
+    // Claude Code posts every subscribed lifecycle event here.
+    app.post('/claude/hook', (req, res) => {
+        try {
+            handleClaudeHook((req.body ?? {}));
+        }
+        catch (err) {
+            console.error('[claude-hook] failed to process event:', err);
+        }
+        // 204 = 2xx with empty body = "no decision". Never influence the session.
+        res.status(204).end();
+    });
+    // Lets `--setup` and users confirm the receiver is reachable.
+    app.get('/claude/hook/health', (_req, res) => {
+        res.json({ ok: true, receiver: 'claude-hooks' });
+    });
+    // A malformed or oversized body fails inside the express.json() middleware, before the
+    // route above ever runs, and would otherwise surface to Claude as a 4xx — a non-2xx
+    // response is a hook error. Convert it back into "no decision" so a bad payload can
+    // still never affect the user's session.
+    app.use((err, req, res, next) => {
+        if (!req.path.startsWith('/claude/hook'))
+            return next(err);
+        console.error('[claude-hook] rejected malformed request:', err);
+        if (res.headersSent)
+            return;
+        res.status(204).end();
+    });
+}

package/dist/claudePricing.js

@@ -0,0 +1,31 @@
+/**
+ * Anthropic token pricing, shared by the OTLP receiver and the Claude hook tracker.
+ *
+ * Lives in its own module so `claudeSession.ts` and `otlpReceiver.ts` can both use it
+ * without importing each other (they reference each other in the hybrid hook+OTLP flow).
+ */
+// Anthropic API pricing per 1K tokens (USD), converted to GitHub "AI credit" units
+// (1 credit = $0.01) so aiCredits stays one unit across Copilot and Claude entries.
+// Rates are Anthropic's current published per-model prices; a model id that doesn't
+// match a specific entry falls back to its tier's (opus/sonnet/haiku) latest rate.
+const ANTHROPIC_USD_PER_1K = {
+    'claude-fable-5': { input: 0.010, output: 0.050 },
+    'claude-mythos-5': { input: 0.010, output: 0.050 },
+    'claude-opus-5': { input: 0.005, output: 0.025 },
+    'claude-opus-4-8': { input: 0.005, output: 0.025 },
+    'claude-opus-4-7': { input: 0.005, output: 0.025 },
+    'claude-opus-4-6': { input: 0.005, output: 0.025 },
+    'claude-sonnet-5': { input: 0.002, output: 0.010 },
+    'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
+    'claude-haiku-4-5': { input: 0.001, output: 0.005 },
+    'opus': { input: 0.005, output: 0.025 },
+    'sonnet': { input: 0.003, output: 0.015 },
+    'haiku': { input: 0.001, output: 0.005 },
+    'default': { input: 0.003, output: 0.015 },
+};
+export function calcClaudeCredits(tokens, model) {
+    const key = Object.keys(ANTHROPIC_USD_PER_1K).find(k => (model ?? '').toLowerCase().includes(k)) ?? 'default';
+    const rate = ANTHROPIC_USD_PER_1K[key];
+    const usd = (tokens.input / 1000) * rate.input + (tokens.output / 1000) * rate.output;
+    return usd * 100; // USD → credits (1 credit = $0.01)
+}

package/dist/claudeSession.js

@@ -0,0 +1,405 @@
+/**
+ * Claude Code session tracker — the "hook" half of the hybrid tracing design.
+ *
+ * Why this exists
+ * ---------------
+ * Claude Code's OTLP stream alone can't reliably reconstruct a multi-prompt session.
+ * Its log events are correlated by `prompt.id` while its spans are correlated by OTLP
+ * `traceId`, and neither key is guaranteed to be present, so turns after the first one
+ * would routinely lose their tool calls or land on a duplicate entry.
+ *
+ * Claude Code hooks give us a deterministic, ordered lifecycle instead:
+ *   UserPromptSubmit → PreToolUse* / PostToolUse* → Stop
+ * and every hook payload carries `session_id` plus `prompt_id`, where `prompt_id` is
+ * documented to match the OTLP `prompt.id` attribute. That shared key is what lets the
+ * two halves join up.
+ *
+ * Division of responsibility:
+ *   - Hooks own the turn/tool *lifecycle* (what happened, in what order, on which turn).
+ *   - OTLP owns *enrichment* (tokens, model, cost), applied onto the hook-created turn.
+ *
+ * When hooks aren't configured the OTLP receiver keeps its original standalone behaviour,
+ * so this module degrades to a no-op rather than breaking existing users.
+ */
+import { randomUUID } from 'crypto';
+import { upsertTrace, createSession } from './db.js';
+import { traceEvents } from './proxy.js';
+import { calcClaudeCredits } from './claudePricing.js';
+// ── Bounded state ─────────────────────────────────────────────────────────────
+// A long-lived daemon sees unbounded sessions, so every map is FIFO-capped.
+const ACTIVE_LIMIT = 200; // concurrent Claude sessions we track turns for
+const HISTORY_LIMIT = 2000; // finished turns retained for late OTLP enrichment
+const PENDING_LIMIT = 2000; // buffered usage waiting for its turn to appear
+const PENDING_TTL_MS = 10 * 60 * 1000;
+/** sessionId → the turn currently open for that session */
+const activeBySession = new Map();
+/** promptId → turn (open or closed). The join key shared with OTLP's `prompt.id`. */
+const turnsByPromptId = new Map();
+/** sessionId → most recently closed turn, so usage arriving after Stop still lands */
+const lastClosedBySession = new Map();
+/** buffered usage for turns that haven't been created yet, keyed `p:<promptId>`/`s:<sessionId>` */
+const pendingUsage = new Map();
+/**
+ * Sessions that have produced at least one hook event — enables hook-authoritative mode.
+ * A Map (not a Set) so it can be FIFO-capped: real sessions frequently end without a
+ * SessionEnd hook (crash, kill, machine sleep), and this daemon runs for weeks.
+ */
+const hookSessions = new Map();
+function capped(map, limit) {
+    while (map.size > limit) {
+        const oldest = map.keys().next().value;
+        if (oldest === undefined)
+            return;
+        map.delete(oldest);
+    }
+}
+function emptyTokens() {
+    return { input: 0, output: 0, cached: 0, reasoning: 0, written: 0, total: 0 };
+}
+// ── Tool classification ───────────────────────────────────────────────────────
+// Claude's tool vocabulary differs from Copilot's, so it gets its own classifier
+// rather than reusing the Copilot heuristics (which would mislabel `Task`/`Skill`).
+export function detectClaudeToolType(name) {
+    const n = name.toLowerCase();
+    if (n.startsWith('mcp__') || n.startsWith('mcp_'))
+        return 'mcp';
+    if (n === 'task' || n === 'agent' || n.includes('subagent'))
+        return 'agent';
+    if (n === 'skill' || n.startsWith('skill__') || n.includes('skill'))
+        return 'skill';
+    return 'builtin';
+}
+function recount(entry) {
+    entry.skillCount = entry.toolCalls.filter(c => c.type === 'skill').length;
+    entry.agentCount = entry.toolCalls.filter(c => c.type === 'agent').length;
+    entry.mcpCount = entry.toolCalls.filter(c => c.type === 'mcp').length;
+}
+function persist(ctx, done = false) {
+    recount(ctx.entry);
+    upsertTrace(ctx.entry);
+    traceEvents.emit('trace:update', ctx.entry);
+    if (done)
+        traceEvents.emit('trace:done', ctx.entry);
+}
+// ── Pending-usage buffering ───────────────────────────────────────────────────
+function pendingKeys(sessionId, promptId) {
+    const keys = [];
+    if (promptId)
+        keys.push(`p:${promptId}`);
+    if (sessionId)
+        keys.push(`s:${sessionId}`);
+    return keys;
+}
+function bufferUsage(delta, sessionId, promptId) {
+    const key = pendingKeys(sessionId, promptId)[0];
+    if (!key)
+        return;
+    const existing = pendingUsage.get(key);
+    if (existing) {
+        mergeDelta(existing.delta, delta);
+        existing.at = Date.now();
+    }
+    else {
+        pendingUsage.set(key, { delta: { ...delta }, at: Date.now() });
+    }
+    expirePending();
+    capped(pendingUsage, PENDING_LIMIT);
+}
+function mergeDelta(target, extra) {
+    target.input = (target.input ?? 0) + (extra.input ?? 0);
+    target.output = (target.output ?? 0) + (extra.output ?? 0);
+    target.cached = (target.cached ?? 0) + (extra.cached ?? 0);
+    target.reasoning = (target.reasoning ?? 0) + (extra.reasoning ?? 0);
+    target.written = (target.written ?? 0) + (extra.written ?? 0);
+    target.credits = (target.credits ?? 0) + (extra.credits ?? 0);
+    target.model = extra.model ?? target.model;
+}
+function expirePending() {
+    const cutoff = Date.now() - PENDING_TTL_MS;
+    for (const [key, value] of pendingUsage) {
+        if (value.at < cutoff)
+            pendingUsage.delete(key);
+    }
+}
+function drainPending(ctx) {
+    const keys = [`p:${ctx.promptId ?? ''}`];
+    // Session-keyed usage is only ever buffered when the session had no turn at all, so
+    // it belongs to the session's first turn. Claiming it later would credit one turn's
+    // tokens to an unrelated, subsequent turn.
+    if (!lastClosedBySession.has(ctx.sessionId))
+        keys.push(`s:${ctx.sessionId}`);
+    for (const key of keys) {
+        if (key === 'p:')
+            continue;
+        const buffered = pendingUsage.get(key);
+        if (!buffered)
+            continue;
+        pendingUsage.delete(key);
+        addUsage(ctx, buffered.delta);
+    }
+}
+function addUsage(ctx, delta) {
+    const t = ctx.entry.tokens;
+    t.input += delta.input ?? 0;
+    t.output += delta.output ?? 0;
+    t.cached += delta.cached ?? 0;
+    t.reasoning += delta.reasoning ?? 0;
+    t.written += delta.written ?? 0;
+    // Matches the rest of the codebase (proxy.ts, the OTLP fallback path): `written` and
+    // `cached` are reporting breakdowns of the same traffic, so summing them into `total`
+    // would double-count output tokens.
+    t.total = t.input + t.output;
+    if (delta.model)
+        ctx.model = delta.model;
+    ctx.entry.aiCredits += delta.credits
+        ?? calcClaudeCredits({ input: delta.input ?? 0, output: delta.output ?? 0 }, delta.model ?? ctx.model);
+}
+// ── Turn lookup ───────────────────────────────────────────────────────────────
+/**
+ * Resolve the turn an OTLP event belongs to. Prefers the exact `prompt.id` join,
+ * then the session's open turn, then the session's most recently closed turn
+ * (usage spans routinely arrive just after Stop).
+ */
+export function findClaudeTurn(sessionId, promptId) {
+    if (promptId) {
+        const byPrompt = turnsByPromptId.get(promptId);
+        if (byPrompt)
+            return byPrompt;
+    }
+    if (sessionId) {
+        return activeBySession.get(sessionId) ?? lastClosedBySession.get(sessionId);
+    }
+    return undefined;
+}
+/** True when hooks have reported activity for this session, so hooks own its lifecycle. */
+export function isHookTracked(sessionId) {
+    return !!sessionId && hookSessions.has(sessionId);
+}
+function markHookSession(sessionId) {
+    // Re-insert so the most recently active sessions are evicted last.
+    hookSessions.delete(sessionId);
+    hookSessions.set(sessionId, Date.now());
+    capped(hookSessions, ACTIVE_LIMIT);
+}
+// ── Lifecycle: turns ──────────────────────────────────────────────────────────
+export function startTurn(input) {
+    const { sessionId, promptId, projectId } = input;
+    markHookSession(sessionId);
+    // Claude re-fires UserPromptSubmit for the same prompt_id (retries, resubmits). Reuse
+    // that turn. This must be checked BEFORE closing the stale turn below, since the two
+    // are frequently the same context — closing it first would force a duplicate trace.
+    const existing = promptId ? turnsByPromptId.get(promptId) : undefined;
+    if (existing && !existing.closed) {
+        existing.entry.prompt = input.prompt || existing.entry.prompt;
+        activeBySession.set(sessionId, existing);
+        persist(existing);
+        return existing;
+    }
+    // A different turn that never received Stop (crash, /clear, interrupt) would otherwise
+    // sit at status 'running' forever and swallow this turn's tool calls.
+    const stale = activeBySession.get(sessionId);
+    if (stale && stale !== existing && !stale.closed)
+        closeTurn(stale, { status: 'done' });
+    const startedAtMs = Date.now();
+    const entry = {
+        id: `claude:turn:${promptId ?? randomUUID()}`,
+        sessionId,
+        dateTime: input.dateTime ?? new Date(startedAtMs).toISOString(),
+        prompt: input.prompt || '[Claude Code prompt]',
+        tokens: emptyTokens(),
+        aiCredits: 0,
+        durationMs: 0,
+        toolCalls: [],
+        skillCount: 0,
+        agentCount: 0,
+        mcpCount: 0,
+        status: 'running',
+    };
+    const ctx = {
+        entry,
+        tools: new Map(),
+        sessionId,
+        promptId,
+        startedAtMs,
+        closed: false,
+    };
+    activeBySession.set(sessionId, ctx);
+    capped(activeBySession, ACTIVE_LIMIT);
+    if (promptId) {
+        turnsByPromptId.set(promptId, ctx);
+        capped(turnsByPromptId, HISTORY_LIMIT);
+    }
+    createSession(sessionId, projectId);
+    drainPending(ctx);
+    persist(ctx);
+    return ctx;
+}
+function closeTurn(ctx, opts) {
+    if (!ctx.closed) {
+        ctx.entry.durationMs = ctx.entry.durationMs || Date.now() - ctx.startedAtMs;
+        ctx.closed = true;
+    }
+    if (opts.response)
+        ctx.entry.response = opts.response;
+    if (opts.error)
+        ctx.entry.error = opts.error;
+    // A turn can be closed twice: the Stop hook fires, then the OTLP assistant_response
+    // event arrives to backfill the text. The second call must not downgrade a failure
+    // (StopFailure) back to 'done'.
+    if (opts.error) {
+        ctx.entry.status = 'error';
+    }
+    else if (ctx.entry.status !== 'error') {
+        ctx.entry.status = opts.status ?? 'done';
+    }
+    // Any tool still open at turn end never got its PostToolUse (denied, interrupted,
+    // or the session ended mid-call). Close it out rather than leaving it dangling.
+    for (const call of ctx.entry.toolCalls) {
+        if (call.endedAt === undefined) {
+            call.endedAt = Date.now();
+            call.durationMs = call.endedAt - call.startedAt;
+            call.error = call.error ?? 'incomplete (no PostToolUse received)';
+        }
+    }
+    if (activeBySession.get(ctx.sessionId) === ctx)
+        activeBySession.delete(ctx.sessionId);
+    lastClosedBySession.set(ctx.sessionId, ctx);
+    capped(lastClosedBySession, ACTIVE_LIMIT);
+    persist(ctx, true);
+}
+export function finishTurn(input) {
+    const ctx = findClaudeTurn(input.sessionId, input.promptId);
+    if (!ctx)
+        return;
+    markHookSession(input.sessionId);
+    closeTurn(ctx, { response: input.response, error: input.error });
+}
+export function endSession(sessionId) {
+    const ctx = activeBySession.get(sessionId);
+    if (ctx && !ctx.closed)
+        closeTurn(ctx, { status: 'done' });
+    activeBySession.delete(sessionId);
+    hookSessions.delete(sessionId);
+}
+export function registerSession(sessionId, projectId) {
+    markHookSession(sessionId);
+    createSession(sessionId, projectId);
+}
+// ── Lifecycle: tool calls ─────────────────────────────────────────────────────
+/**
+ * Pre/Post hook pairs share `tool_use_id` on recent Claude Code versions. Older
+ * versions omit it, so fall back to a stable key derived from name + input.
+ */
+function toolKey(toolUseId, name, input) {
+    if (toolUseId)
+        return toolUseId;
+    let serialized = '';
+    try {
+        serialized = JSON.stringify(input ?? {});
+    }
+    catch {
+        serialized = String(input);
+    }
+    return `${name}:${serialized.slice(0, 512)}`;
+}
+/**
+ * Attach a tool call to the session's open turn. If no turn exists (hooks enabled
+ * mid-session, or a subagent session whose UserPromptSubmit we never saw) an implicit
+ * turn is created so the call is recorded rather than silently dropped.
+ */
+function turnForTool(sessionId, promptId, projectId) {
+    // A tool event carrying a prompt_id belongs to that prompt's turn, full stop — even if
+    // the turn already closed. Falling back to the session's *current* turn here would file
+    // a straggling PostToolUse from the previous prompt onto the next prompt's trace.
+    const existing = promptId ? turnsByPromptId.get(promptId) : undefined;
+    if (existing)
+        return existing;
+    const active = activeBySession.get(sessionId);
+    if (active && !active.closed)
+        return active;
+    return startTurn({ sessionId, promptId, prompt: '[Claude Code turn]', projectId });
+}
+export function startToolCall(input) {
+    markHookSession(input.sessionId);
+    const ctx = turnForTool(input.sessionId, input.promptId, input.projectId);
+    const key = toolKey(input.toolUseId, input.name, input.toolInput);
+    const previous = ctx.tools.get(key);
+    // Without a tool_use_id the key is only name+input, so a repeat of an identical call
+    // collides with the earlier one. Skip only while that earlier call is still open (a
+    // genuine duplicate PreToolUse); once it has completed, this is a new call.
+    if (previous && previous.endedAt === undefined)
+        return;
+    const call = {
+        id: input.toolUseId ?? randomUUID(),
+        name: input.name,
+        type: detectClaudeToolType(input.name),
+        input: input.toolInput ?? {},
+        startedAt: Date.now(),
+    };
+    ctx.tools.set(key, call);
+    ctx.entry.toolCalls.push(call);
+    persist(ctx);
+}
+export function finishToolCall(input) {
+    markHookSession(input.sessionId);
+    const ctx = turnForTool(input.sessionId, input.promptId, input.projectId);
+    const key = toolKey(input.toolUseId, input.name, input.toolInput);
+    let call = ctx.tools.get(key);
+    if (!call) {
+        // PostToolUse without a matching PreToolUse (hook added mid-call, or matcher
+        // mismatch). Record it as a zero-duration call so the tool isn't lost.
+        call = {
+            id: input.toolUseId ?? randomUUID(),
+            name: input.name,
+            type: detectClaudeToolType(input.name),
+            input: input.toolInput ?? {},
+            startedAt: Date.now(),
+        };
+        ctx.tools.set(key, call);
+        ctx.entry.toolCalls.push(call);
+    }
+    call.endedAt = Date.now();
+    call.durationMs = call.endedAt - call.startedAt;
+    if (input.output !== undefined)
+        call.output = input.output;
+    if (input.error)
+        call.error = input.error;
+    persist(ctx);
+}
+// ── Enrichment from OTLP ──────────────────────────────────────────────────────
+/**
+ * Apply token/model/cost usage reported over OTLP onto the matching hook turn.
+ * Returns false when no turn matched — the usage is buffered, and the caller may
+ * fall back to its own standalone handling.
+ */
+export function applyClaudeUsage(input) {
+    const ctx = findClaudeTurn(input.sessionId, input.promptId);
+    if (!ctx) {
+        bufferUsage(input.delta, input.sessionId, input.promptId);
+        return false;
+    }
+    addUsage(ctx, input.delta);
+    persist(ctx);
+    return true;
+}
+/** Fill in prompt/response text discovered over OTLP without clobbering hook data. */
+export function enrichClaudeContent(input) {
+    const ctx = findClaudeTurn(input.sessionId, input.promptId);
+    if (!ctx)
+        return false;
+    const placeholder = /^\[Claude Code (prompt|turn)\]$/;
+    if (input.prompt && placeholder.test(ctx.entry.prompt))
+        ctx.entry.prompt = input.prompt;
+    if (input.response && !ctx.entry.response)
+        ctx.entry.response = input.response;
+    persist(ctx);
+    return true;
+}
+/** Test-only: drop all in-memory state. */
+export function resetClaudeTracker() {
+    activeBySession.clear();
+    turnsByPromptId.clear();
+    lastClosedBySession.clear();
+    pendingUsage.clear();
+    hookSessions.clear();
+}

package/dist/cli.js

@@ -11,6 +11,7 @@ import { renderConsoleTable } from './consoleUi.js';
 import { startWebServer } from './webServer.js';
 import { runSetup } from './setup.js';
 import open from 'open';
+import os from 'os';
 program
     .name('copilot-tracer')
     .description('Real-time monitor and tracer for GitHub Copilot CLI')
@@ -30,7 +31,41 @@ const port = parseInt(opts.port);
 // Handle --setup: patch env files, apply to current process, then fall through to start web UI
 if (opts.setup) {
     runSetup(port, opts.daemon);
-    if (!opts.daemon) {
+    if (opts.daemon) {
+        // Relaunch as a detached background daemon so the terminal doesn't need to stay open.
+        const dir = path.join(os.homedir(), '.copilot-tracer');
+        fs.mkdirSync(dir, { recursive: true });
+        const pidFile = path.join(dir, 'daemon.pid');
+        const existingPid = fs.existsSync(pidFile) ? parseInt(fs.readFileSync(pidFile, 'utf8'), 10) : NaN;
+        const alreadyRunning = !isNaN(existingPid) && (() => {
+            try {
+                process.kill(existingPid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (alreadyRunning) {
+            console.log(`\n  🤖 Daemon already running (pid ${existingPid})`);
+            console.log(`  🌐 Dashboard: http://localhost:${port}/\n`);
+        }
+        else {
+            const logFile = fs.openSync(path.join(dir, 'daemon.log'), 'a');
+            const child = spawn(process.execPath, [process.argv[1], '--daemon', '--port', String(port)], {
+                detached: true,
+                stdio: ['ignore', logFile, logFile],
+            });
+            child.unref();
+            fs.writeFileSync(pidFile, String(child.pid));
+            console.log(`\n  🤖 Daemon started in background (pid ${child.pid})`);
+            console.log(`  🌐 Dashboard: http://localhost:${port}/`);
+            console.log(`  📄 Logs: ${path.join(dir, 'daemon.log')}`);
+            console.log(`  Stop it with: kill ${child.pid}\n`);
+        }
+        process.exit(0);
+    }
+    else {
         opts.proxy = false;
         opts.ui = 'web';
     }

package/dist/db.js

@@ -2,7 +2,9 @@ import Database from 'better-sqlite3';
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
-const DB_DIR = path.join(os.homedir(), '.copilot-tracer');
+// Overridable so a verification run can point at a throwaway database instead of
+// polluting the user's real trace history.
+const DB_DIR = process.env.COPILOT_TRACER_HOME ?? path.join(os.homedir(), '.copilot-tracer');
 const DB_PATH = path.join(DB_DIR, 'traces.db');
 if (!fs.existsSync(DB_DIR))
     fs.mkdirSync(DB_DIR, { recursive: true });
@@ -103,7 +105,12 @@ export function createSession(id, projectId) {
       END
   `).run(id, new Date().toISOString(), projectId ?? null);
 }
-export function getDashboard() {
+export function getDashboard(page = 1, pageSize = 12) {
+    const projectCount = db.prepare('SELECT COUNT(*) as count FROM projects').get();
+    const totalProjects = projectCount.count;
+    const totalPages = Math.max(1, Math.ceil(totalProjects / pageSize));
+    const currentPage = Math.min(page, totalPages);
+    const offset = (currentPage - 1) * pageSize;
     const projects = db.prepare(`
     SELECT
       p.id, p.path, p.repo_url, p.local_path,
@@ -115,8 +122,9 @@ export function getDashboard() {
     LEFT JOIN sessions s ON s.project_id = p.id
     LEFT JOIN traces t ON t.session_id = s.id
     GROUP BY p.id
-    ORDER BY last_active_at DESC
-  `).all();
+    ORDER BY last_active_at DESC, p.id ASC
+    LIMIT ? OFFSET ?
+  `).all(pageSize, offset);
     const totals = db.prepare(`
     SELECT
       (SELECT COUNT(*) FROM projects) as projects,
@@ -154,6 +162,12 @@ export function getDashboard() {
             tokens: totals.tokens,
             credits: totals.credits,
         },
+        pagination: {
+            page: currentPage,
+            pageSize,
+            totalPages,
+            totalProjects,
+        },
     };
 }
 export function upsertTrace(entry) {

package/dist/otlpReceiver.js

@@ -17,6 +17,8 @@
 import { randomUUID } from 'crypto';
 import { upsertTrace, createSession, deleteTrace, ensureProject, ensureProjectByRepo } from './db.js';
 import { traceEvents } from './proxy.js';
+import { calcClaudeCredits } from './claudePricing.js';
+import { applyClaudeUsage, enrichClaudeContent, finishTurn, isHookTracked } from './claudeSession.js';
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function getAttr(attrs, key) {
     const kv = attrs?.find(a => a.key === key);
@@ -59,31 +61,7 @@ function getBodyText(body) {
     return undefined;
 }
 const inFlight = new Map(); // traceId → InFlight
-// Anthropic API pricing per 1K tokens (USD), converted to GitHub "AI credit" units
-// (1 credit = $0.01) so aiCredits stays one unit across Copilot and Claude entries.
-// Rates are Anthropic's current published per-model prices; a model id that doesn't
-// match a specific entry falls back to its tier's (opus/sonnet/haiku) latest rate.
-const ANTHROPIC_USD_PER_1K = {
-    'claude-fable-5': { input: 0.010, output: 0.050 },
-    'claude-mythos-5': { input: 0.010, output: 0.050 },
-    'claude-opus-5': { input: 0.005, output: 0.025 },
-    'claude-opus-4-8': { input: 0.005, output: 0.025 },
-    'claude-opus-4-7': { input: 0.005, output: 0.025 },
-    'claude-opus-4-6': { input: 0.005, output: 0.025 },
-    'claude-sonnet-5': { input: 0.002, output: 0.010 },
-    'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
-    'claude-haiku-4-5': { input: 0.001, output: 0.005 },
-    'opus': { input: 0.005, output: 0.025 },
-    'sonnet': { input: 0.003, output: 0.015 },
-    'haiku': { input: 0.001, output: 0.005 },
-    'default': { input: 0.003, output: 0.015 },
-};
-export function calcClaudeCredits(tokens, model) {
-    const key = Object.keys(ANTHROPIC_USD_PER_1K).find(k => (model ?? '').toLowerCase().includes(k)) ?? 'default';
-    const rate = ANTHROPIC_USD_PER_1K[key];
-    const usd = (tokens.input / 1000) * rate.input + (tokens.output / 1000) * rate.output;
-    return usd * 100; // USD → credits (1 credit = $0.01)
-}
+export { calcClaudeCredits };
 // Sessions are created lazily. Always upsert so project_id gets backfilled
 // when the session was created earlier without a project.
 function ensureSession(sessionId, projectId) {
@@ -142,6 +120,27 @@ function processClaudeLogRecord(record, resourceAttrs, sessionId, projectId, wor
     const promptId = getStringAttr(attrs, 'prompt.id');
     const resolvedProjectId = resolveProjectId(getStringAttr(resourceAttrs, 'github.copilot.git.repository', 'vcs.repository.url'), getStringAttr(attrs, 'process.working_directory', 'github.copilot.working_dir', 'claude_code.working_dir') ?? workingDir, projectId);
     const eventSessionId = getStringAttr(attrs, 'session.id') ?? sessionId;
+    // ── Hook-authoritative path ────────────────────────────────────────────────
+    // When Claude Code hooks are reporting this session, they already own the turn and
+    // tool lifecycle (ordered, complete, and correlated by session_id + prompt_id). OTLP
+    // logs then only contribute content that hooks don't carry. Claiming the lifecycle
+    // here as well would duplicate every turn and tool call.
+    if (isHookTracked(eventSessionId)) {
+        if (eventName === 'claude_code.user_prompt') {
+            enrichClaudeContent({ sessionId: eventSessionId, promptId, prompt: getStringAttr(attrs, 'prompt') });
+            return;
+        }
+        if (eventName === 'claude_code.assistant_response') {
+            // The Stop hook normally closes the turn first; finishTurn is idempotent and
+            // backfills the response text either way.
+            finishTurn({ sessionId: eventSessionId, promptId, response: getStringAttr(attrs, 'response') });
+            return;
+        }
+        if (eventName === 'claude_code.tool_result') {
+            // Pre/PostToolUse already recorded this call with full input and real duration.
+            return;
+        }
+    }
     if (eventName === 'claude_code.user_prompt') {
         const entry = {
             id: claudeEventId(record, attrs, 'prompt'),
@@ -240,13 +239,43 @@ function processSpans(spans, sessionId, projectId, workingDir) {
             const attrs = span.attributes ?? [];
             const inputTokens = Number(getAttr(attrs, 'input_tokens') ?? 0);
             const outputTokens = Number(getAttr(attrs, 'output_tokens') ?? 0);
+            const cachedTokens = Number(getAttr(attrs, 'cache_read_tokens') ?? 0);
             const model = getStringAttr(attrs, 'model', 'gen_ai.request.model');
+            const claudeSessionId = getStringAttr(attrs, 'session.id') ?? sessionId;
+            const claudePromptId = getStringAttr(attrs, 'prompt.id');
+            // ── Hook-authoritative path ──────────────────────────────────────────
+            // Hooks already created the turn for this prompt, so the interaction span is
+            // pure enrichment: tokens, model and cost land on the existing entry instead
+            // of spawning a second, tool-less trace for the same turn.
+            if (isHookTracked(claudeSessionId)) {
+                const pendingDelta = pendingClaudeLlmDeltas.get(traceId);
+                if (pendingDelta)
+                    pendingClaudeLlmDeltas.delete(traceId);
+                applyClaudeUsage({
+                    sessionId: claudeSessionId,
+                    promptId: claudePromptId,
+                    delta: {
+                        input: inputTokens + (pendingDelta?.input ?? 0),
+                        output: outputTokens + (pendingDelta?.output ?? 0),
+                        cached: cachedTokens + (pendingDelta?.cached ?? 0),
+                        written: outputTokens + (pendingDelta?.output ?? 0),
+                        credits: calcClaudeCredits({ input: inputTokens, output: outputTokens }, model) + (pendingDelta?.credits ?? 0),
+                        model,
+                    },
+                });
+                enrichClaudeContent({
+                    sessionId: claudeSessionId,
+                    promptId: claudePromptId,
+                    prompt: getStringAttr(attrs, 'user_prompt'),
+                });
+                continue;
+            }
             const entry = {
                 id: spanId,
-                sessionId: getStringAttr(attrs, 'session.id') ?? sessionId,
+                sessionId: claudeSessionId,
                 dateTime: nanoToIso(span.startTimeUnixNano),
                 prompt: getStringAttr(attrs, 'user_prompt') ?? '[Claude Code interaction]',
-                tokens: { input: inputTokens, output: outputTokens, cached: Number(getAttr(attrs, 'cache_read_tokens') ?? 0), reasoning: 0, written: outputTokens, total: inputTokens + outputTokens },
+                tokens: { input: inputTokens, output: outputTokens, cached: cachedTokens, reasoning: 0, written: outputTokens, total: inputTokens + outputTokens },
                 aiCredits: calcClaudeCredits({ input: inputTokens, output: outputTokens }, model),
                 durationMs: Number(getAttr(attrs, 'interaction.duration_ms')
                     ?? (nanoToMs(span.endTimeUnixNano) - nanoToMs(span.startTimeUnixNano))),
@@ -283,6 +312,27 @@ function processSpans(spans, sessionId, projectId, workingDir) {
             const outputTokens = Number(getAttr(attrs, 'output_tokens') ?? 0);
             const cachedTokens = Number(getAttr(attrs, 'cache_read_tokens') ?? 0);
             const model = getStringAttr(attrs, 'model', 'gen_ai.request.model');
+            const claudeSessionId = getStringAttr(attrs, 'session.id') ?? sessionId;
+            const claudePromptId = getStringAttr(attrs, 'prompt.id');
+            // ── Hook-authoritative path ──────────────────────────────────────────
+            // Every iteration of Claude's agentic loop emits one of these spans. Keying on
+            // session_id + prompt_id (rather than the OTLP traceId) is what makes them
+            // accumulate onto the correct turn across a multi-prompt session.
+            if (isHookTracked(claudeSessionId)) {
+                applyClaudeUsage({
+                    sessionId: claudeSessionId,
+                    promptId: claudePromptId,
+                    delta: {
+                        input: inputTokens,
+                        output: outputTokens,
+                        cached: cachedTokens,
+                        written: outputTokens,
+                        credits: calcClaudeCredits({ input: inputTokens, output: outputTokens }, model),
+                        model,
+                    },
+                });
+                continue;
+            }
             const entry = claudeInteractionEntries.get(traceId);
             if (entry) {
                 entry.tokens = {

package/dist/setup.js

@@ -89,6 +89,119 @@ function vscodeEnvBlock(port) {
         [OTEL_LOG_RESPONSES_KEY]: '1',
     };
 }
+// ── Claude Code hooks ─────────────────────────────────────────────────────────
+// OTLP alone can't correlate a multi-prompt Claude session (its logs key on prompt.id,
+// its spans key on OTLP traceId, and neither is always present). Hooks give us the
+// ordered turn/tool lifecycle; OTLP still supplies the token/model/cost numbers.
+/** Events the tracer subscribes to, and which of them support a matcher. */
+const CLAUDE_HOOK_EVENTS = [
+    { event: 'SessionStart', matcher: undefined },
+    { event: 'UserPromptSubmit', matcher: undefined },
+    { event: 'PreToolUse', matcher: '.*' },
+    { event: 'PostToolUse', matcher: '.*' },
+    { event: 'PostToolUseFailure', matcher: '.*' },
+    { event: 'Stop', matcher: undefined },
+    { event: 'StopFailure', matcher: undefined },
+    { event: 'SessionEnd', matcher: undefined },
+];
+export function claudeHookUrl(port) {
+    return `http://localhost:${port}/claude/hook`;
+}
+function getClaudeSettingsPath() {
+    return path.join(os.homedir(), '.claude', 'settings.json');
+}
+/** Our handler is identified by its URL path so we can update the port in place. */
+function isTracerHandler(handler) {
+    return handler?.type === 'http' && typeof handler.url === 'string' && handler.url.includes('/claude/hook');
+}
+function tracerHandler(port) {
+    return {
+        type: 'http',
+        url: claudeHookUrl(port),
+        // Short timeout: a hook that stalls must never hold up the user's session. A
+        // timed-out http hook is cancelled and renders no decision, which is what we want.
+        timeout: 5,
+    };
+}
+/**
+ * Merge the tracer's hooks into Claude's settings.
+ *
+ * Merging (never replacing) is mandatory — users and plugins routinely register their
+ * own handlers on these same events, and clobbering them would silently break unrelated
+ * tooling. We only ever add, update, or leave alone our own `/claude/hook` handler.
+ */
+export function patchClaudeSettings(settingsPath, port) {
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        const raw = fs.readFileSync(settingsPath, 'utf8').trim();
+        if (raw) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                    return { action: 'skipped', reason: '~/.claude/settings.json is not a JSON object' };
+                }
+                settings = parsed;
+            }
+            catch {
+                // Never overwrite a file we can't understand — the user would lose their config.
+                return { action: 'skipped', reason: 'could not parse ~/.claude/settings.json' };
+            }
+        }
+    }
+    // Everything below treats the user's file as untrusted: it is hand-edited, shared
+    // between tools, and losing part of it would silently break their setup. Anything we
+    // don't recognise is left exactly as found.
+    const rawHooks = settings.hooks;
+    if (rawHooks !== undefined && (typeof rawHooks !== 'object' || rawHooks === null || Array.isArray(rawHooks))) {
+        return { action: 'skipped', reason: '"hooks" in ~/.claude/settings.json is not an object' };
+    }
+    const hooks = (rawHooks ?? {});
+    let added = false;
+    let updated = false;
+    for (const { event, matcher } of CLAUDE_HOOK_EVENTS) {
+        const rawGroups = hooks[event];
+        // An unrecognised shape for this event is left untouched rather than replaced —
+        // overwriting it would discard whatever the user or a plugin configured there.
+        if (rawGroups !== undefined && !Array.isArray(rawGroups))
+            continue;
+        const groups = (rawGroups ?? []);
+        const desired = tracerHandler(port);
+        // Only well-formed groups are candidates for merging into.
+        const usable = groups.filter((g) => !!g && typeof g === 'object' && !Array.isArray(g));
+        // Find our handler wherever it already lives in this event's groups.
+        const ownerGroup = usable.find(g => Array.isArray(g.hooks) && g.hooks.some(h => !!h && isTracerHandler(h)));
+        if (ownerGroup) {
+            const handlers = ownerGroup.hooks;
+            const index = handlers.findIndex(h => !!h && isTracerHandler(h));
+            if (handlers[index].url !== desired.url || handlers[index].timeout !== desired.timeout) {
+                handlers[index] = { ...handlers[index], ...desired };
+                updated = true;
+            }
+            if (matcher !== undefined && ownerGroup.matcher !== matcher) {
+                ownerGroup.matcher = matcher;
+                updated = true;
+            }
+            continue;
+        }
+        // Reuse an existing group with the same matcher so we don't fragment the config.
+        const sameMatcher = usable.find(g => (g.matcher ?? undefined) === matcher);
+        if (sameMatcher) {
+            sameMatcher.hooks = [...(Array.isArray(sameMatcher.hooks) ? sameMatcher.hooks : []), desired];
+        }
+        else {
+            const group = matcher === undefined ? { hooks: [desired] } : { matcher, hooks: [desired] };
+            groups.push(group);
+        }
+        hooks[event] = groups;
+        added = true;
+    }
+    if (!added && !updated)
+        return { action: 'already_set' };
+    settings.hooks = hooks;
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return { action: added ? 'added' : 'updated' };
+}
 // ── Detection helpers ─────────────────────────────────────────────────────────
 function detectCopilotCli() {
     try {
@@ -265,7 +378,27 @@ export function runSetup(port, silent = false) {
             console.log(`\n${WARN} VS Code settings: ${result.reason}`);
         }
     }
-    // 5. Apply env vars to the current process so the OTLP receiver works immediately
+    // 5. Patch Claude Code hooks (turn/tool lifecycle — OTLP can't correlate multi-prompt sessions)
+    const claudeSettingsPath = getClaudeSettingsPath();
+    const claudeResult = patchClaudeSettings(claudeSettingsPath, port);
+    if (claudeResult.action === 'added') {
+        console.log(`\n${CHECK} Claude Code hooks installed`);
+        console.log(`   ${ARROW} ~/.claude/settings.json → ${claudeHookUrl(port)}`);
+        console.log(`   ${ARROW} Captures every prompt, tool call and turn (merged with your existing hooks)`);
+        console.log(`   ${ARROW} Restart Claude Code to apply`);
+    }
+    else if (claudeResult.action === 'updated') {
+        console.log(`\n${CHECK} Claude Code hooks updated`);
+        console.log(`   ${ARROW} Endpoint now ${claudeHookUrl(port)}`);
+        console.log(`   ${ARROW} Restart Claude Code to apply`);
+    }
+    else if (claudeResult.action === 'already_set') {
+        console.log(`\n${CHECK} Claude Code hooks: already configured`);
+    }
+    else {
+        console.log(`\n${WARN} Claude Code hooks: ${claudeResult.reason}`);
+    }
+    // 6. Apply env vars to the current process so the OTLP receiver works immediately
     process.env[OTEL_ENDPOINT_KEY] = `http://localhost:${port}`;
     process.env[OTEL_CONTENT_KEY] = 'true';
     process.env[OTEL_ENABLED_KEY] = 'true';
@@ -276,7 +409,7 @@ export function runSetup(port, silent = false) {
     process.env[OTEL_PROTOCOL_KEY] = 'http/json';
     process.env[OTEL_LOG_PROMPTS_KEY] = '1';
     process.env[OTEL_LOG_RESPONSES_KEY] = '1';
-    // 6. Summary
+    // 7. Summary
     if (!silent) {
         const profileBase = profilePath ? path.basename(profilePath) : '.zshrc';
         console.log('\n────────────────────────────────────────────────');

package/dist/webServer.js

@@ -7,6 +7,7 @@ import { execSync } from 'child_process';
 import { getTraces, getTrace, getSessionSummary, getDashboard, updateProjectLocalPath, getProjectTraces, getProjectSessionSummary } from './db.js';
 import { traceEvents } from './proxy.js';
 import { registerOtlpRoutes } from './otlpReceiver.js';
+import { registerClaudeHookRoutes } from './claudeHooks.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export function startWebServer(port = 4747, sessionId, projectId) {
     const app = express();
@@ -17,6 +18,8 @@ export function startWebServer(port = 4747, sessionId, projectId) {
     // Register OTLP receiver routes
     app.use(express.json({ limit: '10mb' }));
     registerOtlpRoutes(app, sessionId ?? 'default', projectId);
+    // Register Claude Code hook receiver (turn/tool lifecycle; OTLP supplies token usage)
+    registerClaudeHookRoutes(app);
     // API
     app.get('/api/traces', (req, res) => {
         const sid = req.query.sessionId || undefined; // undefined = all sessions
@@ -81,8 +84,16 @@ ${prompt.trim()}`;
             return res.json(null);
         res.json(getSessionSummary(sid));
     });
-    app.get('/api/dashboard', (_req, res) => {
-        res.json(getDashboard());
+    app.get('/api/dashboard', (req, res) => {
+        const pageParam = req.query.page;
+        const pageSizeParam = req.query.pageSize;
+        const page = pageParam === undefined ? 1 : Number(pageParam);
+        const pageSize = pageSizeParam === undefined ? 12 : Number(pageSizeParam);
+        if (!Number.isInteger(page) || page < 1 || !Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+            res.status(400).json({ error: 'page must be a positive integer and pageSize must be an integer between 1 and 100' });
+            return;
+        }
+        res.json(getDashboard(page, pageSize));
     });
     // Project registration — CLI registers its local path for a project
     app.post('/api/projects', (req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-tracer",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Real-time tracing and prompt-refinement companion for GitHub Copilot CLI and VS Code Copilot — tracks tokens, AI credits, tool calls, and refined prompts with console and web UI",
   "keywords": [
     "copilot",

package/web/index.html

@@ -279,6 +279,10 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
   .dash-empty { padding: 60px 24px; text-align: center; color: #8b949e; }
   .dash-empty p { margin-top: 8px; font-size: 12px; }
   .dash-empty code { background: #21262d; padding: 2px 6px; border-radius: 4px; font-size: 11px; color: #79c0ff; }
+  .dash-pagination { display: flex; justify-content: center; align-items: center; gap: 12px; padding: 0 24px 24px; color: #8b949e; font-size: 12px; }
+  .dash-pagination button { background: #21262d; border: 1px solid #30363d; border-radius: 6px; color: #c9d1d9; cursor: pointer; padding: 6px 10px; }
+  .dash-pagination button:hover:not(:disabled) { border-color: #58a6ff; color: #58a6ff; }
+  .dash-pagination button:disabled { cursor: not-allowed; opacity: 0.5; }
 </style>
 </head>
 <body>
@@ -308,6 +312,7 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
     <div class="dash-totals" id="dash-totals"></div>
     <div class="dash-section-title">Projects</div>
     <div id="dash-projects" class="dash-projects"></div>
+    <div id="dash-pagination" class="dash-pagination"></div>
   </div>
 
   <!-- ═══════════════ LIVE TRACER PAGE ═══════════════ -->
@@ -384,6 +389,8 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
   let currentProjectId = null;
   let liveSocket = null;
   let dashboardRefreshPending = false;
+  let dashboardPage = 1;
+  const dashboardPageSize = 12;
 
   // Main socket listens for all trace events — refreshes dashboard in real-time
   // (regardless of active page, so it's fresh when you switch back)
@@ -464,8 +471,10 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
 
   async function loadDashboard() {
     try {
-      const res = await fetch('/api/dashboard');
+      const res = await fetch(`/api/dashboard?page=${dashboardPage}&pageSize=${dashboardPageSize}`);
+      if (!res.ok) throw new Error(`Dashboard request failed: ${res.status}`);
       const data = await res.json();
+      dashboardPage = data.pagination.page;
       renderDashboard(data);
     } catch (e) {
       console.error('Dashboard load failed:', e);
@@ -494,6 +503,7 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
     `;
 
     const projectsEl = document.getElementById('dash-projects');
+    const paginationEl = document.getElementById('dash-pagination');
     if (!data.projects.length) {
       projectsEl.innerHTML = `
         <div class="dash-empty">
@@ -502,6 +512,7 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
           <p>Start the tracer with a project path:</p>
           <p style="margin-top:8px"><code>copilot-tracer --project-path /path/to/repo</code></p>
         </div>`;
+      paginationEl.innerHTML = '';
       return;
     }
 
@@ -532,6 +543,18 @@ Reply with ONLY the rewritten prompt. No explanation, no preamble.`;
           <div class="dash-project-last-active">Last active: ${lastActive}</div>
         </div>`;
     }).join('');
+
+    const { page, totalPages, totalProjects } = data.pagination;
+    paginationEl.innerHTML = totalPages > 1 ? `
+      <button type="button" onclick="changeDashboardPage(-1)" ${page === 1 ? 'disabled' : ''}>Previous</button>
+      <span>Page ${page} of ${totalPages} (${totalProjects} projects)</span>
+      <button type="button" onclick="changeDashboardPage(1)" ${page === totalPages ? 'disabled' : ''}>Next</button>
+    ` : `<span>${totalProjects} project${totalProjects === 1 ? '' : 's'}</span>`;
+  }
+
+  function changeDashboardPage(direction) {
+    dashboardPage += direction;
+    loadDashboard();
   }
 
   // ── Live Tracer (Socket.io) ────────────────────