cc-query 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,67 @@
+# cc-query
+
+SQL REPL for querying Claude Code session data using DuckDB.
+
+## Installation
+
+```bash
+npm install -g cc-query
+```
+
+Requires Node.js 24+.
+
+## Usage
+
+```bash
+# Query all projects
+cc-query
+
+# Query a specific project
+cc-query ~/code/my-project
+
+# Filter by session ID prefix
+cc-query -s abc123 .
+
+# Pipe queries (like psql)
+echo "SELECT count(*) FROM messages;" | cc-query .
+```
+
+## Available Views
+
+- `messages` - All messages with parsed fields
+- `user_messages` - User messages only
+- `assistant_messages` - Assistant responses only
+- `tool_calls` - Tool invocations from assistant messages
+- `raw_messages` - Unparsed JSONL data
+
+## REPL Commands
+
+- `.help` - Show tables and example queries
+- `.schema` - Show table schema
+- `.quit` - Exit
+
+## Skill (experimental)
+
+This [example skill](examples/skills/reflect/SKILL.md) gives claude the ability and slash command `/reflect` to work with claude session history.
+
+Why not a plugin? If you copy the skill you can reflect on it to adapt to your own usage.
+
+For example you can ask questions like:
+- Across all projects what bash commands return the most errors?
+- Let's analyze the last session and identify how we might improve the claude.md file
+- Gimme a summary of what we worked on this past week
+- Let's go though our whole session history and identify repeated patterns that we could extract into skills
+- Let's look at our use of cc-query tool calls to see how we might improve the reflect skill
+
+### Test drive
+
+To test drive this skill do something like this:
+
+1. `npm i -g cc-query`
+2. Clone this repo or otherwise fetch the `examples/skills/reflect` dir
+3. `mkdir -p ~/.claude/skills && cp -R examples/skills/reflect ~/.claude/skills/`
+4. run claude and use `/reflect [whatever you want]`
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-query",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SQL REPL for querying Claude Code session data",
   "type": "module",
   "exports": {

package/src/query-session.js

@@ -8,6 +8,59 @@ import { getSessionFiles } from "./session-loader.js";
  * @property {number} projectCount
  */
 
+/**
+ * Convert a result value to string for display
+ * @param {any} val
+ * @returns {string}
+ */
+function valueToString(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", "");
+    }
+    // Handle DuckDB UUID objects (returned as {hugeint: string})
+    if ("hugeint" in val) {
+      // Convert 128-bit signed decimal to UUID hex string
+      // DuckDB XORs the high bit for sorting, so flip it back
+      let n = BigInt(val.hugeint);
+      if (n < 0n) n += 1n << 128n; // Convert from signed to unsigned
+      n ^= 1n << 127n; // Flip high bit (undo DuckDB's sort optimization)
+      const hex = n.toString(16).padStart(32, "0");
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    return JSON.stringify(val, (_, v) =>
+      typeof v === "bigint" ? v.toString() : v,
+    );
+  }
+  return String(val);
+}
+
+/**
+ * Format query results as TSV with header row
+ * @param {import("@duckdb/node-api").DuckDBResultReader} result
+ * @returns {string}
+ */
+function formatResultsTsv(result) {
+  const columnCount = result.columnCount;
+  if (columnCount === 0) return "";
+
+  const columnNames = [];
+  for (let i = 0; i < columnCount; i++) {
+    columnNames.push(result.columnName(i));
+  }
+  const rows = result.getRows();
+
+  const lines = [columnNames.join("\t")];
+  for (const row of rows) {
+    lines.push(row.map(valueToString).join("\t"));
+  }
+  return lines.join("\n");
+}
+
 /**
  * Format query results as a table string
  * @param {import("@duckdb/node-api").DuckDBResultReader} result
@@ -29,33 +82,7 @@ function formatResults(result) {
   }
 
   // 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", "");
-        }
-        // Handle DuckDB UUID objects (returned as {hugeint: string})
-        if ("hugeint" in val) {
-          // Convert 128-bit signed decimal to UUID hex string
-          // DuckDB XORs the high bit for sorting, so flip it back
-          let n = BigInt(val.hugeint);
-          if (n < 0n) n += 1n << 128n; // Convert from signed to unsigned
-          n ^= 1n << 127n; // Flip high bit (undo DuckDB's sort optimization)
-          const hex = n.toString(16).padStart(32, "0");
-          return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-        }
-        return JSON.stringify(val, (_, v) =>
-          typeof v === "bigint" ? v.toString() : v,
-        );
-      }
-      return String(val);
-    }),
-  );
+  const stringRows = rows.map((row) => row.map(valueToString));
 
   const widths = columnNames.map((name, i) => {
     const maxDataWidth = Math.max(
@@ -91,13 +118,13 @@ function formatResults(result) {
 export class QuerySession {
   /** @type {import("@duckdb/node-api").DuckDBConnection | undefined} */
   #connection;
-  /** @type {string} */
+  /** @type {string | string[]} */
   #filePattern;
   /** @type {QuerySessionInfo} */
   #info;
 
   /**
-   * @param {string} filePattern - Glob pattern for JSONL files
+   * @param {string | string[]} filePattern - Glob pattern(s) for JSONL files
    * @param {QuerySessionInfo} info - Session counts
    */
   constructor(filePattern, info) {
@@ -105,6 +132,19 @@ export class QuerySession {
     this.#info = info;
   }
 
+  /**
+   * Format file pattern for use in DuckDB SQL
+   * @returns {string} SQL expression for the file pattern
+   */
+  #formatFilePatternForSql() {
+    if (Array.isArray(this.#filePattern)) {
+      // DuckDB accepts a list of patterns: ['pattern1', 'pattern2']
+      const patterns = this.#filePattern.map((p) => `'${p}'`).join(", ");
+      return `[${patterns}]`;
+    }
+    return `'${this.#filePattern}'`;
+  }
+
   /**
    * Create a QuerySession from a project path
    * @param {string | null} projectDir - Claude projects dir, or null for all
@@ -158,6 +198,19 @@ export class QuerySession {
     return formatResults(result);
   }
 
+  /**
+   * Execute a SQL query and return TSV formatted string with header
+   * @param {string} sql
+   * @returns {Promise<string>} Query result as TSV
+   */
+  async queryTsv(sql) {
+    if (!this.#connection) {
+      throw new Error("Session not initialized - use QuerySession.create()");
+    }
+    const result = await this.#connection.runAndReadAll(sql);
+    return formatResultsTsv(result);
+  }
+
   /**
    * Execute a SQL query and return raw rows
    * @param {string} sql
@@ -290,7 +343,7 @@ export class QuerySession {
       regexp_extract(filename, '/projects/([^/]+)/', 1) as project,
       ordinality as rownum
     FROM read_ndjson(
-      '${this.#filePattern}',
+      ${this.#formatFilePatternForSql()},
       filename=true,
       ignore_errors=true,
       columns={${columnsDef}}
@@ -342,7 +395,7 @@ export class QuerySession {
     SELECT
       (json->>'uuid')::UUID as uuid,
       json as raw
-    FROM read_ndjson_objects('${this.#filePattern}', ignore_errors=true)
+    FROM read_ndjson_objects(${this.#formatFilePatternForSql()}, ignore_errors=true)
     WHERE json->>'uuid' IS NOT NULL AND length(json->>'uuid') > 0;
 
     -- Tool uses: All tool calls with unnested content blocks

package/src/repl.js

@@ -188,6 +188,7 @@ async function readStdin() {
 
 /**
  * Run queries from piped input (non-interactive mode)
+ * Uses TSV output format with --- separator between queries
  * @param {QuerySession} qs
  * @param {string} input
  */
@@ -198,12 +199,25 @@ async function runPipedQueries(qs, input) {
     .map((s) => s.trim())
     .filter((s) => s && s !== ";");
 
+  let isFirstOutput = true;
+
   for (const stmt of statements) {
     if (stmt.startsWith(".")) {
       const shouldExit = await handleDotCommand(stmt, qs);
       if (shouldExit) break;
     } else {
-      await executeQuery(qs, stmt);
+      try {
+        const result = await qs.queryTsv(stmt);
+        if (result) {
+          if (!isFirstOutput) {
+            console.log("---");
+          }
+          console.log(result);
+          isFirstOutput = false;
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+      }
     }
   }
 }

package/src/session-loader.js

@@ -42,7 +42,7 @@ function countSessionsAndAgents(files, sessionFilter = "") {
  * 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 }>}
+ * @returns {Promise<{ sessionCount: number, agentCount: number, projectCount: number, filePattern: string | string[] }>}
  */
 export async function getSessionFiles(claudeProjectsDir, sessionFilter = "") {
   // If no specific project, use all projects
@@ -72,8 +72,13 @@ export async function getSessionFiles(claudeProjectsDir, sessionFilter = "") {
     }
 
     // Use glob pattern for all projects (** for recursive matching)
+    // When session filter is provided, include both the filtered session AND its subagents
+    // Subagents are stored in {session_id}/subagents/*.jsonl
     const filePattern = sessionFilter
-      ? join(base, "*", `**/${sessionFilter}*.jsonl`)
+      ? [
+          join(base, "*", `${sessionFilter}*.jsonl`),
+          join(base, "*", `${sessionFilter}*/subagents/*.jsonl`),
+        ]
       : join(base, "*", "**/*.jsonl");
 
     return {
@@ -93,9 +98,14 @@ export async function getSessionFiles(claudeProjectsDir, sessionFilter = "") {
     return { sessionCount: 0, agentCount: 0, projectCount: 1, filePattern: "" };
   }
 
-  // Use glob pattern with ** for recursive matching
+  // Use glob pattern for matching
+  // When session filter is provided, include both the filtered session AND its subagents
+  // Subagents are stored in {session_id}/subagents/*.jsonl
   const filePattern = sessionFilter
-    ? join(claudeProjectsDir, `**/${sessionFilter}*.jsonl`)
+    ? [
+        join(claudeProjectsDir, `${sessionFilter}*.jsonl`),
+        join(claudeProjectsDir, `${sessionFilter}*/subagents/*.jsonl`),
+      ]
     : join(claudeProjectsDir, "**/*.jsonl");
 
   return {