@gswangg/duncan-cc 0.1.0 → 0.2.0

package/README.md

@@ -30,71 +30,206 @@ claude mcp add duncan -- npx tsx /path/to/duncan-cc/src/mcp-server.ts
 
 ## Authentication
 
-Duncan resolves auth automatically:
+Duncan resolves auth automatically in this order:
 
-1. Explicit apiKey/token parameter
-2. CC OAuth credentials (`~/.claude/.credentials.json`)
-3. `ANTHROPIC_API_KEY` environment variable
+1. **Explicit** apiKey/token parameter (if passed)
+2. **CC OAuth** credentials from `~/.claude/.credentials.json` (primary for CC users)
+3. **API key** from `ANTHROPIC_API_KEY` environment variable
+
+Most CC users authenticate via OAuth — duncan picks this up automatically with no configuration.
 
 ## Tools
 
+Duncan exposes three MCP tools:
+
 ### `duncan_query`
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `question` | string | ✓ | The question to ask |
-| `mode` | string | ✓ | `project`, `global`, `session`, `self`, `ancestors` |
-| `projectDir` | string | | For project mode |
-| `sessionId` | string | | For session mode |
-| `cwd` | string | | Working directory for context resolution |
-| `limit` | number | | Max sessions/windows (default: 10) |
-| `offset` | number | | Pagination offset |
-| `copies` | number | | For self mode: sample count (default: 3) |
-| `includeSubagents` | boolean | | Include subagent transcripts |
+Query dormant sessions to recall information from previous conversations. Loads session context and asks the target session's model whether it has relevant information.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `question` | string | ✓ | — | The question to ask. Be specific and self-contained. |
+| `mode` | string | ✓ | — | Routing mode (see [Routing Modes](#routing-modes) below) |
+| `projectDir` | string | | cwd-based | Explicit project directory path (for `project` and `branch` modes) |
+| `sessionId` | string | | — | Session file path or ID (for `session` mode) |
+| `cwd` | string | | process.cwd() | Working directory for context resolution |
+| `limit` | number | | 10 | Max sessions/windows to query |
+| `offset` | number | | 0 | Skip this many sessions for pagination |
+| `copies` | number | | 3 | For `self` mode: number of parallel samples |
+| `includeSubagents` | boolean | | false | Include subagent transcripts in search |
+| `batchSize` | number | | 5 | Max concurrent API calls per batch |
+| `gitBranch` | string | | auto-detected | For `branch` mode: explicit branch name |
+
+### `duncan_projects`
+
+List all CC projects with metadata. Use to discover what projects exist before targeting a specific project with `duncan_query`.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `limit` | number | | 50 | Max projects to list |
+| `offset` | number | | 0 | Pagination offset |
+
+Returns for each project:
+- Original working directory path (reconstructed from CC's hashed directory name)
+- Session count
+- Most recent activity timestamp
+- Git branches seen across recent sessions
 
 ### `duncan_list_sessions`
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `mode` | string | ✓ | `project` or `global` |
-| `projectDir` | string | | For project mode |
-| `cwd` | string | | Working directory |
-| `limit` | number | | Max sessions (default: 20) |
+List available sessions for a project or globally.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `mode` | string | ✓ | — | `project` or `global` |
+| `projectDir` | string | | cwd-based | For `project` mode |
+| `cwd` | string | | process.cwd() | Working directory |
+| `limit` | number | | 20 | Max sessions to list |
+
+## Routing Modes
+
+### `project`
+
+Query all sessions from the same project directory. The calling session is automatically excluded via self-detection. Sessions are ordered by modification time (newest first).
+
+Use when you want to search through recent work in the current project.
+
+### `global`
+
+Query all sessions across all CC projects (newest first). Self-excluded. The broadest search — useful when you don't know which project holds the information.
+
+### `session`
+
+Query a specific session by ID or file path. No self-exclusion (you might intentionally target a known session). Pass the session ID via the `sessionId` parameter — either a UUID or full file path.
+
+### `self`
 
-## Routing modes
+Query your own active window multiple times for **sampling diversity**. Instead of searching other sessions, this sends the same question to N independent copies of the current conversation context. Useful for exploring different perspectives on complex problems.
 
-| Mode | Target |
-|------|--------|
-| `project` | Sessions from same project dir (self-excluded) |
-| `global` | All sessions across all projects (self-excluded) |
-| `session` | Specific session by ID or path |
-| `self` | Own active window, queried N times for sampling diversity |
-| `ancestors` | Own prior compaction windows (excluding active) |
+Uses a **two-wave cache strategy**:
+1. **Wave 1**: 1 query primes the prompt cache (pays full input token cost)
+2. **Wave 2**: remaining N-1 queries in parallel (hit cached prefix, ~90% cheaper)
 
-## How it works
+The `copies` parameter controls how many samples to take (default: 3).
 
-Duncan replicates CC's full session-to-API pipeline, then substitutes its own query:
+### `ancestors`
 
-1. Parse JSONL session file
-2. Relink preserved segments (compaction tree surgery)
-3. Walk parentUuid chain from leaf to root
-4. Post-process (merge split assistants, fix orphan tool results)
-5. Normalize messages (filter, convert types, merge, 8 post-transforms)
-6. Apply content replacements (persisted outputs from disk)
-7. Microcompact (truncate old tool results)
-8. Inject userContext (CLAUDE.md + date)
-9. Build system prompt (full parity with CC's static sections + dynamic context from project dir)
-10. Convert to API format
-11. Add prompt caching breakpoints
-12. Query with `duncan_response` structured output tool
+Query the calling session's **prior compaction windows**. When CC compacts a session, the old context is summarized but the original messages remain in the JSONL file. Ancestors mode lets you query that pre-compaction context.
 
-Self-exclusion: the calling session is identified by scanning for the MCP `toolUseId` in session file tails — deterministic, zero config, swarm-safe.
+Returns nothing if the session has no compaction boundaries. In CC (which has no dfork lineage), "ancestors" always means the session's own compacted-away history.
+
+### `subagents`
+
+Query **subagent transcripts** of the calling session. When CC spawns subagent tasks (e.g., parallel tool calls), their transcripts are stored alongside the main session. This mode searches through those transcripts.
+
+Subagent files are sorted by modification time for deterministic pagination.
+
+### `branch`
+
+Query all sessions in the same project that share the **same git branch** as the calling session. CC records `gitBranch` in JSONL entries, so this grouping works without explicit lineage metadata.
+
+Useful when work on a feature spans multiple sessions — `branch` naturally groups them by the git branch they were on.
+
+If the calling session's branch can't be auto-detected, pass it explicitly via the `gitBranch` parameter.
+
+## How It Works
+
+### Pipeline
+
+Duncan replicates CC's full session-to-API message pipeline, then substitutes its own query as the final message:
+
+```
+Session file (.jsonl)
+  │
+  ▼ Parse JSONL — separate transcript from metadata
+  ▼ Relink preserved segments (compaction tree surgery)
+  ▼ Walk parentUuid chain from leaf to root
+  ▼ Post-process (merge split assistants, fix orphan tool results)
+  ▼ Slice from last compaction boundary
+  ▼ Normalize messages (filter, convert types, merge, 8 post-transforms)
+  ▼ Content replacements (resolve persisted tool outputs from disk)
+  ▼ Microcompact (truncate old tool results)
+  ▼ Inject userContext (CLAUDE.md + date)
+  ▼ Build system prompt (full CC parity)
+  ▼ Convert to API format
+  ▼ Add prompt cache breakpoints
+  ▼ Append duncan question as final user message
+  ▼ Query with duncan_response structured output tool
+```
+
+### Self-Exclusion
+
+When CC calls an MCP tool, it writes the assistant message (containing the `tool_use` block) to the session JSONL *before* invoking the tool. CC passes the tool_use ID in the MCP request's `_meta` as `claudecode/toolUseId`.
+
+Duncan scans the last 32KB of candidate session files for this ID to deterministically identify the calling session — no configuration needed, safe for concurrent sessions.
+
+### System Prompt Reconstruction
+
+Duncan rebuilds the system prompt with full parity to CC's own prompt:
+
+**Static sections** (embedded verbatim from CC):
+- Identity/intro, system rules, coding instructions
+- Careful actions guidelines, tool usage, tone/style, output efficiency
+
+**Dynamic sections** (reconstructed from session context):
+- **Environment**: from session JSONL metadata (cwd, model) + local filesystem
+- **CLAUDE.md**: loaded from session's original cwd hierarchy (if paths exist)
+- **Memory**: from CC project directory (`~/.claude/projects/<hash>/memory/MEMORY.md`)
+- **Tool-conditional instructions**: only included when the corresponding tools appear in the session (e.g., "use Read instead of cat" only when Read tool was used)
+- **Language**: configurable
+
+Tool schemas are NOT included — duncan sends only its own `duncan_response` tool. The session's original tools aren't callable during a duncan query.
+
+### Prompt Caching
+
+Cache breakpoints placed on:
+- **System prompt**: each text block gets `cache_control: { type: "ephemeral" }`
+- **Messages**: breakpoint on last content block of penultimate message
+
+This caches the session context (stable across queries) while letting the duncan question (last message) vary without invalidating cache. For multi-session batch queries, each session's context is cached independently.
+
+### Query Logging
+
+Every query is logged to `~/.claude/duncan.jsonl` as append-only JSONL. Each record captures:
+
+- Batch ID, question, answer, hasContext flag
+- Target session, window index, source session
+- Routing strategy, model used
+- Token counts (input, output, cache creation, cache read)
+- Latency in milliseconds, timestamp
+
+Process with standard tools: `cat ~/.claude/duncan.jsonl | jq .`
+
+### Progress Notifications
+
+During batch queries, duncan sends MCP progress notifications via the standard `progressToken` mechanism. As each session window completes, a notification is sent so the calling session can display real-time status (e.g., "Querying 3/7 sessions...").
+
+## Session Storage Layout
+
+Duncan reads CC's native session storage:
+
+```
+~/.claude/
+├── .credentials.json          # OAuth credentials
+├── duncan.jsonl               # Query log (written by duncan)
+└── projects/
+    └── <hashed-cwd>/          # e.g., -Users-foo-bar
+        ├── <session-id>.jsonl # Session transcript
+        ├── <session-id>/
+        │   ├── subagents/     # Subagent transcripts
+        │   │   └── <subdir>/
+        │   │       └── agent-<id>.jsonl
+        │   └── tool-results/  # Persisted tool outputs
+        │       └── <id>.txt
+        └── memory/
+            └── MEMORY.md      # Project memory
+```
 
-## Known gaps
+## Known Gaps
 
-- **MCP server instructions** — not available for dormant sessions (fetched live, not persisted)
-- **Tool schemas** — only `duncan_response` is sent; session's original tools aren't callable
-- **Compaction test coverage** — synthetic tests only; no real compacted sessions in test corpus
+- **MCP server instructions** — CC injects MCP server `instructions` from the initialize handshake into the system prompt. These aren't persisted to disk, so duncan can't reconstruct them for dormant sessions. Equivalent to resuming a CC session with tools disconnected.
+- **Tool schemas** — only `duncan_response` is sent; the session's original tools aren't callable during a duncan query.
+- **Compaction test coverage** — compaction logic is tested with synthetic fixtures only. No real compacted sessions in the current test corpus (CC's 30-day `cleanupPeriodDays` default purged them before capture).
 
 ## Tests
 
@@ -106,5 +241,5 @@ Corpus-dependent tests skip gracefully when `testdata/` is absent.
 
 ## Related
 
-- [duncan-pi](https://github.com/gswangg/duncan-pi) — duncan for the [pi](https://github.com/badlogic/pi-mono) coding agent
+- [duncan-pi](https://github.com/gswangg/duncan-pi) — Duncan for the [pi](https://github.com/badlogic/pi-mono) coding agent
 - [The Duncan Idaho Approach to Agent Memory](https://gswangg.net/posts/duncan-idaho-agent-memory) — design writeup

package/SPEC.md

@@ -4,7 +4,8 @@
 
 Duncan-cc replicates CC's full message pipeline to hydrate dormant CC sessions,
 then queries them with questions via the Anthropic API. Exposed as an MCP server
-(stdio transport) with two tools: `duncan_query` and `duncan_list_sessions`.
+(stdio transport) with three tools: `duncan_query`, `duncan_projects`, and
+`duncan_list_sessions`.
 
 ## Pipeline: Disk → API
 
@@ -63,7 +64,7 @@ Build system prompt (full parity with CC):
   ├── System rules
   ├── Coding instructions
   ├── Careful actions guidelines
-  ├── Tool usage
+  ├── Tool usage (+ per-tool instructions based on session's tools)
   ├── Tone and style
   ├── Output efficiency
   ├── Environment info (cwd, platform, model)
@@ -95,6 +96,8 @@ messages.create() with duncan_response tool
 | `session` | Specific session by ID/path | — |
 | `self` | Own active window, N copies (sampling diversity) | — (queries self intentionally) |
 | `ancestors` | Own prior compaction windows (excluding active) | Active window excluded |
+| `subagents` | Subagent transcripts of the active session | — |
+| `branch` | Sessions sharing the same git branch in the project | ✅ via toolUseId |
 
 ### Self-exclusion
 
@@ -116,6 +119,13 @@ Queries compaction windows of the calling session excluding the active window.
 Returns nothing if the session has no compaction boundaries. In CC (no dfork
 lineage), "ancestors" = the compacted-away context from the current session.
 
+### Branch mode
+
+Collects all sessions from the same project directory that share a git branch
+with the calling session, ordered by mtime. CC sessions store `gitBranch` in
+their JSONL entries. If the calling session's branch can't be auto-detected,
+it can be passed explicitly via the `gitBranch` parameter.
+
 ## Authentication
 
 Resolution order:
@@ -151,6 +161,24 @@ This matches CC's own resume behavior: rebuild system prompt from current state.
 Note: tool schemas are NOT included — duncan sends only its own `duncan_response`
 tool. The session's original tools are not callable during a duncan query.
 
+## Query Logging
+
+Every query is logged to `~/.claude/duncan.jsonl` as append-only JSONL. Each record:
+- `batchId`, `question`, `answer`, `hasContext`
+- `targetSession`, `windowIndex`, `sourceSession`
+- `strategy`, `model`
+- `inputTokens`, `outputTokens`, `cacheCreationInputTokens`, `cacheReadInputTokens`
+- `latencyMs`, `timestamp`
+
+Logging is best-effort (failures don't break queries).
+
+## MCP Progress Notifications
+
+During batch queries, progress notifications are sent via MCP's standard
+`progressToken` mechanism. Each completed session window sends a notification
+with `{ progress: completed, total: totalWindows }`. Requires the caller to
+include `_meta.progressToken` in the request.
+
 ## Known Gaps
 
 ### MCP Server Instructions
@@ -172,22 +200,32 @@ Compaction logic is tested with synthetic fixtures only.
 - **Subagent transcripts**: `<project-dir>/<session-id>/subagents/<subdir>/agent-<id>.jsonl`
 - **Tool results**: `<project-dir>/<session-id>/tool-results/<id>.txt`
 - **Memory**: `<project-dir>/memory/MEMORY.md`
+- **Query log**: `~/.claude/duncan.jsonl`
 
 ## MCP Server
 
-Two tools exposed via stdio transport:
+Three tools exposed via stdio transport:
 
 ### duncan_query
 Query dormant sessions. Parameters:
 - `question` (required): the question to ask
-- `mode` (required): `project`, `global`, `session`, `self`, `ancestors`
-- `projectDir`: for project mode
+- `mode` (required): `project`, `global`, `session`, `self`, `ancestors`, `subagents`, `branch`
+- `projectDir`: for project/branch mode
 - `sessionId`: for session mode
 - `cwd`: working directory context
 - `limit`: max sessions/windows (default: 10)
 - `offset`: pagination offset
 - `copies`: for self mode, number of samples (default: 3)
 - `includeSubagents`: include subagent transcripts (default: false)
+- `batchSize`: max concurrent API calls per batch (default: 5)
+- `gitBranch`: for branch mode, explicit branch name
+
+### duncan_projects
+List all CC projects with metadata. Parameters:
+- `limit`: max projects (default: 50)
+- `offset`: pagination offset
+
+Returns: project cwd, session count, last activity, git branches.
 
 ### duncan_list_sessions
 List available sessions. Parameters:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gswangg/duncan-cc",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Query dormant Claude Code sessions — the Duncan Idaho approach to agent memory, for CC.",
   "type": "module",
   "bin": {

package/src/discovery.ts

@@ -9,7 +9,7 @@
  * Also discovers subagent transcripts.
  */
 
-import { readdirSync, statSync, existsSync, openSync, readSync, closeSync } from "node:fs";
+import { readdirSync, statSync, existsSync, openSync, readSync, closeSync, readFileSync } from "node:fs";
 import { join, basename, dirname } from "node:path";
 import { homedir } from "node:os";
 
@@ -148,14 +148,144 @@ export function listSubagentFiles(sessionFile: string): SessionFileInfo[] {
     scanDir(sessionDir);
   } catch {}
 
+  // Sort by mtime, newest first (deterministic ordering)
+  files.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
   return files;
 }
 
+// ============================================================================
+// Git branch extraction
+// ============================================================================
+
+/** Size of head chunk to scan for gitBranch (bytes). */
+const HEAD_SCAN_BYTES = 8_192;
+
+/**
+ * Extract git branch(es) from a session file by scanning the head.
+ * Returns unique branches found. Scans only the first HEAD_SCAN_BYTES
+ * since gitBranch appears in the earliest entries.
+ */
+export function extractGitBranches(filePath: string): string[] {
+  try {
+    const stat = statSync(filePath);
+    const readSize = Math.min(stat.size, HEAD_SCAN_BYTES);
+    const buf = Buffer.alloc(readSize);
+    const fd = openSync(filePath, "r");
+    readSync(fd, buf, 0, readSize, 0);
+    closeSync(fd);
+
+    const text = buf.toString("utf-8");
+    const branches = new Set<string>();
+    const re = /"gitBranch":"([^"]+)"/g;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+      branches.add(match[1]);
+    }
+    return [...branches];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Extract the primary git branch for a session (first found).
+ */
+export function extractGitBranch(filePath: string): string | null {
+  const branches = extractGitBranches(filePath);
+  return branches.length > 0 ? branches[0] : null;
+}
+
+// ============================================================================
+// Project listing
+// ============================================================================
+
+export interface ProjectInfo {
+  /** The hashed project directory name (e.g., "-Users-foo-bar") */
+  dirName: string;
+  /** Full path to the project directory under ~/.claude/projects/ */
+  projectDir: string;
+  /** Reconstructed original working directory path */
+  cwd: string;
+  /** Number of sessions in this project */
+  sessionCount: number;
+  /** Most recent session activity */
+  lastActivity: Date;
+  /** Git branches seen across sessions */
+  branches: string[];
+}
+
+/**
+ * Reconstruct the original cwd from a CC project directory name.
+ * CC hashes cwd by replacing `/` with `-`, so `/Users/foo/bar` → `-Users-foo-bar`.
+ */
+function cwdFromDirName(dirName: string): string {
+  // Replace leading - and all subsequent - with /
+  // This is lossy if the original path contained hyphens, but it's the best we can do
+  return dirName.replace(/-/g, "/");
+}
+
+/**
+ * List all CC projects with metadata.
+ */
+export function listProjects(opts?: { limit?: number; offset?: number }): {
+  projects: ProjectInfo[];
+  totalCount: number;
+  hasMore: boolean;
+} {
+  const projectsDir = getProjectsDir();
+  if (!existsSync(projectsDir)) {
+    return { projects: [], totalCount: 0, hasMore: false };
+  }
+
+  const allProjects: ProjectInfo[] = [];
+
+  try {
+    const dirs = readdirSync(projectsDir, { withFileTypes: true });
+    for (const d of dirs) {
+      if (!d.isDirectory()) continue;
+      const fullPath = join(projectsDir, d.name);
+      const sessions = listSessionFiles(fullPath);
+      if (sessions.length === 0) continue;
+
+      // Collect branches from recent sessions (scan up to 5 for efficiency)
+      const branchSet = new Set<string>();
+      for (const s of sessions.slice(0, 5)) {
+        for (const b of extractGitBranches(s.path)) {
+          branchSet.add(b);
+        }
+      }
+
+      allProjects.push({
+        dirName: d.name,
+        projectDir: fullPath,
+        cwd: cwdFromDirName(d.name),
+        sessionCount: sessions.length,
+        lastActivity: sessions[0].mtime, // sessions already sorted newest-first
+        branches: [...branchSet],
+      });
+    }
+  } catch {
+    return { projects: [], totalCount: 0, hasMore: false };
+  }
+
+  // Sort by last activity, newest first
+  allProjects.sort((a, b) => b.lastActivity.getTime() - a.lastActivity.getTime());
+
+  const limit = opts?.limit ?? 50;
+  const offset = opts?.offset ?? 0;
+  const page = allProjects.slice(offset, offset + limit);
+  return {
+    projects: page,
+    totalCount: allProjects.length,
+    hasMore: offset + limit < allProjects.length,
+  };
+}
+
 // ============================================================================
 // Routing
 // ============================================================================
 
-export type RoutingMode = "project" | "global" | "session" | "self" | "ancestors";
+export type RoutingMode = "project" | "global" | "session" | "self" | "ancestors" | "subagents" | "branch";
 
 export interface RoutingParams {
   mode: RoutingMode;
@@ -171,6 +301,10 @@ export interface RoutingParams {
   limit?: number;
   /** Offset for pagination */
   offset?: number;
+  /** For "branch" mode: explicit git branch (auto-detected from calling session if omitted) */
+  gitBranch?: string;
+  /** Tool use ID from MCP _meta (used for self-exclusion and branch detection) */
+  toolUseId?: string;
 }
 
 export interface RoutingResult {
@@ -232,6 +366,45 @@ export function resolveSessionFiles(params: RoutingParams): RoutingResult {
       break;
     }
 
+    case "branch": {
+      // Find all sessions in the same project that share a git branch with the current session.
+      // Requires toolUseId to identify the calling session, or an explicit gitBranch param.
+      const projectDir = params.projectDir ?? (params.cwd ? getProjectDir(params.cwd) : null);
+      if (!projectDir) {
+        return { sessions: [], totalCount: 0, hasMore: false };
+      }
+
+      const projectSessions = listSessionFiles(projectDir);
+      let targetBranch: string | null = null;
+
+      // If we have a toolUseId, find the calling session's branch
+      if (params.toolUseId) {
+        const callingId = findCallingSession(params.toolUseId, projectSessions);
+        if (callingId) {
+          const callingSession = projectSessions.find(s => s.sessionId === callingId);
+          if (callingSession) {
+            targetBranch = extractGitBranch(callingSession.path);
+          }
+        }
+      }
+
+      // Fallback: use the explicit gitBranch param
+      if (!targetBranch && params.gitBranch) {
+        targetBranch = params.gitBranch;
+      }
+
+      if (!targetBranch) {
+        return { sessions: [], totalCount: 0, hasMore: false };
+      }
+
+      // Filter to sessions that share the same branch
+      allSessions = projectSessions.filter(s => {
+        const branches = extractGitBranches(s.path);
+        return branches.includes(targetBranch!);
+      });
+      break;
+    }
+
     default:
       return { sessions: [], totalCount: 0, hasMore: false };
   }
@@ -317,7 +490,7 @@ export function findCallingSession(
  * and exclude the calling session from results.
  */
 export function resolveSessionFilesExcludingSelf(
-  params: RoutingParams & { toolUseId?: string },
+  params: RoutingParams,
 ): RoutingResult & { excludedSessionId: string | null } {
   const result = resolveSessionFiles(params);
 

package/src/mcp-server.ts

@@ -19,15 +19,15 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { processSessionFile, processSessionWindows } from "./pipeline.js";
-import { resolveSessionFiles, resolveSessionFilesExcludingSelf, getProjectsDir, listAllSessionFiles } from "./discovery.js";
-import { querySingleWindow, queryBatch, querySelf, queryAncestors } from "./query.js";
+import { resolveSessionFiles, resolveSessionFilesExcludingSelf, getProjectsDir, listAllSessionFiles, listProjects, extractGitBranch } from "./discovery.js";
+import { querySingleWindow, queryBatch, querySelf, queryAncestors, querySubagents } from "./query.js";
 
 // ============================================================================
 // Server setup
 // ============================================================================
 
 const server = new Server(
-  { name: "duncan-cc", version: "0.1.0" },
+  { name: "duncan-cc", version: "0.2.0" },
   { capabilities: { tools: {} } },
 );
 
@@ -52,13 +52,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           mode: {
             type: "string",
-            enum: ["project", "global", "session", "self", "ancestors"],
+            enum: ["project", "global", "session", "self", "ancestors", "subagents", "branch"],
             description:
               "Routing mode. 'project': sessions from a specific project dir. " +
               "'global': all sessions across all projects (newest first). " +
               "'session': a specific session file. " +
               "'self': query own active window N times for sampling diversity. " +
-              "'ancestors': query own prior compaction windows (excluding active).",
+              "'ancestors': query own prior compaction windows (excluding active). " +
+              "'subagents': query subagent transcripts of the active session. " +
+              "'branch': sessions from the same project that share the current git branch.",
           },
           projectDir: {
             type: "string",
@@ -88,10 +90,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             type: "number",
             description: "For 'self' mode: number of parallel queries for sampling diversity (default: 3).",
           },
+          batchSize: {
+            type: "number",
+            description: "Max concurrent API calls per batch (default: 5).",
+          },
+          gitBranch: {
+            type: "string",
+            description: "For 'branch' mode: explicit git branch name. If omitted, uses the calling session's branch.",
+          },
         },
         required: ["question", "mode"],
       },
     },
+    {
+      name: "duncan_projects",
+      description:
+        "List all Claude Code projects with metadata. Use to discover what projects exist " +
+        "before targeting a specific project with duncan_query. Returns project directories, " +
+        "session counts, last activity timestamps, and git branches.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          limit: {
+            type: "number",
+            description: "Max projects to list (default: 50).",
+          },
+          offset: {
+            type: "number",
+            description: "Pagination offset (default: 0).",
+          },
+        },
+        required: [],
+      },
+    },
     {
       name: "duncan_list_sessions",
       description: "List available Claude Code sessions. Use to discover sessions before querying.",
@@ -130,11 +161,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args, _meta } = request.params;
 
   // CC passes tool_use ID in _meta — used for self-exclusion
-  const toolUseId = (_meta as Record<string, unknown> | undefined)?.["claudecode/toolUseId"] as string | undefined;
+  const meta = _meta as Record<string, unknown> | undefined;
+  const toolUseId = meta?.["claudecode/toolUseId"] as string | undefined;
+  const progressToken = meta?.progressToken as string | number | undefined;
 
   switch (name) {
     case "duncan_query":
-      return handleDuncanQuery(args as any, toolUseId);
+      return handleDuncanQuery(args as any, toolUseId, progressToken);
+    case "duncan_projects":
+      return handleListProjects(args as any);
     case "duncan_list_sessions":
       return handleListSessions(args as any);
     default:
@@ -145,6 +180,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
+/**
+ * Send an MCP progress notification if a progressToken was provided.
+ */
+async function sendProgress(progressToken: string | number | undefined, progress: number, total: number): Promise<void> {
+  if (progressToken === undefined) return;
+  try {
+    await server.notification({
+      method: "notifications/progress",
+      params: { progressToken, progress, total },
+    });
+  } catch {
+    // Best-effort — don't let progress notifications break queries
+  }
+}
+
 async function handleDuncanQuery(args: {
   question: string;
   mode: string;
@@ -155,7 +205,9 @@ async function handleDuncanQuery(args: {
   offset?: number;
   includeSubagents?: boolean;
   copies?: number;
-}, toolUseId?: string) {
+  batchSize?: number;
+  gitBranch?: string;
+}, toolUseId?: string, progressToken?: string | number) {
   try {
     // Self mode: query own active window N times for sampling diversity
     if (args.mode === "self") {
@@ -168,7 +220,9 @@ async function handleDuncanQuery(args: {
       const result = await querySelf(args.question, {
         toolUseId,
         copies: args.copies ?? 3,
+        batchSize: args.batchSize,
         apiKey: undefined,
+        onProgress: (completed, total) => sendProgress(progressToken, completed, total),
       });
 
       if (result.results.length === 0) {
@@ -201,7 +255,9 @@ async function handleDuncanQuery(args: {
         toolUseId,
         limit: args.limit ?? 50,
         offset: args.offset ?? 0,
+        batchSize: args.batchSize,
         apiKey: undefined,
+        onProgress: (completed, total) => sendProgress(progressToken, completed, total),
       });
 
       if (result.results.length === 0) {
@@ -232,6 +288,58 @@ async function handleDuncanQuery(args: {
       return { content: [{ type: "text", text: parts.join("") }] };
     }
 
+    // Subagents mode: query subagent transcripts of the calling session
+    if (args.mode === "subagents") {
+      if (!toolUseId) {
+        return {
+          content: [{ type: "text", text: "Subagents mode requires toolUseId from _meta (only available when called from CC)." }],
+          isError: true,
+        };
+      }
+      const result = await querySubagents(args.question, {
+        toolUseId,
+        limit: args.limit ?? 50,
+        offset: args.offset ?? 0,
+        batchSize: args.batchSize,
+        apiKey: undefined,
+        onProgress: (completed, total) => sendProgress(progressToken, completed, total),
+      });
+
+      if (result.results.length === 0) {
+        return {
+          content: [{ type: "text", text: "No subagent transcripts found for this session." }],
+        };
+      }
+
+      const errors = result.results.filter(r => r.result.answer.startsWith("Error: "));
+      const nonErrors = result.results.filter(r => !r.result.answer.startsWith("Error: "));
+      const withContext = nonErrors.filter(r => r.result.hasContext);
+      const relevant = withContext.length > 0 ? withContext : nonErrors.length > 0 ? nonErrors : result.results;
+
+      const answers = relevant.map((r) => {
+        const label = relevant.length === 1 ? "" : `### ${r.sessionId.slice(0, 20)} (window ${r.windowIndex})\n`;
+        return `${label}${r.result.answer}\n*— ${r.model}*`;
+      }).join("\n\n---\n\n");
+
+      const parts = [`**${args.question}**\n\n${answers}`];
+
+      if (errors.length > 0) {
+        const errorLines = errors.map(r => `- ${r.sessionId.slice(0, 20)} (window ${r.windowIndex}): ${r.result.answer}`).join("\n");
+        parts.push(`\n\n---\n**${errors.length} error(s):**\n${errorLines}`);
+      }
+
+      if (result.hasMore) {
+        const nextOffset = (args.offset ?? 0) + (args.limit ?? 50);
+        const remaining = result.totalWindows - nextOffset;
+        parts.push(`\n\n---\n*Queried ${result.results.length} of ${result.totalWindows} windows. ${remaining} more available — call again with offset: ${nextOffset}.*`);
+      }
+
+      const contextCount = withContext.length;
+      parts.push(`\n\n*${contextCount}/${result.results.length} subagent windows had relevant context. queryId: ${result.queryId}*`);
+
+      return { content: [{ type: "text", text: parts.join("") }] };
+    }
+
     const result = await queryBatch(
       args.question,
       {
@@ -242,10 +350,13 @@ async function handleDuncanQuery(args: {
         limit: args.limit ?? 10,
         offset: args.offset ?? 0,
         includeSubagents: args.includeSubagents ?? false,
-        toolUseId, // for self-exclusion
+        toolUseId, // for self-exclusion + branch detection
+        gitBranch: args.gitBranch,
       },
       {
         apiKey: undefined,
+        batchSize: args.batchSize,
+        onProgress: (completed, total) => sendProgress(progressToken, completed, total),
       },
     );
 
@@ -300,6 +411,37 @@ async function handleDuncanQuery(args: {
   }
 }
 
+async function handleListProjects(args: {
+  limit?: number;
+  offset?: number;
+}) {
+  try {
+    const result = listProjects({ limit: args.limit, offset: args.offset });
+
+    if (result.projects.length === 0) {
+      return {
+        content: [{ type: "text", text: "No projects found." }],
+      };
+    }
+
+    const lines = result.projects.map((p) => {
+      const date = p.lastActivity.toISOString().slice(0, 16);
+      const branches = p.branches.length > 0 ? p.branches.join(", ") : "—";
+      return `${p.cwd}\n  sessions: ${p.sessionCount}  last: ${date}  branches: ${branches}`;
+    });
+
+    const header = `${result.totalCount} projects${result.hasMore ? ` (showing ${result.projects.length})` : ""}:`;
+    return {
+      content: [{ type: "text", text: `${header}\n\n${lines.join("\n\n")}` }],
+    };
+  } catch (err: any) {
+    return {
+      content: [{ type: "text", text: `Error listing projects: ${err.message}` }],
+      isError: true,
+    };
+  }
+}
+
 async function handleListSessions(args: {
   mode: string;
   projectDir?: string;

package/src/query-logger.ts

@@ -0,0 +1,117 @@
+/**
+ * Duncan Query Logger
+ * 
+ * Appends structured records to ~/.claude/duncan.jsonl for every query.
+ * Captures tokens, latency, cache hits, routing strategy, and results.
+ * Append-only JSONL — easy to process with standard tools.
+ */
+
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DuncanLogRecord {
+  /** Batch ID grouping related queries */
+  batchId: string;
+  /** The question asked */
+  question: string;
+  /** The answer returned */
+  answer: string;
+  /** Whether the session had relevant context */
+  hasContext: boolean;
+  /** Target session ID */
+  targetSession: string;
+  /** Window index within the session */
+  windowIndex: number;
+  /** Source session ID (the calling session, if known) */
+  sourceSession: string | null;
+  /** Routing strategy used */
+  strategy: string;
+  /** Model used for the query */
+  model: string;
+  /** Input tokens consumed */
+  inputTokens: number;
+  /** Output tokens generated */
+  outputTokens: number;
+  /** Cache creation input tokens */
+  cacheCreationInputTokens: number;
+  /** Cache read input tokens */
+  cacheReadInputTokens: number;
+  /** Query latency in milliseconds */
+  latencyMs: number;
+  /** ISO timestamp */
+  timestamp: string;
+}
+
+// ============================================================================
+// Logger
+// ============================================================================
+
+let logPath: string | null = null;
+
+function getLogPath(): string {
+  if (!logPath) {
+    const claudeDir = join(homedir(), ".claude");
+    if (!existsSync(claudeDir)) {
+      mkdirSync(claudeDir, { recursive: true });
+    }
+    logPath = join(claudeDir, "duncan.jsonl");
+  }
+  return logPath;
+}
+
+/**
+ * Record a single query result to the log file.
+ */
+export function recordQuery(record: DuncanLogRecord): void {
+  try {
+    const line = JSON.stringify(record) + "\n";
+    appendFileSync(getLogPath(), line, "utf-8");
+  } catch {
+    // Logging is best-effort — don't let it break queries
+  }
+}
+
+/**
+ * Helper to create a log record from query context.
+ */
+export function buildLogRecord(opts: {
+  batchId: string;
+  question: string;
+  answer: string;
+  hasContext: boolean;
+  targetSession: string;
+  windowIndex: number;
+  sourceSession?: string | null;
+  strategy: string;
+  model: string;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+  };
+  latencyMs: number;
+}): DuncanLogRecord {
+  return {
+    batchId: opts.batchId,
+    question: opts.question,
+    answer: opts.answer,
+    hasContext: opts.hasContext,
+    targetSession: opts.targetSession,
+    windowIndex: opts.windowIndex,
+    sourceSession: opts.sourceSession ?? null,
+    strategy: opts.strategy,
+    model: opts.model,
+    inputTokens: opts.usage?.input_tokens ?? 0,
+    outputTokens: opts.usage?.output_tokens ?? 0,
+    cacheCreationInputTokens: opts.usage?.cache_creation_input_tokens ?? 0,
+    cacheReadInputTokens: opts.usage?.cache_read_input_tokens ?? 0,
+    latencyMs: opts.latencyMs,
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/query.ts

@@ -11,7 +11,8 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { processSessionFile, processSessionWindows, type PipelineResult, type WindowPipelineResult } from "./pipeline.js";
-import { resolveSessionFilesExcludingSelf, findCallingSession, listAllSessionFiles, type RoutingParams, type RoutingResult } from "./discovery.js";
+import { resolveSessionFilesExcludingSelf, findCallingSession, listAllSessionFiles, listSubagentFiles, type RoutingParams, type RoutingResult } from "./discovery.js";
+import { recordQuery, buildLogRecord } from "./query-logger.js";
 
 // ============================================================================
 // OAuth token resolution
@@ -65,7 +66,7 @@ function oauthClientConfig(token: string): ResolvedAuth {
       "accept": "application/json",
       "anthropic-dangerous-direct-browser-access": "true",
       "anthropic-beta": "claude-code-20250219,oauth-2025-04-20,fine-grained-tool-streaming-2025-05-14",
-      "user-agent": "duncan-cc/0.1.0",
+      "user-agent": "duncan-cc/0.2.0",
       "x-app": "cli",
     },
   };
@@ -105,6 +106,13 @@ const DUNCAN_PREFIX = `Answer solely based on the conversation above. If you don
 export interface DuncanResult {
   hasContext: boolean;
   answer: string;
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+  };
+  latencyMs?: number;
 }
 
 export interface DuncanQueryResult {
@@ -190,6 +198,8 @@ export async function querySingleWindow(
     } as any);
   }
 
+  const startTime = Date.now();
+
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     const response = await client.messages.create({
       model,
@@ -207,7 +217,13 @@ export async function querySingleWindow(
     if (toolCall) {
       const input = toolCall.input as { hasContext: boolean; answer: string };
       if (typeof input.hasContext === "boolean" && typeof input.answer === "string") {
-        return { hasContext: input.hasContext, answer: input.answer };
+        const latencyMs = Date.now() - startTime;
+        return {
+          hasContext: input.hasContext,
+          answer: input.answer,
+          usage: response.usage as any,
+          latencyMs,
+        };
       }
     }
 
@@ -226,6 +242,35 @@ export async function querySingleWindow(
   throw new Error(`Duncan query failed after ${MAX_RETRIES} retries: model did not produce a valid duncan_response tool call`);
 }
 
+// ============================================================================
+// Logging Helper
+// ============================================================================
+
+/**
+ * Log all results in a batch to ~/.claude/duncan.jsonl.
+ */
+function logBatchResults(
+  batchResult: DuncanBatchResult,
+  strategy: string,
+  sourceSession: string | null,
+): void {
+  for (const r of batchResult.results) {
+    recordQuery(buildLogRecord({
+      batchId: batchResult.queryId,
+      question: batchResult.question,
+      answer: r.result.answer,
+      hasContext: r.result.hasContext,
+      targetSession: r.sessionId,
+      windowIndex: r.windowIndex,
+      sourceSession,
+      strategy,
+      model: r.model,
+      usage: r.result.usage,
+      latencyMs: r.result.latencyMs ?? 0,
+    }));
+  }
+}
+
 // ============================================================================
 // Batch Query
 // ============================================================================
@@ -235,7 +280,7 @@ export async function querySingleWindow(
  */
 export async function queryBatch(
   question: string,
-  routing: RoutingParams & { toolUseId?: string },
+  routing: RoutingParams,
   opts: {
     apiKey?: string;
     model?: string;
@@ -328,7 +373,7 @@ export async function queryBatch(
     results.push(...batchResults);
   }
 
-  return {
+  const batchResult: DuncanBatchResult = {
     queryId,
     question,
     results,
@@ -336,6 +381,8 @@ export async function queryBatch(
     hasMore: resolved.hasMore,
     offset: routing.offset ?? 0,
   };
+  logBatchResults(batchResult, routing.mode, resolved.excludedSessionId);
+  return batchResult;
 }
 
 // ============================================================================
@@ -434,7 +481,9 @@ export async function querySelf(
   // Wave 1: prime the cache with a single query
   results.push(await queryOnce());
   if (opts.signal?.aborted || copies <= 1) {
-    return { queryId, question, results, totalWindows: total, hasMore: false, offset: 0 };
+    const batchResult: DuncanBatchResult = { queryId, question, results, totalWindows: total, hasMore: false, offset: 0 };
+    logBatchResults(batchResult, "self", callingSessionId);
+    return batchResult;
   }
 
   // Wave 2: remaining copies in batches, hitting cached prefix
@@ -449,7 +498,9 @@ export async function querySelf(
     results.push(...batchResults);
   }
 
-  return { queryId, question, results, totalWindows: total, hasMore: false, offset: 0 };
+  const batchResult: DuncanBatchResult = { queryId, question, results, totalWindows: total, hasMore: false, offset: 0 };
+  logBatchResults(batchResult, "self", callingSessionId);
+  return batchResult;
 }
 
 // ============================================================================
@@ -546,7 +597,7 @@ export async function queryAncestors(
     results.push(...batchResults);
   }
 
-  return {
+  const batchResult: DuncanBatchResult = {
     queryId,
     question,
     results,
@@ -554,6 +605,112 @@ export async function queryAncestors(
     hasMore: offset + limit < totalWindows,
     offset,
   };
+  logBatchResults(batchResult, "ancestors", callingSessionId);
+  return batchResult;
+}
+
+// ============================================================================
+// Subagents Query — subagent transcripts of the active session
+// ============================================================================
+
+/**
+ * Query the calling session's subagent transcripts.
+ */
+export async function querySubagents(
+  question: string,
+  opts: {
+    toolUseId: string;
+    limit?: number;
+    offset?: number;
+    batchSize?: number;
+    apiKey?: string;
+    model?: string;
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+  },
+): Promise<DuncanBatchResult> {
+  const queryId = randomUUID();
+  const limit = opts.limit ?? 50;
+  const offset = opts.offset ?? 0;
+
+  const allSessions = listAllSessionFiles();
+  const callingSessionId = findCallingSession(opts.toolUseId, allSessions);
+  if (!callingSessionId) {
+    return { queryId, question, results: [], totalWindows: 0, hasMore: false, offset };
+  }
+
+  const session = allSessions.find(s => s.sessionId === callingSessionId);
+  if (!session) {
+    return { queryId, question, results: [], totalWindows: 0, hasMore: false, offset };
+  }
+
+  const subagentFiles = listSubagentFiles(session.path);
+  if (subagentFiles.length === 0) {
+    return { queryId, question, results: [], totalWindows: 0, hasMore: false, offset };
+  }
+
+  // Expand subagent files to windows
+  const allTargets: Array<{ sessionFile: string; sessionId: string; pipeline: WindowPipelineResult }> = [];
+  for (const sub of subagentFiles) {
+    try {
+      const windows = processSessionWindows(sub.path);
+      for (const w of windows) {
+        if (w.messages.length === 0) continue;
+        allTargets.push({ sessionFile: sub.path, sessionId: sub.sessionId, pipeline: w });
+      }
+    } catch {}
+  }
+
+  if (allTargets.length === 0) {
+    return { queryId, question, results: [], totalWindows: 0, hasMore: false, offset };
+  }
+
+  const totalWindows = allTargets.length;
+  const page = allTargets.slice(offset, offset + limit);
+
+  const batchSize = opts.batchSize ?? 5;
+  const results: DuncanQueryResult[] = [];
+  let completed = 0;
+
+  for (let i = 0; i < page.length; i += batchSize) {
+    if (opts.signal?.aborted) break;
+    const batch = page.slice(i, i + batchSize);
+    const batchResults = await Promise.all(
+      batch.map(async (target) => {
+        try {
+          const result = await querySingleWindow(target.pipeline, question, {
+            apiKey: opts.apiKey,
+            model: opts.model ?? target.pipeline.modelInfo?.modelId,
+            signal: opts.signal,
+          });
+          completed++;
+          opts.onProgress?.(completed, page.length);
+          return {
+            queryId, sessionFile: target.sessionFile, sessionId: target.sessionId,
+            windowIndex: target.pipeline.windowIndex,
+            model: target.pipeline.modelInfo?.modelId ?? "unknown", result,
+          };
+        } catch (err: any) {
+          completed++;
+          opts.onProgress?.(completed, page.length);
+          return {
+            queryId, sessionFile: target.sessionFile, sessionId: target.sessionId,
+            windowIndex: target.pipeline.windowIndex,
+            model: target.pipeline.modelInfo?.modelId ?? "unknown",
+            result: { hasContext: false, answer: `Error: ${err.message}` },
+          };
+        }
+      }),
+    );
+    results.push(...batchResults);
+  }
+
+  const batchResult: DuncanBatchResult = {
+    queryId, question, results, totalWindows,
+    hasMore: offset + limit < totalWindows, offset,
+  };
+  logBatchResults(batchResult, "subagents", callingSessionId);
+  return batchResult;
 }
 
 // ============================================================================