claude-session-explorer 0.1.0

package/dist/cli.js

@@ -0,0 +1,595 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from 'commander';
+// src/reader.ts
+import { createReadStream } from 'fs';
+import { readdir, readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join, join as join4 } from 'path';
+import { createInterface } from 'readline';
+
+async function readJsonFile(path) {
+  const content = await readFile(path, 'utf-8');
+  return JSON.parse(content);
+}
+async function* readJsonlFile(path) {
+  const stream = createReadStream(path, 'utf-8');
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (trimmed) {
+      yield JSON.parse(trimmed);
+    }
+  }
+}
+async function listSessionFiles(claudeDir) {
+  const sessionsDir = join(claudeDir, 'sessions');
+  try {
+    const files2 = await readdir(sessionsDir);
+    return files2.filter((f) => f.endsWith('.json')).map((f) => join(sessionsDir, f));
+  } catch {
+    return [];
+  }
+}
+async function listProjectDirs(claudeDir) {
+  const projectsDir = join(claudeDir, 'projects');
+  try {
+    const entries = await readdir(projectsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => join(projectsDir, e.name));
+  } catch {
+    return [];
+  }
+}
+async function findConversationFile(claudeDir, sessionId) {
+  const projectDirs = await listProjectDirs(claudeDir);
+  for (const dir of projectDirs) {
+    const files2 = await readdir(dir);
+    const match = files2.find((f) => f.includes(sessionId) && f.endsWith('.jsonl'));
+    if (match) return join(dir, match);
+  }
+  return null;
+}
+async function readSessionMeta(path) {
+  try {
+    return await readJsonFile(path);
+  } catch {
+    return null;
+  }
+}
+async function* readHistory(claudeDir) {
+  const historyPath = join(claudeDir, 'history.jsonl');
+  try {
+    for await (const entry of readJsonlFile(historyPath)) {
+      yield entry;
+    }
+  } catch {}
+}
+
+// src/output.ts
+import chalk from 'chalk';
+import Table from 'cli-table3';
+
+function writeJson(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+function writeTable(headers, rows) {
+  const table = new Table({
+    head: headers.map((h) => chalk.bold(h)),
+    style: { head: [], border: [] },
+  });
+  for (const row of rows) {
+    table.push(row);
+  }
+  process.stdout.write(table.toString() + '\n');
+}
+function writeError(message) {
+  process.stderr.write(
+    chalk.red(`error: ${message}
+`),
+  );
+}
+function formatTimestamp(ms) {
+  return new Date(ms)
+    .toISOString()
+    .replace('T', ' ')
+    .replace(/\.\d+Z$/, '');
+}
+
+// src/commands/list.ts
+async function list(opts) {
+  const files2 = await listSessionFiles(opts.claudeDir);
+  const sessions = [];
+  for (const file of files2) {
+    const meta = await readSessionMeta(file);
+    if (!meta) continue;
+    if (opts.project && !meta.cwd.startsWith(opts.project)) continue;
+    if (opts.kind && meta.kind !== opts.kind) continue;
+    if (opts.entrypoint && meta.entrypoint !== opts.entrypoint) continue;
+    const startedAt = meta.startedAt;
+    if (opts.since && startedAt < new Date(opts.since).getTime()) continue;
+    if (opts.until && startedAt > new Date(opts.until).getTime()) continue;
+    if (opts.today) {
+      const todayStart = /* @__PURE__ */ new Date();
+      todayStart.setHours(0, 0, 0, 0);
+      if (startedAt < todayStart.getTime()) continue;
+    }
+    if (opts.thisWeek) {
+      const now = /* @__PURE__ */ new Date();
+      const weekStart = new Date(now);
+      weekStart.setDate(now.getDate() - now.getDay());
+      weekStart.setHours(0, 0, 0, 0);
+      if (startedAt < weekStart.getTime()) continue;
+    }
+    sessions.push({
+      id: meta.sessionId,
+      date: formatTimestamp(startedAt),
+      project: meta.cwd,
+      kind: meta.kind,
+      entrypoint: meta.entrypoint,
+      startedAt,
+    });
+  }
+  sessions.sort((a, b) => b.startedAt - a.startedAt);
+  if (opts.reverse) sessions.reverse();
+  const limited = sessions.slice(0, opts.limit);
+  if (opts.pretty) {
+    writeTable(
+      ['ID', 'Date', 'Project', 'Kind', 'Entrypoint'],
+      limited.map((s) => [s.id, s.date, s.project, s.kind, s.entrypoint]),
+    );
+  } else {
+    writeJson(limited);
+  }
+}
+
+// src/commands/show.ts
+async function show(sessionId, opts) {
+  const file = await findConversationFile(opts.claudeDir, sessionId);
+  if (!file) {
+    writeError(`Session not found: ${sessionId}`);
+    process.exit(1);
+  }
+  const entries = [];
+  for await (const entry of readJsonlFile(file)) {
+    entries.push(entry);
+  }
+  if (opts.raw) {
+    for (const entry of entries) {
+      process.stdout.write(JSON.stringify(entry) + '\n');
+    }
+    return;
+  }
+  writeJson({ sessionId, file, entryCount: entries.length });
+}
+
+// src/commands/search.ts
+import { readdir as readdir2 } from 'fs/promises';
+import { join as join2 } from 'path';
+
+async function search(query, opts) {
+  if (!query) {
+    writeError('Search query required');
+    process.exit(1);
+  }
+  const matcher = opts.regex
+    ? (text) => new RegExp(query).test(text)
+    : (text) => text.includes(query);
+  const results = [];
+  const projectDirs = await listProjectDirs(opts.claudeDir);
+  for (const dir of projectDirs) {
+    if (opts.project && !dir.includes(opts.project)) continue;
+    const files2 = await readdir2(dir);
+    const jsonlFiles = files2.filter((f) => f.endsWith('.jsonl'));
+    for (const file of jsonlFiles) {
+      const sessionId = file.replace('.jsonl', '');
+      let messageIndex = 0;
+      for await (const entry of readJsonlFile(join2(dir, file))) {
+        const record = entry;
+        const content = extractText(record, opts.all, opts.tools);
+        if (content && matcher(content)) {
+          results.push({
+            sessionId,
+            messageIndex,
+            timestamp: record.timestamp ?? 0,
+            matchingText: content.slice(0, 200),
+          });
+        }
+        messageIndex++;
+      }
+    }
+  }
+  writeJson(results);
+}
+function extractText(record, includeAssistant, includeTools) {
+  const type = record.type;
+  if (type === 'user' || (includeAssistant && type === 'assistant')) {
+    const content = record.content;
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+      return content
+        .filter((b) => b.type === 'text' || (includeTools && b.type === 'tool_use'))
+        .map((b) => (b.type === 'text' ? b.text : JSON.stringify(b.input)))
+        .join('\n');
+    }
+  }
+  return null;
+}
+
+// src/commands/stats.ts
+async function stats(opts) {
+  const files2 = await listSessionFiles(opts.claudeDir);
+  let sessionCount = 0;
+  const projectCounts = /* @__PURE__ */ new Map();
+  const hourCounts = new Array(24).fill(0);
+  for (const file of files2) {
+    const meta = await readSessionMeta(file);
+    if (!meta) continue;
+    if (opts.project && !meta.cwd.startsWith(opts.project)) continue;
+    sessionCount++;
+    projectCounts.set(meta.cwd, (projectCounts.get(meta.cwd) ?? 0) + 1);
+    hourCounts[new Date(meta.startedAt).getHours()]++;
+  }
+  const result = {
+    sessionCount,
+    projectBreakdown: [...projectCounts.entries()]
+      .map(([path, count]) => ({ path, sessionCount: count }))
+      .sort((a, b) => b.sessionCount - a.sessionCount),
+    hourBreakdown: hourCounts.map((count, hour) => ({ hour, sessionCount: count })),
+  };
+  if (opts.pretty) {
+    writeTable(
+      ['Metric', 'Value'],
+      [
+        ['Sessions', String(sessionCount)],
+        ['Projects', String(projectCounts.size)],
+      ],
+    );
+  } else {
+    writeJson(result);
+  }
+}
+
+// src/commands/projects.ts
+import { readdir as readdir3 } from 'fs/promises';
+import { basename } from 'path';
+
+async function projects(opts) {
+  const dirs = await listProjectDirs(opts.claudeDir);
+  const results = [];
+  for (const dir of dirs) {
+    const slug = basename(dir);
+    const files2 = await readdir3(dir);
+    const sessionFiles = files2.filter((f) => f.endsWith('.jsonl'));
+    results.push({
+      path: slug.replaceAll('-', '/'),
+      slug,
+      sessionCount: sessionFiles.length,
+      totalTokens: 0,
+      firstSession: 0,
+      lastSession: 0,
+    });
+  }
+  if (opts.sort === 'sessions') {
+    results.sort((a, b) => b.sessionCount - a.sessionCount);
+  }
+  if (opts.pretty) {
+    writeTable(
+      ['Path', 'Slug', 'Sessions'],
+      results.map((p) => [p.path, p.slug, String(p.sessionCount)]),
+    );
+  } else {
+    writeJson(results);
+  }
+}
+
+// src/commands/history.ts
+async function history(opts) {
+  const entries = [];
+  for await (const entry of readHistory(opts.claudeDir)) {
+    if (opts.search && !entry.prompt.includes(opts.search)) continue;
+    if (opts.project && !entry.project.startsWith(opts.project)) continue;
+    if (opts.since && entry.timestamp < new Date(opts.since).getTime()) continue;
+    entries.push(entry);
+  }
+  entries.sort((a, b) => b.timestamp - a.timestamp);
+  const limited = entries.slice(0, opts.limit);
+  if (opts.pretty) {
+    writeTable(
+      ['Timestamp', 'Project', 'Prompt'],
+      limited.map((e) => [formatTimestamp(e.timestamp), e.project, e.prompt.slice(0, 80)]),
+    );
+  } else {
+    writeJson(limited);
+  }
+}
+
+// src/commands/files.ts
+var TOOL_OP_MAP = {
+  Read: 'read',
+  Write: 'write',
+  Edit: 'edit',
+};
+async function files(sessionId, opts) {
+  const file = await findConversationFile(opts.claudeDir, sessionId);
+  if (!file) {
+    writeError(`Session not found: ${sessionId}`);
+    process.exit(1);
+  }
+  const operations = [];
+  let messageIndex = 0;
+  for await (const entry of readJsonlFile(file)) {
+    const record = entry;
+    if (record.type === 'assistant' && Array.isArray(record.content)) {
+      for (const block of record.content) {
+        if (block.type !== 'tool_use') continue;
+        const toolName = block.name;
+        const operation = TOOL_OP_MAP[toolName];
+        if (!operation) continue;
+        if (opts.reads && operation !== 'read') continue;
+        if (opts.writes && operation !== 'write') continue;
+        if (opts.edits && operation !== 'edit') continue;
+        const input = block.input;
+        const filePath = input.file_path ?? input.path ?? '';
+        operations.push({
+          filePath,
+          operation,
+          timestamp: record.timestamp ?? 0,
+          messageIndex,
+        });
+      }
+    }
+    messageIndex++;
+  }
+  if (opts.pretty) {
+    writeTable(
+      ['File', 'Op', 'Index'],
+      operations.map((o) => [o.filePath, o.operation, String(o.messageIndex)]),
+    );
+  } else {
+    writeJson(operations);
+  }
+}
+
+// src/commands/messages.ts
+async function messages(sessionId, opts) {
+  const file = await findConversationFile(opts.claudeDir, sessionId);
+  if (!file) {
+    writeError(`Session not found: ${sessionId}`);
+    process.exit(1);
+  }
+  let results = [];
+  let index = 0;
+  for await (const entry of readJsonlFile(file)) {
+    const record = entry;
+    const type = record.type;
+    if (type !== 'user' && type !== 'assistant') {
+      index++;
+      continue;
+    }
+    if (opts.user && type !== 'user') {
+      index++;
+      continue;
+    }
+    if (opts.assistant && type !== 'assistant') {
+      index++;
+      continue;
+    }
+    const content = extractTextContent(record, opts.raw);
+    results.push({
+      index,
+      type,
+      timestamp: record.timestamp ?? 0,
+      content,
+    });
+    index++;
+  }
+  if (opts.slice) {
+    const [start, end] = opts.slice.split(':').map(Number);
+    results = results.slice(start, end);
+  } else if (opts.first) {
+    results = results.slice(0, opts.first);
+  } else if (opts.last) {
+    results = results.slice(-opts.last);
+  }
+  writeJson(results);
+}
+function extractTextContent(record, raw) {
+  const content = record.content;
+  if (typeof content === 'string') return content;
+  if (raw) return JSON.stringify(content);
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b.type === 'text')
+      .map((b) => b.text)
+      .join('\n');
+  }
+  return '';
+}
+
+// src/commands/tokens.ts
+async function tokens(sessionId, opts) {
+  if (!sessionId) {
+    writeError('Session ID required (project-level aggregation not yet implemented)');
+    process.exit(1);
+  }
+  const file = await findConversationFile(opts.claudeDir, sessionId);
+  if (!file) {
+    writeError(`Session not found: ${sessionId}`);
+    process.exit(1);
+  }
+  const turns = [];
+  let turnIndex = 0;
+  for await (const entry of readJsonlFile(file)) {
+    const record = entry;
+    const usage = record.usage;
+    if (usage) {
+      turns.push({
+        turnIndex,
+        inputTokens: usage.input_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? 0,
+        cacheReadTokens: usage.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: usage.cache_creation_input_tokens ?? 0,
+        model: record.model,
+      });
+    }
+    turnIndex++;
+  }
+  writeJson(turns);
+}
+
+// src/commands/export.ts
+import { mkdir, writeFile } from 'fs/promises';
+import { join as join3 } from 'path';
+
+async function exportSession(sessionId, opts) {
+  if (!sessionId) {
+    writeError('Session ID required (--all not yet implemented)');
+    process.exit(1);
+  }
+  const file = await findConversationFile(opts.claudeDir, sessionId);
+  if (!file) {
+    writeError(`Session not found: ${sessionId}`);
+    process.exit(1);
+  }
+  const entries = [];
+  for await (const entry of readJsonlFile(file)) {
+    entries.push(entry);
+  }
+  if (opts.stdout) {
+    writeJson(entries);
+    return;
+  }
+  await mkdir(opts.outDir, { recursive: true });
+  const outPath = join3(opts.outDir, `${sessionId}.${opts.format}`);
+  if (opts.format === 'json') {
+    await writeFile(outPath, JSON.stringify(entries, null, 2));
+  } else if (opts.format === 'md') {
+    const md = entries
+      .filter((e) => {
+        const r = e;
+        return r.type === 'user' || r.type === 'assistant';
+      })
+      .map((e) => {
+        const r = e;
+        const role = r.type === 'user' ? 'User' : 'Assistant';
+        const content = typeof r.content === 'string' ? r.content : JSON.stringify(r.content);
+        return `## ${role}
+
+${content}`;
+      })
+      .join('\n\n---\n\n');
+    await writeFile(outPath, md);
+  }
+  process.stderr.write(`Exported to ${outPath}
+`);
+}
+
+// src/cli.ts
+var program = new Command();
+program
+  .name('cse')
+  .description('Deterministic CLI for Claude Code session history')
+  .version('0.1.0')
+  .option('--claude-dir <path>', 'override ~/.claude location', join4(homedir(), '.claude'))
+  .option('--out-dir <path>', 'override output directory', '.cse')
+  .option('--stdout', 'write to stdout instead of file')
+  .option('--json', 'JSON output (default)', true)
+  .option('--pretty', 'human-readable table output')
+  .option('--no-color', 'disable colored output')
+  .option('--verbose', 'debug info to stderr');
+function globals() {
+  return program.opts();
+}
+program
+  .command('list')
+  .description('List sessions')
+  .option('--project <path>', 'filter by project directory')
+  .option('--since <date>', 'filter by start date')
+  .option('--until <date>', 'filter by end date')
+  .option('--today', "shorthand for today's sessions")
+  .option('--this-week', 'shorthand for current week')
+  .option('--kind <kind>', 'filter by session kind')
+  .option('--entrypoint <ep>', 'filter by entrypoint (cli/ide/web)')
+  .option('--limit <n>', 'limit results', '50')
+  .option('--sort <field>', 'sort: date, duration, tokens, messages', 'date')
+  .option('--reverse', 'reverse sort order')
+  .action((opts) => list({ ...globals(), ...opts, limit: Number(opts.limit) }));
+program
+  .command('show <session-id>')
+  .description('Show session detail')
+  .option('--messages', 'all messages with type, timestamp, content length')
+  .option('--tools', 'all tool_use blocks')
+  .option('--files', 'all file paths from tool_use inputs')
+  .option('--tokens', 'per-turn token usage')
+  .option('--raw', 'raw JSONL lines')
+  .action((id, opts) => show(id, { ...globals(), ...opts }));
+program
+  .command('search <query>')
+  .description('Full-text search across sessions')
+  .option('--all', 'search user + assistant content')
+  .option('--tools', 'search tool_use inputs/outputs')
+  .option('--project <path>', 'scope to project')
+  .option('--since <date>', 'filter by date')
+  .option('--context <n>', 'include N messages around match')
+  .option('--regex', 'treat query as regex')
+  .action((query, opts) => search(query, { ...globals(), ...opts }));
+program
+  .command('stats')
+  .description('Aggregate statistics')
+  .option('--project <path>', 'per-project stats')
+  .option('--daily', 'daily breakdown')
+  .option('--weekly', 'weekly breakdown')
+  .action((opts) => stats({ ...globals(), ...opts }));
+program
+  .command('projects')
+  .description('List all projects')
+  .option('--sort <field>', 'sort: sessions, tokens, recent', 'sessions')
+  .action((opts) => projects({ ...globals(), ...opts }));
+program
+  .command('history')
+  .description('Prompt history')
+  .option('--search <text>', 'exact substring match on prompt text')
+  .option('--project <path>', 'filter by project')
+  .option('--since <date>', 'filter by date')
+  .option('--limit <n>', 'number of entries', '50')
+  .action((opts) => history({ ...globals(), ...opts, limit: Number(opts.limit) }));
+program
+  .command('files <session-id>')
+  .description('Extract file operations')
+  .option('--reads', 'only Read tool calls')
+  .option('--writes', 'only Write tool calls')
+  .option('--edits', 'only Edit tool calls')
+  .action((id, opts) => files(id, { ...globals(), ...opts }));
+program
+  .command('messages <session-id>')
+  .description('Extract messages')
+  .option('--user', 'only user messages')
+  .option('--assistant', 'only assistant messages')
+  .option('--first <n>', 'first N messages')
+  .option('--last <n>', 'last N messages')
+  .option('--slice <range>', 'message range by index (e.g. 5:15)')
+  .option('--raw', 'include tool blocks')
+  .action((id, opts) =>
+    messages(id, {
+      ...globals(),
+      ...opts,
+      first: opts.first ? Number(opts.first) : void 0,
+      last: opts.last ? Number(opts.last) : void 0,
+    }),
+  );
+program
+  .command('tokens [session-id]')
+  .description('Token usage')
+  .option('--project <path>', 'aggregate per-session for a project')
+  .option('--daily', 'daily token totals')
+  .option('--by-model', 'grouped by model')
+  .action((id, opts) => tokens(id, { ...globals(), ...opts }));
+program
+  .command('export [session-id]')
+  .description('Export data')
+  .option('--format <fmt>', 'output format: json, md, csv', 'json')
+  .option('--all', 'export all sessions')
+  .option('--project <path>', 'export project sessions')
+  .action((id, opts) => exportSession(id, { ...globals(), ...opts }));
+program.parse();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "claude-session-explorer",
+  "version": "0.1.0",
+  "description": "Deterministic CLI for extracting structured data from Claude Code session history",
+  "type": "module",
+  "packageManager": "pnpm@10.20.0",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=10"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "cse": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "check": "biome ci . && pnpm typecheck",
+    "prepare": "simple-git-hooks"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm exec biome check --staged --no-errors-on-unmatched",
+    "pre-push": "pnpm typecheck"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/node": "^22.0.0",
+    "simple-git-hooks": "^2.12.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3"
+  }
+}