syndes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guruprasath005
+
+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,77 @@
+# SynDes
+
+**A tamper-evident ledger of everything you do in Claude Code, an efficiency
+score built from it, and a local dashboard that shows you how you actually work.**
+
+macOS, Windows and Linux. Zero dependencies. Nothing leaves your machine.
+
+```bash
+npm install -g syndes
+```
+
+That is the whole setup. It wires itself into Claude Code, opens the ledger and
+starts recording; your next `syndes` explains the rest.
+
+## What it does
+
+**Works with more than one agent.** Claude Code through its hook API, Codex by
+following its session files. Everything below that — the chain, the score, the
+practice rules, the dashboard — is agent-agnostic, so adding another is one
+adapter, not a rewrite. `syndes sources` shows what it can see.
+
+**Records every move.** Every prompt, tool call, permission block, compaction,
+interrupt, token and dollar — appended to a hash-chained log that cannot be
+edited, re-ordered or back-dated without `syndes verify` naming the exact
+record where the chain breaks.
+
+**Tells you how to work better.** A dozen practice rules run over that ledger and
+surface at most one nudge, at a moment that does not interrupt you, always with
+the evidence attached: *"you edited `src/app.ts` six times in twelve minutes
+without running tests."*
+
+**Shows you the whole picture.** `syndes dashboard` opens a local
+dashboard: your efficiency score and its five pillars, token and cost
+breakdowns, cache hit rate, active time versus wall-clock, permission friction,
+tool mix, per-project history — every number clickable through to the records
+that produced it.
+
+**No password to invent.** The dashboard opens straight from the command line;
+the link it prints carries a one-time key. If you want a lock, use the one your
+machine already has — `syndes lock system` asks Touch ID — or set a PIN.
+
+## Commands
+
+| | |
+| --- | --- |
+| `syndes` | today at a glance |
+| `syndes dashboard` | the full UI, on 127.0.0.1 |
+| `syndes report week` | terminal digest |
+| `syndes verify` | prove the chain is intact |
+| `syndes sessions` | list and drill down |
+| `syndes export --format=csv` | all of it, back out |
+| `syndes lock system` | require Touch ID to open the dashboard |
+| `syndes sources` | which coding agents SynDes can see |
+| `syndes watch` | follow agents that have no hook API |
+| `syndes doctor` | what is wired and what actually works |
+| `syndes off` | stop tracking (recorded in the ledger) |
+
+## Privacy
+
+No telemetry, no endpoint, no account. Secrets are scrubbed **before** anything
+is written, because an append-only ledger has no take-backs. Three modes:
+`redacted` (default), `full`, `metadata`.
+
+What keeps the dashboard private is that it binds loopback and refuses any
+request whose `Host` is not a literal loopback address — without that, any web
+page you have open could read it. The lock is the second layer, for machines
+other people also use.
+
+## Honest limits
+
+The ledger is **tamper-evident, not tamper-proof**. Anything running as your
+user can delete the directory. What it guarantees is that nothing can be quietly
+*changed* — see `DESIGN.md` §2.
+
+## License
+
+MIT

package/adapters/claude-code.mjs

@@ -0,0 +1,59 @@
+/**
+ * Claude Code — the hook adapter.
+ *
+ * The highest-fidelity source we have: Claude Code invokes our hook on every
+ * event, so permission stops, tool boundaries and compactions are all observed
+ * as they happen rather than inferred from a log afterwards.
+ *
+ * The classification logic itself lives in collect/classify.mjs, which predates
+ * the adapter layer and is exercised by its own tests; this file is the seam
+ * that lets a second agent exist beside it.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { claudeDir, settingsFile } from '../runtime/paths.mjs';
+import { classify as classifyPayload } from '../collect/classify.mjs';
+import { familyOf as toolFamily } from '../collect/tools.mjs';
+import { installHooks, uninstallHooks, hookCommand, installedEvents, HOOK_EVENTS } from '../src/settings.mjs';
+
+export default {
+  id: 'claude-code',
+  name: 'Claude Code',
+  capture: 'hook',
+
+  detect() {
+    // The config directory is the honest signal. A `claude` binary may live
+    // anywhere or be a shell alias, but nothing creates ~/.claude except
+    // Claude Code having run.
+    const present = existsSync(claudeDir) || existsSync(join(homedir(), '.claude'));
+    return {
+      present,
+      detail: present ? `hooks in ${settingsFile.replace(homedir(), '~')}` : 'no ~/.claude directory found',
+    };
+  },
+
+  install() {
+    const { backup, events } = installHooks(hookCommand());
+    return { steps: [{ step: 'hooks', detail: `${events.length} events`, backup }] };
+  },
+
+  uninstall() {
+    const { removed, backup } = uninstallHooks();
+    return { steps: [{ step: 'hooks', detail: removed.length ? removed.join(', ') : 'none were wired', backup }] };
+  },
+
+  status() {
+    const { events } = installedEvents();
+    return { wired: events.length, expected: HOOK_EVENTS.length, events };
+  },
+
+  classify(raw, ctx) {
+    return classifyPayload(raw, ctx);
+  },
+
+  familyOf(tool) {
+    return toolFamily(tool);
+  },
+};

package/adapters/codex.mjs

@@ -0,0 +1,256 @@
+/**
+ * OpenAI Codex CLI — the tail adapter.
+ *
+ * Codex has no hook API, so nothing invokes us. Instead the watcher follows the
+ * rollout files Codex writes under ~/.codex/sessions and turns appended lines
+ * into the same records the Claude Code hooks produce.
+ *
+ * What that costs: no permission-stop events and coarser timing, because the
+ * transcript records what happened rather than what was about to. What it buys:
+ * it needs no cooperation from Codex at all, and the same approach works for
+ * any agent that writes a session log — which is nearly all of them.
+ *
+ * The format is Codex's, not ours. Parse defensively; an unrecognised line is
+ * skipped, never fatal.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { draft, KIND } from '../ledger/schema.mjs';
+import { redact, clamp } from '../collect/redact.mjs';
+
+const HOME = homedir();
+const CODEX_DIR = process.env.CODEX_HOME?.trim() || join(HOME, '.codex');
+const SESSIONS = join(CODEX_DIR, 'sessions');
+
+/** Follow files touched in the last week; older ones are finished history. */
+const RECENT_MS = 7 * 24 * 60 * 60 * 1000;
+
+const FAMILY = {
+  shell: 'execute',
+  local_shell: 'execute',
+  exec_command: 'execute',
+  apply_patch: 'edit',
+  read_file: 'read',
+  view_image: 'read',
+  update_plan: 'plan',
+  web_search: 'web',
+  mcp_tool_call: 'mcp',
+};
+
+export default {
+  id: 'codex',
+  name: 'Codex CLI',
+  capture: 'tail',
+
+  detect() {
+    if (!existsSync(CODEX_DIR)) return { present: false, detail: 'no ~/.codex directory found' };
+    const files = list();
+    return {
+      present: true,
+      detail: files.length
+        ? `${files.length} recent session file(s) in ~/.codex/sessions`
+        : 'installed, but no recent sessions to read',
+    };
+  },
+
+  /** Nothing to wire: tailing needs no cooperation from the agent. */
+  install() {
+    return { steps: [{ step: 'watch', detail: `following ${SESSIONS.replace(HOME, '~')}` }] };
+  },
+
+  uninstall() {
+    return { steps: [{ step: 'watch', detail: 'stopped following ~/.codex/sessions' }] };
+  },
+
+  sources() {
+    return list();
+  },
+
+  familyOf(tool) {
+    if (!tool) return 'other';
+    if (tool.startsWith('mcp')) return 'mcp';
+    return FAMILY[tool] ?? 'other';
+  },
+
+  /**
+   * One transcript line → drafts.
+   *
+   * @param {{line: object, file: string}} raw
+   */
+  classify(raw, ctx) {
+    const entry = raw?.line;
+    if (!entry || typeof entry !== 'object') return [];
+
+    const ts = Date.parse(entry.timestamp ?? '') || raw.at || Date.now();
+    const session = raw.session ?? null;
+    const project = ctx?.project?.id ?? null;
+    const base = { ts, session, project, source: 'codex' };
+    const mode = ctx?.config?.privacy ?? 'redacted';
+    const extra = ctx?.config?.redactPatterns ?? [];
+
+    const payload = entry.payload ?? entry;
+    const type = entry.type ?? payload?.type;
+
+    switch (type) {
+      case 'session_meta':
+      case 'session.created':
+        return [draft(KIND.SESSION_START, {
+          ...base,
+          data: { source: 'startup', cwd: mode === 'metadata' ? null : payload.cwd ?? null, agent: 'codex' },
+        })];
+
+      case 'user_message':
+      case 'message': {
+        if (payload.role && payload.role !== 'user') return [];
+        const text = textOf(payload);
+        if (!text) return [];
+        const scrubbed = redact(text, { mode, extra });
+        const stored = clamp(scrubbed.text);
+        return [draft(KIND.PROMPT, {
+          ...base,
+          data: {
+            chars: text.length,
+            words: text.trim() ? text.trim().split(/\s+/).length : 0,
+            lines: text.split('\n').length,
+            text: stored.text,
+            truncated: stored.truncated,
+            redactions: scrubbed.redactions,
+            correction: /^\s*(no|nope)\b|\bi (meant|said)\b|\bactually\b/i.test(text),
+          },
+        })];
+      }
+
+      case 'function_call':
+      case 'tool_call': {
+        const tool = payload.name ?? payload.tool ?? 'unknown';
+        return [draft(KIND.TOOL_PRE, {
+          ...base,
+          data: {
+            tool,
+            family: this.familyOf(tool),
+            target: mode === 'metadata' ? null : targetOf(tool, payload),
+            searchViaBash: this.familyOf(tool) === 'execute' && /\b(grep|rg|find|fd)\b/.test(argText(payload)),
+            verification: this.familyOf(tool) === 'execute' && /\b(test|lint|build|typecheck|pytest|cargo)\b/.test(argText(payload)),
+          },
+        })];
+      }
+
+      case 'function_call_output':
+      case 'tool_result': {
+        const tool = payload.name ?? payload.tool ?? 'unknown';
+        const failed = payload.success === false || payload.is_error === true ||
+          /^error\b/i.test(String(payload.output ?? payload.content ?? '').slice(0, 40));
+        const drafts = [draft(KIND.TOOL_POST, {
+          ...base,
+          data: { tool, family: this.familyOf(tool), target: mode === 'metadata' ? null : targetOf(tool, payload), durationMs: null, failed },
+        })];
+
+        if (this.familyOf(tool) === 'edit') {
+          const path = targetOf(tool, payload);
+          drafts.push(draft(KIND.FILE_TOUCH, {
+            ...base,
+            // Codex does not tell us whether the file was read first, and
+            // guessing would put a fabricated number into the score.
+            data: { path: mode === 'metadata' ? null : path, ext: extOf(path), op: 'edit', readFirst: null },
+          }));
+        }
+        return drafts;
+      }
+
+      case 'token_count':
+      case 'usage': {
+        const usage = payload.info?.total_token_usage ?? payload.usage ?? payload;
+        if (!usage || typeof usage !== 'object') return [];
+        return [draft(KIND.USAGE, {
+          ...base,
+          data: {
+            model: payload.model ?? entry.model ?? 'codex',
+            input: usage.input_tokens ?? 0,
+            output: usage.output_tokens ?? 0,
+            cacheRead: usage.cached_input_tokens ?? usage.cache_read_input_tokens ?? 0,
+            cacheWrite: 0,
+            thinking: usage.reasoning_output_tokens ?? 0,
+            toolUses: 0,
+            sidechain: false,
+          },
+        })];
+      }
+
+      case 'turn_complete':
+      case 'task_complete':
+        return [draft(KIND.STOP, { ...base, data: { chained: false } })];
+
+      default:
+        return [];
+    }
+  },
+};
+
+/** Session files touched recently, newest last so replay order is natural. */
+function list() {
+  if (!existsSync(SESSIONS)) return [];
+  const out = [];
+  const cutoff = Date.now() - RECENT_MS;
+
+  const walk = (dir, depth = 0) => {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (entry.name.endsWith('.jsonl')) {
+        try {
+          if (statSync(full).mtimeMs >= cutoff) out.push(full);
+        } catch { /* vanished between readdir and stat */ }
+      }
+    }
+  };
+
+  walk(SESSIONS);
+  return out.sort();
+}
+
+function textOf(payload) {
+  if (typeof payload.content === 'string') return payload.content;
+  if (typeof payload.message === 'string') return payload.message;
+  if (Array.isArray(payload.content)) {
+    return payload.content.map((part) => part?.text ?? '').filter(Boolean).join('\n');
+  }
+  return '';
+}
+
+function argText(payload) {
+  try {
+    return typeof payload.arguments === 'string' ? payload.arguments : JSON.stringify(payload.arguments ?? {});
+  } catch {
+    return '';
+  }
+}
+
+function targetOf(tool, payload) {
+  let args = payload.arguments;
+  if (typeof args === 'string') {
+    try { args = JSON.parse(args); } catch { args = {}; }
+  }
+  args ??= {};
+
+  if (Array.isArray(args.command)) return args.command[0]?.split('/').pop()?.slice(0, 40) ?? null;
+  if (typeof args.command === 'string') return args.command.trim().split(/\s+/)[0]?.split('/').pop()?.slice(0, 40) ?? null;
+  return args.path ?? args.file_path ?? args.filename ?? null;
+}
+
+function extOf(path) {
+  if (typeof path !== 'string') return null;
+  const name = path.split(/[\\/]/).pop() ?? '';
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot + 1).toLowerCase().slice(0, 12) : null;
+}
+
+export { SESSIONS, CODEX_DIR };

package/adapters/index.mjs

@@ -0,0 +1,92 @@
+/**
+ * Source adapters — how SynDes learns what an agent did.
+ *
+ * Everything below this layer is already agent-agnostic: the chain, the
+ * rollups, the score, the practice rules and the dashboard all operate on
+ * normalised records and never ask where one came from. So supporting a new
+ * coding agent means writing one adapter, not touching any of that.
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ * An adapter is an object with:
+ *
+ *   id            stable string written into every record's `source`
+ *   name          what a human calls it
+ *   capture       'hook' | 'tail'  — how events arrive (see below)
+ *   detect()      → { present, detail }   is this agent installed here?
+ *   install()     → { steps }             wire it up (hook adapters only)
+ *   uninstall()   → { steps }
+ *   classify(raw, ctx) → draft[]          raw event → ledger records
+ *   familyOf(tool) → family               its tool names → our shared taxonomy
+ *   sources()     → string[]              files to tail (tail adapters only)
+ *
+ * ── The two capture modes ───────────────────────────────────────────────────
+ * `hook` is the high-fidelity path: the agent invokes us on every event, so we
+ * see permission stops and tool boundaries as they happen. Only agents with a
+ * hook API can do this.
+ *
+ * `tail` needs no cooperation at all — a watcher follows the agent's own
+ * session files and turns appended lines into records. Lower fidelity (no
+ * permission events, coarser timing) but it works for anything that writes a
+ * transcript, which is most of them.
+ */
+
+import claudeCode from './claude-code.mjs';
+import codex from './codex.mjs';
+
+export const ADAPTERS = [claudeCode, codex];
+
+export const DEFAULT_SOURCE = claudeCode.id;
+
+export function adapterFor(id) {
+  return ADAPTERS.find((adapter) => adapter.id === id) ?? null;
+}
+
+export function adapterIds() {
+  return ADAPTERS.map((adapter) => adapter.id);
+}
+
+/** Adapters whose agent is actually installed on this machine. */
+export function detectAll() {
+  return ADAPTERS.map((adapter) => {
+    let found = { present: false, detail: 'detection failed' };
+    try {
+      found = adapter.detect();
+    } catch (error) {
+      found = { present: false, detail: error.message };
+    }
+    return { id: adapter.id, name: adapter.name, capture: adapter.capture, ...found };
+  });
+}
+
+/**
+ * Map a tool name to our shared family taxonomy.
+ *
+ * Every agent names its tools differently — Read/Grep/Bash here,
+ * shell/apply_patch there. Normalising into one set of families is what makes
+ * "you search through the shell more than you should" a statement that holds
+ * across agents rather than one that only means something for Claude Code.
+ */
+export function familyOf(source, tool) {
+  return adapterFor(source)?.familyOf?.(tool) ?? 'other';
+}
+
+/** Turn one raw captured event into ledger drafts. */
+export function classify(source, raw, ctx) {
+  const adapter = adapterFor(source);
+  if (!adapter) return [];
+  return adapter.classify(raw, ctx).map((record) => ({ ...record, source }));
+}
+
+/** Every file the watcher should follow, across all tail adapters. */
+export function tailTargets() {
+  const out = [];
+  for (const adapter of ADAPTERS) {
+    if (adapter.capture !== 'tail') continue;
+    try {
+      for (const file of adapter.sources() ?? []) out.push({ source: adapter.id, file });
+    } catch {
+      // An agent that is not installed simply contributes nothing to follow.
+    }
+  }
+  return out;
+}

package/analytics/index.mjs

@@ -0,0 +1,189 @@
+/**
+ * The one façade the CLI and the dashboard both call.
+ *
+ * No metric is computed in two places. The alternative is a terminal report and
+ * a UI that eventually disagree, with one of them wrong in a way nobody notices
+ * for months.
+ */
+
+import { rangeFor, previousRange, localDay } from './ranges.mjs';
+import { rollupsFor, mergeRollups } from './rollup.mjs';
+import { score } from './score.mjs';
+import { costOf, savingsFromCache } from './metrics/cost.mjs';
+import { loadConfig } from '../runtime/config.mjs';
+import { nameFor, loadProjects } from '../collect/projects.mjs';
+import { readRange, height } from '../ledger/read.mjs';
+import { KIND } from '../ledger/schema.mjs';
+
+export { rangeFor, previousRange, localDay };
+
+async function summarise(range) {
+  const rollups = await rollupsFor(range);
+  const merged = mergeRollups(rollups);
+  const prices = loadConfig().prices ?? {};
+  return {
+    range,
+    rollups,
+    merged,
+    cost: costOf(merged.tokens, prices),
+    cacheSavings: savingsFromCache(merged.tokens, prices),
+  };
+}
+
+/** Everything the overview screen needs, plus the same numbers one period back. */
+export async function overview(spec = '7d') {
+  const range = rangeFor(spec);
+  const current = await summarise(range);
+  const previous = await summarise(previousRange(range));
+
+  const scored = score(current.merged);
+  const before = score(previous.merged);
+
+  return {
+    range: { ...range, days: range.days },
+    score: scored,
+    scoreDelta: scored.total !== null && before.total !== null ? scored.total - before.total : null,
+    headline: headlineOf(current),
+    previousHeadline: headlineOf(previous),
+    series: current.rollups.map((rollup) => ({
+      day: rollup.day,
+      records: rollup.records,
+      prompts: rollup.metrics?.prompts?.count ?? 0,
+      toolCalls: rollup.metrics?.tools?.calls ?? 0,
+      activeMs: rollup.metrics?.time?.activeMs ?? 0,
+      tokens: totalTokens(rollup.metrics?.tokens),
+      // Per-day so the timeline can mark the days the window ran out, which is
+      // the single most useful thing to spot across a week.
+      compacts: (rollup.metrics?.context?.autoCompacts ?? 0) + (rollup.metrics?.context?.manualCompacts ?? 0),
+      sessions: (rollup.metrics?.volume?.sessions ?? []).length,
+      cost: 0,
+    })),
+    hours: current.merged.time.hours,
+    weekdays: current.merged.time.weekdays,
+    metrics: current.merged,
+    cost: current.cost,
+    cacheSavings: current.cacheSavings,
+    ledger: height(),
+  };
+}
+
+function headlineOf({ merged, cost }) {
+  return {
+    sessions: merged.volume.sessionCount,
+    prompts: merged.prompts.count,
+    toolCalls: merged.tools.calls,
+    activeMs: merged.time.activeMs,
+    wallMs: merged.time.wallMs,
+    tokens: merged.tokens.total,
+    cacheHitRate: merged.tokens.cacheHitRate,
+    usd: cost.usd,
+    files: merged.volume.fileCount,
+    commits: merged.volume.commits,
+    compacts: merged.context.compacts,
+    blocks: merged.friction.blocks,
+  };
+}
+
+function totalTokens(summary) {
+  if (!summary?.byModel) return 0;
+  let total = 0;
+  for (const bucket of Object.values(summary.byModel)) {
+    total += bucket.input + bucket.output + bucket.cacheRead + bucket.cacheWrite;
+  }
+  return total;
+}
+
+/** Per-session detail, reconstructed from the chain rather than from state. */
+export async function sessions(spec = '7d') {
+  const range = rangeFor(spec);
+  const found = new Map();
+
+  for await (const record of readRange(range.from, range.to)) {
+    const id = record.session;
+    if (!id) continue;
+
+    if (!found.has(id)) {
+      found.set(id, {
+        id, project: record.project, projectName: null,
+        startedAt: record.ts, endedAt: record.ts,
+        prompts: 0, toolCalls: 0, writes: 0, blocks: 0, compacts: 0,
+        errors: 0, tokens: 0, models: new Set(), files: new Set(),
+        ended: false, reason: null,
+      });
+    }
+    const session = found.get(id);
+    session.endedAt = Math.max(session.endedAt, record.ts);
+    session.project ??= record.project;
+
+    switch (record.kind) {
+      case KIND.PROMPT: session.prompts += 1; break;
+      case KIND.TOOL_POST:
+        session.toolCalls += 1;
+        if (record.data.failed) session.errors += 1;
+        break;
+      case KIND.FILE_TOUCH:
+        session.writes += 1;
+        if (record.data.path) session.files.add(record.data.path);
+        break;
+      case KIND.TOOL_BLOCKED: session.blocks += 1; break;
+      case KIND.COMPACT: session.compacts += 1; break;
+      case KIND.USAGE:
+        session.tokens += (record.data.input ?? 0) + (record.data.output ?? 0) +
+          (record.data.cacheRead ?? 0) + (record.data.cacheWrite ?? 0);
+        if (record.data.model) session.models.add(record.data.model);
+        break;
+      case KIND.SESSION_END:
+        session.ended = true;
+        session.reason = record.data.reason;
+        break;
+      default: break;
+    }
+  }
+
+  const names = loadProjects();
+  return [...found.values()]
+    .map((session) => ({
+      ...session,
+      projectName: names[session.project]?.name ?? session.project,
+      models: [...session.models],
+      files: [...session.files].length,
+      durationMs: session.endedAt - session.startedAt,
+    }))
+    .sort((a, b) => b.startedAt - a.startedAt);
+}
+
+/** One session's records, for the timeline view. */
+export async function sessionDetail(sessionId) {
+  const events = [];
+  for await (const record of readRange(0, Date.now() + 86_400_000)) {
+    if (record.session === sessionId) events.push(record);
+  }
+  return events;
+}
+
+export async function byProject(spec = '30d') {
+  const range = rangeFor(spec);
+  const buckets = new Map();
+
+  for await (const record of readRange(range.from, range.to)) {
+    const id = record.project ?? 'unknown';
+    if (!buckets.has(id)) {
+      buckets.set(id, { id, name: nameFor(id), records: 0, prompts: 0, toolCalls: 0, tokens: 0, sessions: new Set() });
+    }
+    const bucket = buckets.get(id);
+    bucket.records += 1;
+    if (record.session) bucket.sessions.add(record.session);
+    if (record.kind === KIND.PROMPT) bucket.prompts += 1;
+    if (record.kind === KIND.TOOL_POST) bucket.toolCalls += 1;
+    if (record.kind === KIND.USAGE) {
+      bucket.tokens += (record.data.input ?? 0) + (record.data.output ?? 0) +
+        (record.data.cacheRead ?? 0) + (record.data.cacheWrite ?? 0);
+    }
+  }
+
+  return [...buckets.values()]
+    .map((bucket) => ({ ...bucket, sessions: bucket.sessions.size }))
+    .sort((a, b) => b.records - a.records);
+}
+
+export { summarise, score };