cc-query 0.1.0

package/bin/cc-query.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { startRepl } from "../src/repl.js";
+import { resolveProjectDir } from "../src/utils.js";
+
+const args = process.argv.slice(2);
+
+// Parse --session or -s flag
+let sessionFilter = "";
+const sessionFlagIndex = args.findIndex((a) => a === "--session" || a === "-s");
+if (sessionFlagIndex !== -1 && sessionFlagIndex + 1 < args.length) {
+  sessionFilter = args[sessionFlagIndex + 1];
+}
+
+// Show help
+if (args.includes("--help") || args.includes("-h")) {
+  console.log("Usage: cc-query [options] [project-path]");
+  console.log("");
+  console.log("Interactive SQL REPL for querying Claude Code session data.");
+  console.log("Uses chdb (embedded ClickHouse) to query JSONL session files.");
+  console.log("");
+  console.log("Arguments:");
+  console.log(
+    "  project-path            Path to project (omit for all projects)",
+  );
+  console.log("");
+  console.log("Options:");
+  console.log(
+    "  --session, -s <prefix>  Filter to sessions matching the ID prefix",
+  );
+  console.log("  --help, -h              Show this help message");
+  console.log("");
+  console.log("Examples:");
+  console.log("  cc-query                          # All projects");
+  console.log("  cc-query ~/code/my-project        # Specific project");
+  console.log("  cc-query -s abc123 .              # Filter by session prefix");
+  console.log("");
+  console.log("Piped input (like psql):");
+  console.log('  echo "SELECT count(*) FROM messages;" | cc-query .');
+  console.log("  cat queries.sql | cc-query .");
+  console.log("");
+  console.log("REPL Commands:");
+  console.log("  .help      Show available tables and example queries");
+  console.log("  .schema    Show table schema");
+  console.log("  .quit      Exit the REPL");
+  process.exit(0);
+}
+
+// Filter out flags to get positional args
+const filteredArgs = args.filter(
+  (a, i) =>
+    a !== "--session" &&
+    a !== "-s" &&
+    (sessionFlagIndex === -1 || i !== sessionFlagIndex + 1),
+);
+
+// If no project specified, use null for all projects
+let claudeProjectsDir = null;
+let projectPath = null;
+
+if (filteredArgs.length > 0) {
+  const resolved = resolveProjectDir(filteredArgs[0]);
+  claudeProjectsDir = resolved.claudeProjectsDir;
+  projectPath = resolved.projectPath;
+}
+
+try {
+  await startRepl(claudeProjectsDir, { sessionFilter });
+} catch (err) {
+  if (
+    err instanceof Error &&
+    /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+  ) {
+    if (projectPath) {
+      console.error(`Error: No Claude Code data found for ${projectPath}`);
+      console.error(`Expected: ${claudeProjectsDir}`);
+    } else {
+      console.error("Error: No Claude Code sessions found");
+    }
+    process.exit(1);
+  }
+  throw err;
+}

package/index.js

@@ -0,0 +1 @@
+export { QuerySession } from "./src/query-session.js";

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cc-query",
+  "version": "0.1.0",
+  "description": "SQL REPL for querying Claude Code session data",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dannycoates/cc-query.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "cc-query": "./bin/cc-query.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@duckdb/node-api": "1.4.3-r.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.3"
+  }
+}

package/src/query-session.js

@@ -0,0 +1,339 @@
+import { DuckDBInstance } from "@duckdb/node-api";
+import { getSessionFiles } from "./session-loader.js";
+
+/**
+ * @typedef {object} QuerySessionInfo
+ * @property {number} sessionCount
+ * @property {number} agentCount
+ * @property {number} projectCount
+ */
+
+/**
+ * Format query results as a table string
+ * @param {import("@duckdb/node-api").DuckDBResultReader} result
+ * @returns {string}
+ */
+function formatResults(result) {
+  const columnCount = result.columnCount;
+  if (columnCount === 0) return "";
+
+  // Build column names array
+  const columnNames = [];
+  for (let i = 0; i < columnCount; i++) {
+    columnNames.push(result.columnName(i));
+  }
+  const rows = result.getRows();
+
+  if (rows.length === 0) {
+    return columnNames.join(" | ") + "\n(0 rows)";
+  }
+
+  // Convert all values to strings and calculate column widths
+  const stringRows = rows.map((row) =>
+    row.map((val) => {
+      if (val === null || val === undefined) return "NULL";
+      if (typeof val === "bigint") return val.toString();
+      if (typeof val === "object") {
+        // Handle DuckDB timestamp objects (returned as {micros: bigint})
+        if ("micros" in val) {
+          const ms = Number(val.micros) / 1000;
+          return new Date(ms).toISOString().replace("T", " ").replace("Z", "");
+        }
+        return JSON.stringify(val, (_, v) =>
+          typeof v === "bigint" ? v.toString() : v,
+        );
+      }
+      return String(val);
+    }),
+  );
+
+  const widths = columnNames.map((name, i) => {
+    const maxDataWidth = Math.max(
+      ...stringRows.map((row) => row[i]?.length || 0),
+    );
+    return Math.max(name.length, maxDataWidth);
+  });
+
+  // Build formatted output
+  const lines = [];
+
+  // Header
+  const header = columnNames.map((n, i) => n.padEnd(widths[i])).join(" │ ");
+  lines.push("┌" + widths.map((w) => "─".repeat(w + 2)).join("┬") + "┐");
+  lines.push("│ " + header + " │");
+  lines.push("├" + widths.map((w) => "─".repeat(w + 2)).join("┼") + "┤");
+
+  // Data rows
+  for (const row of stringRows) {
+    const rowStr = row.map((v, i) => (v || "").padEnd(widths[i])).join(" │ ");
+    lines.push("│ " + rowStr + " │");
+  }
+
+  lines.push("└" + widths.map((w) => "─".repeat(w + 2)).join("┴") + "┘");
+  lines.push(`(${rows.length} row${rows.length === 1 ? "" : "s"})`);
+
+  return lines.join("\n");
+}
+
+/**
+ * A reusable session for querying Claude Code message data
+ */
+export class QuerySession {
+  /** @type {import("@duckdb/node-api").DuckDBConnection | undefined} */
+  #connection;
+  /** @type {string} */
+  #filePattern;
+  /** @type {QuerySessionInfo} */
+  #info;
+
+  /**
+   * @param {string} filePattern - Glob pattern for JSONL files
+   * @param {QuerySessionInfo} info - Session counts
+   */
+  constructor(filePattern, info) {
+    this.#filePattern = filePattern;
+    this.#info = info;
+  }
+
+  /**
+   * Create a QuerySession from a project path
+   * @param {string | null} projectDir - Claude projects dir, or null for all
+   * @param {string} [sessionFilter] - Optional session ID prefix filter
+   * @returns {Promise<QuerySession>}
+   */
+  static async create(projectDir, sessionFilter = "") {
+    const { sessionCount, agentCount, projectCount, filePattern } =
+      await getSessionFiles(projectDir, sessionFilter);
+
+    if (sessionCount === 0) {
+      const err = new Error("No sessions found");
+      // @ts-ignore
+      err.code = "ENOENT";
+      throw err;
+    }
+
+    const qs = new QuerySession(filePattern, {
+      sessionCount,
+      agentCount,
+      projectCount,
+    });
+    await qs.#init();
+    return qs;
+  }
+
+  /** @returns {QuerySessionInfo} */
+  get info() {
+    return this.#info;
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async #init() {
+    const instance = await DuckDBInstance.create(":memory:");
+    this.#connection = await instance.connect();
+    await this.#connection.run(this.#getCreateViewsSql());
+  }
+
+  /**
+   * Execute a SQL query and return formatted table
+   * @param {string} sql
+   * @returns {Promise<string>} Query result as formatted table
+   */
+  async query(sql) {
+    if (!this.#connection) {
+      throw new Error("Session not initialized - use QuerySession.create()");
+    }
+    const result = await this.#connection.runAndReadAll(sql);
+    return formatResults(result);
+  }
+
+  /**
+   * Execute a SQL query and return raw rows
+   * @param {string} sql
+   * @returns {Promise<{columns: string[], rows: any[][]}>} Query result as raw data
+   */
+  async queryRows(sql) {
+    if (!this.#connection) {
+      throw new Error("Session not initialized - use QuerySession.create()");
+    }
+    const result = await this.#connection.runAndReadAll(sql);
+    const columns = [];
+    for (let i = 0; i < result.columnCount; i++) {
+      columns.push(result.columnName(i));
+    }
+    return { columns, rows: result.getRows() };
+  }
+
+  /**
+   * Clean up resources
+   */
+  cleanup() {
+    this.#connection?.closeSync();
+  }
+
+  /**
+   * Get the SQL to create views
+   * @returns {string}
+   */
+  #getCreateViewsSql() {
+    // Explicitly define schema so missing columns become NULL with proper types
+    const columns = {
+      // Common fields
+      uuid: "UUID",
+      type: "VARCHAR",
+      subtype: "VARCHAR",
+      parentUuid: "UUID",
+      timestamp: "TIMESTAMP",
+      sessionId: "UUID",
+      cwd: "VARCHAR",
+      gitBranch: "VARCHAR",
+      slug: "VARCHAR",
+      version: "VARCHAR",
+      isSidechain: "BOOLEAN",
+      userType: "VARCHAR",
+      message: "JSON",
+      // User-specific
+      isCompactSummary: "BOOLEAN",
+      isMeta: "BOOLEAN",
+      isVisibleInTranscriptOnly: "BOOLEAN",
+      sourceToolUseID: "VARCHAR",
+      thinkingMetadata: "JSON",
+      todos: "JSON",
+      toolUseResult: "JSON",
+      // Assistant-specific
+      error: "JSON",
+      isApiErrorMessage: "BOOLEAN",
+      requestId: "VARCHAR",
+      sourceToolAssistantUUID: "UUID",
+      // System-specific
+      content: "VARCHAR",
+      compactMetadata: "JSON",
+      hasOutput: "BOOLEAN",
+      hookCount: "INTEGER",
+      hookErrors: "JSON",
+      hookInfos: "JSON",
+      level: "VARCHAR",
+      logicalParentUuid: "UUID",
+      maxRetries: "INTEGER",
+      preventedContinuation: "BOOLEAN",
+      retryAttempt: "INTEGER",
+      retryInMs: "INTEGER",
+      stopReason: "VARCHAR",
+      toolUseID: "VARCHAR",
+    };
+
+    const columnsDef = Object.entries(columns)
+      .map(([name, type]) => `'${name}': '${type}'`)
+      .join(", ");
+
+    return `
+    -- Base messages view with explicit schema for type safety
+    CREATE OR REPLACE VIEW messages AS
+    SELECT
+      uuid,
+      type,
+      subtype,
+      parentUuid,
+      timestamp,
+      sessionId,
+      cwd,
+      gitBranch,
+      slug,
+      version,
+      isSidechain,
+      userType,
+      message,
+      isCompactSummary,
+      isMeta,
+      isVisibleInTranscriptOnly,
+      sourceToolUseID,
+      sourceToolAssistantUUID,
+      thinkingMetadata,
+      todos,
+      toolUseResult,
+      error,
+      isApiErrorMessage,
+      requestId,
+      content,
+      compactMetadata,
+      hasOutput,
+      hookCount,
+      hookErrors,
+      hookInfos,
+      level,
+      logicalParentUuid,
+      maxRetries,
+      preventedContinuation,
+      retryAttempt,
+      retryInMs,
+      stopReason,
+      toolUseID,
+      -- Derived fields
+      regexp_extract(filename, '[^/]+$') as file,
+      starts_with(regexp_extract(filename, '[^/]+$'), 'agent-') as isAgent,
+      CASE WHEN starts_with(regexp_extract(filename, '[^/]+$'), 'agent-')
+           THEN regexp_extract(regexp_extract(filename, '[^/]+$'), 'agent-([^.]+)', 1)
+           ELSE NULL
+      END as agentId,
+      -- Extract project slug (directory after /projects/)
+      regexp_extract(filename, '/projects/([^/]+)/', 1) as project,
+      ordinality as rownum
+    FROM read_ndjson(
+      '${this.#filePattern}',
+      filename=true,
+      ignore_errors=true,
+      columns={${columnsDef}}
+    ) WITH ORDINALITY
+    WHERE type IN ('user', 'assistant', 'system');
+
+    -- User messages view
+    CREATE OR REPLACE VIEW user_messages AS
+    SELECT
+      uuid, parentUuid, timestamp, sessionId, cwd, gitBranch, slug, version,
+      isSidechain, userType, message, isCompactSummary, isMeta,
+      isVisibleInTranscriptOnly, sourceToolUseID, sourceToolAssistantUUID,
+      thinkingMetadata, todos, toolUseResult, file, isAgent, agentId, project, rownum
+    FROM messages
+    WHERE type = 'user';
+
+    -- Human-typed messages (excludes tool results and system-injected text)
+    CREATE OR REPLACE VIEW human_messages AS
+    SELECT
+      uuid, parentUuid, timestamp, sessionId, cwd, gitBranch, slug, version,
+      isSidechain, message->>'content' as content, file, project, rownum
+    FROM user_messages
+    WHERE json_type(message->'content') = 'VARCHAR'
+      AND (agentId IS NULL OR agentId = '')
+      AND (isMeta IS NULL OR isMeta = false);
+
+    -- Assistant messages view
+    CREATE OR REPLACE VIEW assistant_messages AS
+    SELECT
+      uuid, parentUuid, timestamp, sessionId, cwd, gitBranch, slug, version,
+      isSidechain, userType, message, error, isApiErrorMessage, requestId,
+      file, isAgent, agentId, project, rownum
+    FROM messages
+    WHERE type = 'assistant';
+
+    -- System messages view
+    CREATE OR REPLACE VIEW system_messages AS
+    SELECT
+      uuid, subtype, parentUuid, timestamp, sessionId, cwd, gitBranch, slug,
+      version, isSidechain, userType, content, error, compactMetadata,
+      hasOutput, hookCount, hookErrors, hookInfos, level, logicalParentUuid,
+      maxRetries, preventedContinuation, retryAttempt, retryInMs, stopReason,
+      toolUseID, isMeta, file, isAgent, agentId, project, rownum
+    FROM messages
+    WHERE type = 'system';
+
+    -- Raw messages view with full JSON string
+    CREATE OR REPLACE VIEW raw_messages AS
+    SELECT
+      (json->>'uuid')::UUID as uuid,
+      json as raw
+    FROM read_ndjson_objects('${this.#filePattern}', ignore_errors=true)
+    WHERE json->>'uuid' IS NOT NULL AND length(json->>'uuid') > 0;
+  `;
+  }
+}

package/src/repl.js

@@ -0,0 +1,289 @@
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { QuerySession } from "./query-session.js";
+
+const HISTORY_FILE = join(homedir(), ".cc_query_history");
+const HISTORY_SIZE = 100;
+
+/**
+ * Load query history from file
+ * @returns {Promise<string[]>}
+ */
+async function loadHistory() {
+  try {
+    const content = await readFile(HISTORY_FILE, "utf-8");
+    return content
+      .split("\n")
+      .filter((line) => line.trim())
+      .slice(-HISTORY_SIZE);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save query history to file
+ * @param {string[]} history
+ */
+async function saveHistory(history) {
+  try {
+    await writeFile(
+      HISTORY_FILE,
+      history.slice(-HISTORY_SIZE).join("\n"),
+      "utf-8",
+    );
+  } catch {
+    // Silently ignore write errors
+  }
+}
+
+/**
+ * @typedef {object} ReplOptions
+ * @property {string} [sessionFilter] - Session ID prefix filter
+ */
+
+/**
+ * Get help text for .help command
+ * @returns {string}
+ */
+function getHelpText() {
+  return `
+Commands:
+  .help, .h      Show this help
+  .schema, .s    Show table schema (runs DESCRIBE messages)
+  .schema <view> Show schema for a specific view
+  .quit, .q      Exit
+
+Views:
+  messages            All messages (user, assistant, system)
+  user_messages       User messages with user-specific fields
+  assistant_messages  Assistant messages with error, requestId, etc.
+  system_messages     System messages with hooks, retry info, etc.
+
+Example queries:
+  -- Count messages by type
+  SELECT type, count(*) as cnt FROM messages GROUP BY type ORDER BY cnt DESC;
+
+  -- Messages by project (when querying all projects)
+  SELECT project, count(*) as cnt FROM messages GROUP BY project ORDER BY cnt DESC;
+
+  -- Recent assistant messages
+  SELECT timestamp, message->>'role', message->>'stop_reason'
+  FROM assistant_messages ORDER BY timestamp DESC LIMIT 10;
+
+  -- Tool usage
+  SELECT message->>'stop_reason' as reason, count(*) as cnt
+  FROM assistant_messages
+  GROUP BY reason ORDER BY cnt DESC;
+
+  -- Sessions summary
+  SELECT sessionId, count(*) as msgs, min(timestamp) as started
+  FROM messages GROUP BY sessionId ORDER BY started DESC;
+
+  -- System message subtypes
+  SELECT subtype, count(*) FROM system_messages GROUP BY subtype;
+
+  -- Agent vs main session breakdown
+  SELECT isAgent, count(*) FROM messages GROUP BY isAgent;
+
+JSON field access (DuckDB syntax):
+  message->'field'        Access JSON field (returns JSON)
+  message->>'field'       Access JSON field as string
+  message->'a'->'b'       Nested access
+
+Useful functions:
+  arr[n]                 Get nth element (1-indexed)
+  UNNEST(arr)            Expand array into rows
+  json_extract_string()  Extract string from JSON
+`;
+}
+
+/**
+ * Execute a SQL query and print results
+ * @param {QuerySession} qs
+ * @param {string} query
+ */
+async function executeQuery(qs, query) {
+  try {
+    const result = await qs.query(query);
+    if (result) {
+      console.log(result);
+    }
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+/**
+ * Handle dot commands
+ * @param {string} command
+ * @param {QuerySession} qs
+ * @returns {Promise<boolean>} true if should exit
+ */
+async function handleDotCommand(command, qs) {
+  const cmd = command.toLowerCase();
+
+  if (cmd === ".quit" || cmd === ".exit" || cmd === ".q") {
+    console.log("\nGoodbye!");
+    qs.cleanup();
+    return true;
+  }
+
+  if (cmd === ".help" || cmd === ".h") {
+    console.log(getHelpText());
+    return false;
+  }
+
+  if (cmd === ".schema" || cmd === ".s") {
+    await executeQuery(qs, "DESCRIBE messages");
+    return false;
+  }
+
+  if (cmd.startsWith(".schema ") || cmd.startsWith(".s ")) {
+    const view = command.split(/\s+/)[1];
+    await executeQuery(qs, `DESCRIBE ${view}`);
+    return false;
+  }
+
+  console.log(`Unknown command: ${command}. Type .help for usage.`);
+  return false;
+}
+
+/**
+ * Read all stdin as a string
+ * @returns {Promise<string>}
+ */
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/**
+ * Run queries from piped input (non-interactive mode)
+ * @param {QuerySession} qs
+ * @param {string} input
+ */
+async function runPipedQueries(qs, input) {
+  // Split by semicolons, keeping the semicolon with each statement
+  const statements = input
+    .split(/(?<=;)/)
+    .map((s) => s.trim())
+    .filter((s) => s && s !== ";");
+
+  for (const stmt of statements) {
+    if (stmt.startsWith(".")) {
+      const shouldExit = await handleDotCommand(stmt, qs);
+      if (shouldExit) break;
+    } else {
+      await executeQuery(qs, stmt);
+    }
+  }
+}
+
+/**
+ * Start the interactive REPL or run piped queries
+ * @param {string | null} claudeProjectsDir
+ * @param {ReplOptions} [options]
+ */
+export async function startRepl(claudeProjectsDir, options = {}) {
+  const { sessionFilter = "" } = options;
+
+  // Create query session (handles file discovery and view creation)
+  const qs = await QuerySession.create(claudeProjectsDir, sessionFilter);
+  const { sessionCount, agentCount, projectCount } = qs.info;
+
+  // Check if input is piped (non-TTY)
+  if (!process.stdin.isTTY) {
+    try {
+      const input = await readStdin();
+      await runPipedQueries(qs, input);
+    } finally {
+      qs.cleanup();
+    }
+    return;
+  }
+
+  // Interactive mode
+  try {
+    const projectInfo = projectCount > 1 ? `${projectCount} project(s), ` : "";
+    console.log(
+      `Loaded ${projectInfo}${sessionCount} session(s), ${agentCount} agent file(s)`,
+    );
+    if (sessionFilter) {
+      console.log(`Filter: ${sessionFilter}*`);
+    }
+    console.log('Type ".help" for usage hints.\n');
+
+    // Setup readline with persistent history
+    const history = await loadHistory();
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: "cc-query> ",
+      terminal: true,
+      history,
+      historySize: HISTORY_SIZE,
+      removeHistoryDuplicates: true,
+    });
+
+    // Persist history on changes
+    rl.on("history", (newHistory) => {
+      saveHistory(newHistory);
+    });
+
+    let multiLineBuffer = "";
+    let inMultiLine = false;
+
+    rl.on("close", () => {
+      console.log("\nGoodbye!");
+      qs.cleanup();
+      process.exit(0);
+    });
+
+    rl.prompt();
+
+    for await (const line of rl) {
+      const trimmed = line.trim();
+
+      // Handle multi-line mode
+      if (inMultiLine) {
+        multiLineBuffer += "\n" + line;
+        // Check if query ends with semicolon
+        if (trimmed.endsWith(";")) {
+          await executeQuery(qs, multiLineBuffer);
+          multiLineBuffer = "";
+          inMultiLine = false;
+        } else {
+          process.stdout.write("      -> ");
+          continue;
+        }
+      }
+      // Handle dot commands
+      else if (trimmed.startsWith(".")) {
+        const shouldExit = await handleDotCommand(trimmed, qs);
+        if (shouldExit) break;
+      }
+      // Handle SQL queries
+      else if (trimmed) {
+        if (trimmed.endsWith(";")) {
+          await executeQuery(qs, trimmed);
+        } else {
+          // Start multi-line mode
+          multiLineBuffer = line;
+          inMultiLine = true;
+          process.stdout.write("      -> ");
+          continue;
+        }
+      }
+
+      rl.prompt();
+    }
+  } finally {
+    qs.cleanup();
+  }
+}

package/src/session-loader.js

@@ -0,0 +1,107 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Get the base Claude projects directory
+ * @returns {string}
+ */
+export function getClaudeProjectsBase() {
+  return join(homedir(), ".claude", "projects");
+}
+
+/**
+ * Get all project directories
+ * @returns {Promise<string[]>} Array of project directory paths
+ */
+export async function getAllProjectDirs() {
+  const base = getClaudeProjectsBase();
+  const entries = await readdir(base, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => join(base, e.name));
+}
+
+/**
+ * Count sessions and agents from a list of jsonl filenames
+ * @param {string[]} files - Array of filenames (basenames)
+ * @param {string} sessionFilter - Optional session ID prefix
+ * @returns {{ sessions: number, agents: number }}
+ */
+function countSessionsAndAgents(files, sessionFilter = "") {
+  const jsonlFiles = files.filter((e) => e.endsWith(".jsonl"));
+  const grouped = Object.groupBy(jsonlFiles, (e) =>
+    e.startsWith("agent-") ? "agent" : "session",
+  );
+  const agents = grouped.agent?.length ?? 0;
+  const sessions = (grouped.session ?? []).filter(
+    (e) => !sessionFilter || e.startsWith(sessionFilter),
+  ).length;
+  return { sessions, agents };
+}
+
+/**
+ * Get session info and file pattern for querying
+ * @param {string | null} claudeProjectsDir - Path to ~/.claude/projects/{slug}, or null for all projects
+ * @param {string} [sessionFilter] - Optional session ID prefix
+ * @returns {Promise<{ sessionCount: number, agentCount: number, projectCount: number, filePattern: string }>}
+ */
+export async function getSessionFiles(claudeProjectsDir, sessionFilter = "") {
+  // If no specific project, use all projects
+  if (!claudeProjectsDir) {
+    const base = getClaudeProjectsBase();
+    const projectDirs = await getAllProjectDirs();
+
+    let totalSessions = 0;
+    let totalAgents = 0;
+
+    for (const dir of projectDirs) {
+      // Recursively find all jsonl files (includes */subagents/*.jsonl)
+      const entries = await readdir(dir, { recursive: true });
+      const basenames = entries.map((e) => e.split("/").pop() ?? e);
+      const counts = countSessionsAndAgents(basenames, sessionFilter);
+      totalSessions += counts.sessions;
+      totalAgents += counts.agents;
+    }
+
+    if (totalSessions === 0) {
+      return {
+        sessionCount: 0,
+        agentCount: 0,
+        projectCount: 0,
+        filePattern: "",
+      };
+    }
+
+    // Use glob pattern for all projects (** for recursive matching)
+    const filePattern = sessionFilter
+      ? join(base, "*", `**/${sessionFilter}*.jsonl`)
+      : join(base, "*", "**/*.jsonl");
+
+    return {
+      sessionCount: totalSessions,
+      agentCount: totalAgents,
+      projectCount: projectDirs.length,
+      filePattern,
+    };
+  }
+
+  // Recursively find all jsonl files (includes */subagents/*.jsonl)
+  const entries = await readdir(claudeProjectsDir, { recursive: true });
+  const basenames = entries.map((e) => e.split("/").pop() ?? e);
+  const { sessions, agents } = countSessionsAndAgents(basenames, sessionFilter);
+
+  if (sessions === 0) {
+    return { sessionCount: 0, agentCount: 0, projectCount: 1, filePattern: "" };
+  }
+
+  // Use glob pattern with ** for recursive matching
+  const filePattern = sessionFilter
+    ? join(claudeProjectsDir, `**/${sessionFilter}*.jsonl`)
+    : join(claudeProjectsDir, "**/*.jsonl");
+
+  return {
+    sessionCount: sessions,
+    agentCount: agents,
+    projectCount: 1,
+    filePattern,
+  };
+}

package/src/utils.js

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { join, resolve, isAbsolute } from "node:path";
+
+/**
+ * Resolve a project path to an absolute path
+ * @param {string} projectPath - Path like ~/code/foo, ./foo, or /home/user/code/foo
+ * @returns {string} - Absolute path
+ */
+function resolveProjectPath(projectPath) {
+  let resolved = projectPath.replace(/^~/, homedir());
+  if (!isAbsolute(resolved)) {
+    const baseDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    resolved = resolve(baseDir, resolved);
+  }
+  return resolved;
+}
+
+/**
+ * Get project slug from a filesystem path
+ * @param {string} projectPath - Path like ~/code/zombie-brainz or /home/user/code/zombie-brainz
+ * @returns {string} - Project slug like -home-user-code-zombie-brainz
+ */
+export function getProjectSlug(projectPath) {
+  return resolveProjectPath(projectPath).replace(/[/.]/g, "-");
+}
+
+/**
+ * Convert a project path to the Claude projects directory path
+ * @param {string} projectPath - Path like ~/code/zombie-brainz or /home/user/code/zombie-brainz
+ * @returns {{ projectPath: string, claudeProjectsDir: string }}
+ */
+export function resolveProjectDir(projectPath) {
+  const resolved = resolveProjectPath(projectPath);
+  const slug = getProjectSlug(projectPath);
+  const claudeProjectsDir = join(homedir(), ".claude", "projects", slug);
+  return { projectPath: resolved, claudeProjectsDir };
+}