cc-query 0.1.1 → 0.2.1

package/README.md

@@ -0,0 +1,55 @@
+# 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 [skill](https://gist.github.com/dannycoates/b4436fb77c9cfd2763028eee42d1d320) gives claude the ability and slash command `/reflect` to work with claude session history.
+
+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
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-query",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "SQL REPL for querying Claude Code session data",
   "type": "module",
   "exports": {
@@ -15,7 +15,7 @@
     "node": ">=24"
   },
   "bin": {
-    "cc-query": "./bin/cc-query.js"
+    "cc-query": "bin/cc-query.js"
   },
   "files": [
     "index.js",

package/src/query-session.js

@@ -91,13 +91,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 +105,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
@@ -290,7 +303,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,8 +355,105 @@ 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
+    CREATE OR REPLACE VIEW tool_uses AS
+    SELECT
+      m.uuid,
+      m.timestamp,
+      m.sessionId,
+      m.isAgent,
+      m.agentId,
+      m.project,
+      m.rownum,
+      block->>'name' as tool_name,
+      block->>'id' as tool_id,
+      block->'input' as tool_input,
+      row_number() OVER (PARTITION BY m.uuid ORDER BY (SELECT NULL)) - 1 as block_index
+    FROM assistant_messages m,
+    LATERAL UNNEST(CAST(message->'content' AS JSON[])) as t(block)
+    WHERE block->>'type' = 'tool_use';
+
+    -- Tool results: All tool results with duration
+    CREATE OR REPLACE VIEW tool_results AS
+    WITH array_messages AS (
+      SELECT * FROM user_messages
+      WHERE json_type(message->'content') = 'ARRAY'
+    )
+    SELECT
+      m.uuid,
+      m.timestamp,
+      m.sessionId,
+      m.isAgent,
+      m.agentId,
+      m.project,
+      m.rownum,
+      block->>'tool_use_id' as tool_use_id,
+      CAST(block->>'is_error' AS BOOLEAN) as is_error,
+      block->>'content' as result_content,
+      CAST(m.toolUseResult->>'durationMs' AS INTEGER) as duration_ms,
+      m.sourceToolAssistantUUID
+    FROM array_messages m,
+    LATERAL UNNEST(CAST(message->'content' AS JSON[])) as t(block)
+    WHERE block->>'type' = 'tool_result';
+
+    -- Token usage: Pre-cast token counts
+    CREATE OR REPLACE VIEW token_usage AS
+    SELECT
+      uuid,
+      timestamp,
+      sessionId,
+      isAgent,
+      agentId,
+      project,
+      message->>'model' as model,
+      message->>'stop_reason' as stop_reason,
+      CAST(message->'usage'->>'input_tokens' AS BIGINT) as input_tokens,
+      CAST(message->'usage'->>'output_tokens' AS BIGINT) as output_tokens,
+      CAST(message->'usage'->>'cache_read_input_tokens' AS BIGINT) as cache_read_tokens,
+      CAST(message->'usage'->>'cache_creation_input_tokens' AS BIGINT) as cache_creation_tokens
+    FROM assistant_messages
+    WHERE (message->'usage') IS NOT NULL;
+
+    -- Bash commands: Bash tool uses with extracted command
+    CREATE OR REPLACE VIEW bash_commands AS
+    SELECT
+      uuid,
+      timestamp,
+      sessionId,
+      isAgent,
+      agentId,
+      project,
+      rownum,
+      tool_id,
+      tool_input->>'command' as command,
+      tool_input->>'description' as description,
+      CAST(tool_input->>'timeout' AS INTEGER) as timeout,
+      CAST(tool_input->>'run_in_background' AS BOOLEAN) as run_in_background
+    FROM tool_uses
+    WHERE tool_name = 'Bash';
+
+    -- File operations: Read/Write/Edit/Glob/Grep with extracted paths
+    CREATE OR REPLACE VIEW file_operations AS
+    SELECT
+      uuid,
+      timestamp,
+      sessionId,
+      isAgent,
+      agentId,
+      project,
+      rownum,
+      tool_id,
+      tool_name,
+      COALESCE(
+        tool_input->>'file_path',
+        tool_input->>'path'
+      ) as file_path,
+      tool_input->>'pattern' as pattern
+    FROM tool_uses
+    WHERE tool_name IN ('Read', 'Write', 'Edit', 'Glob', 'Grep');
   `;
   }
 }

package/src/repl.js

@@ -52,15 +52,22 @@ function getHelpText() {
   return `
 Commands:
   .help, .h      Show this help
-  .schema, .s    Show table schema (runs DESCRIBE messages)
+  .schema, .s    Show schemas for all views
   .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
+  human_messages      Human-typed messages (excludes tool results)
   assistant_messages  Assistant messages with error, requestId, etc.
   system_messages     System messages with hooks, retry info, etc.
+  raw_messages        Raw JSON for each message by uuid
+  tool_uses           All tool calls with unnested content blocks
+  tool_results        Tool results with duration and error status
+  token_usage         Token counts per assistant message
+  bash_commands       Bash tool calls with extracted command
+  file_operations     Read/Write/Edit/Glob/Grep with file paths
 
 Example queries:
   -- Count messages by type
@@ -137,7 +144,23 @@ async function handleDotCommand(command, qs) {
   }
 
   if (cmd === ".schema" || cmd === ".s") {
-    await executeQuery(qs, "DESCRIBE messages");
+    const views = [
+      "messages",
+      "user_messages",
+      "human_messages",
+      "assistant_messages",
+      "system_messages",
+      "raw_messages",
+      "tool_uses",
+      "tool_results",
+      "token_usage",
+      "bash_commands",
+      "file_operations",
+    ];
+    for (const view of views) {
+      console.log(`\n=== ${view} ===`);
+      await executeQuery(qs, `DESCRIBE ${view}`);
+    }
     return false;
   }
 

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 {