session-grep 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Otwell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# session-grep
+
+Grep across local AI coding-session transcripts (Claude Code, Codex) with **bounded
+message context** — built for agents answering questions about past sessions.
+
+Session history is a knowledge base — decisions, incidents, rules, dead ends — but
+the transcripts are hostile to search: conversational text is under 2% of bytes; the
+rest is tool output, thinking blocks, and base64. Raw grep returns whole JSONL records
+(10-100KB each); loading transcripts wholesale blows up context windows. session-grep
+parses records into messages, matches against conversation (not tool echoes), and
+returns ranked hits with a hard output budget.
+
+## Install
+
+```bash
+npx skills add lhotwll217/session-grep                    # as an agent skill
+npx session-grep --query "why did you" --since 7d         # as a CLI, no install
+npm i -g session-grep                                     # or global
+npx session-grep --self-test                              # verify: 22 built-in assertions
+```
+
+Needs Node ≥ 20 and ripgrep. The skill is the [skills/session-grep/](skills/session-grep/)
+folder (SKILL.md + script + adapters) — installable via `npx skills add`, or copy it into
+any skills directory; the self-test travels with it. Session formats are pluggable: one
+adapter file per tool in `adapters/`, drop in a new one to support another harness.
+
+## Use
+
+```bash
+session-grep --query "task_started" --before 2 --after 2      # exact term, bounded context
+session-grep --query "sidebar poll triage membership" --any   # multi-word: rarity-ranked, per-word hit counts
+session-grep --overview                                       # one-line digest per session
+session-grep --skim 269a                                     # one session's conversation, sampled to budget
+```
+
+Searches `~/.claude/projects` and `~/.codex/sessions` by default; `--root DIR` points
+anywhere. Full flags and agent guidance: [skills/session-grep/SKILL.md](skills/session-grep/SKILL.md).
+
+## Benchmark
+
+`eval/` is a promptfoo benchmark: an agent equipped with session-grep vs a naive-grep
+control, rubric-graded questions over real session history, measured in cost,
+correctness, tool calls, and time. The harness ships; our transcripts and cases stay
+local (documented in [eval/README.md](eval/README.md)). Our result — 29 questions
+over 24MB of real sessions, haiku subject:
+
+|  | session-grep | naive control |
+|---|---|---|
+| correct | **79%** (23/29) | 45% (13/29) |
+| cost | **$1.25** (0.41×) | $3.02 |
+| tool calls | **130** (3.3× fewer) | 423 |
+| time per question | **25s** (2.2× faster) | 54s |
+
+Cheaper on 26/29 questions; $0.054 vs $0.233 per correct answer. Target gate:
+≤0.5× cost at ≥ control correctness (`node eval/compare.mjs --gate`).
+
+To create your own eval on your own sessions (and tailor the tool with the
+improvement loop), see [eval/README.md](eval/README.md) and
+[eval/AUTORESEARCH.md](eval/AUTORESEARCH.md).
+
+## Origin
+
+Ported from [owner-operator](https://github.com/lhotwll217/owner-operator)'s
+`sessions-grep` skill; benchmarked on that project's own development sessions.
+
+## License
+
+MIT

package/bin/session-grep.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// npm bin entry. The canonical skill lives in skills/session-grep/ — the layout
+// `npx skills add` installs — and this wrapper just runs it.
+import '../skills/session-grep/session-grep.mjs';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "session-grep",
+  "version": "0.1.0",
+  "description": "Grep AI coding-session transcripts (Claude Code, Codex) with bounded message context — built for agents. Includes rarity-ranked multi-word search, session overviews, sampled spines, and a built-in self-test.",
+  "type": "module",
+  "bin": {
+    "session-grep": "bin/session-grep.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
+  "scripts": {
+    "eval": "promptfoo eval -c eval/promptfooconfig.yaml --no-cache",
+    "eval:smoke": "promptfoo eval -c eval/promptfooconfig.yaml --no-cache --filter-providers 'haiku' --filter-pattern 'roadmap-rule|interactive-launch|ripgrep-shim'",
+    "eval:view": "promptfoo view",
+    "loop": "node eval/loop.mjs",
+    "compare": "node eval/compare.mjs",
+    "test": "node --test eval/test/*.test.mjs",
+    "self-test": "node skills/session-grep/session-grep.mjs --self-test",
+    "prepublishOnly": "node skills/session-grep/session-grep.mjs --self-test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lhotwll217/session-grep.git"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "sessions",
+    "transcripts",
+    "grep",
+    "agent-tools",
+    "skill",
+    "promptfoo"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/session-grep/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: session-grep
+description: >-
+  Literal or regex grep across local AI session transcripts with bounded message context. Use when the user asks to search exact words, punctuation, hashtags/patterns, phrases like "why did you", or wants messages before/after a hit. This is for targeted drill-in, not broad topic discovery.
+---
+
+# session-grep
+
+Searches local AI CLI session files with exact literal matching or opt-in regex matching and returns only bounded
+message context around each hit. Use this when BM25 search is too fuzzy, cannot search
+punctuation/common phrases, or when you need a simple pattern like hashtags.
+
+## Onboarding (first use)
+
+The folders searched by default live in the `SESSION_ROOTS` variable at the top of
+the script. On first use, check it matches where this machine's sessions
+actually live, and edit it if not — ask the user which tools' history they want
+searchable. Known session homes:
+
+| tool | home | format |
+|---|---|---|
+| Claude Code | `~/.claude/projects` | jsonl (supported) |
+| Codex CLI | `~/.codex/sessions`, `~/.codex/archived_sessions` | jsonl (supported) |
+| Cursor | `~/Library/Application Support/Cursor/User/workspaceStorage` (macOS), `~/.config/Cursor/...` (linux) | sqlite (not yet parseable) |
+| Gemini CLI | `~/.gemini/tmp` | json (not yet parseable) |
+| opencode | `~/.local/share/opencode/storage` | split json (not yet parseable) |
+
+Quick existence check: `ls -d ~/.claude/projects ~/.codex/sessions 2>/dev/null`.
+Any directory of session `*.jsonl` files can be added to `SESSION_ROOTS`; `--root DIR`
+overrides per call without editing anything.
+
+Format support lives in the `adapters/` folder next to the script — one file per
+tool, each exporting `{name, detect(file), message(record, opts)}`. Supporting a
+new JSONL-based tool means dropping one file in that folder (and adding a
+`--self-test` fixture); non-JSONL formats also need a reader change in the script.
+
+## When to use
+
+- "grep sessions for ..."
+- "search exact phrase ..."
+- "find where I asked why did you ..."
+- punctuation searches like `?`
+- any request for messages before/after a specific text hit
+
+## Retrieval principle
+
+When no stronger filtering criteria is given, treat **recency as the default heuristic for
+relevance**. Search newest-first and prefer a recent window (`--since today`, `--since 7d`,
+or another explicit date) before expanding all-time. Only broaden when recent results are
+missing or insufficient.
+
+## How to use
+
+The script lives NEXT TO THIS FILE (in the repo: `skills/session-grep/session-grep.mjs`; as an
+installed skill it sits in this skill's directory). Invoke it by its path relative to
+this SKILL.md — shown below as `session-grep.mjs`:
+
+```bash
+node session-grep.mjs --query "why did you" --since 7d --limit 12 --before 2 --after 2
+node session-grep.mjs --query "sidebar poll triage membership" --any     # multi-word: any-word match, rarity-ranked
+node session-grep.mjs --overview                                          # digest of every session
+node session-grep.mjs --skim 269a --max-chars 12000                      # one session's conversation, sampled
+node session-grep.mjs --regex --query "#[A-Za-z0-9_][A-Za-z0-9_-]*" --since 7d --limit 20
+```
+
+For broad questions (summarize a session, what was X about) start with `--overview`,
+then `--skim SESSION_ID`, then targeted `--query` for specifics. For fact questions:
+multi-word literal phrases almost never occur verbatim — use `--any` (matches any word,
+hits ranked by word rarity, per-word hit counts reported) or a single rare term.
+Every hit is a pointer: to read around a promising hit, use `--session <id> --at <idx>`
+from its header instead of re-searching with wider context.
+
+Common flags:
+
+- `--query TEXT` literal query, or a JavaScript regex pattern when `--regex` is set
+- `--any` match ANY query word; hits ranked by summed word rarity (IDF); reports per-word hit counts so you learn which words are low-signal
+- `--regex` treat `--query` as a JavaScript regular expression; useful for hashtags and lightweight patterns
+- `--overview` no query needed: one compact digest per session (id, dates, message counts, opening prompt)
+- `--skim ID_PREFIX` no query needed: one session's user/assistant conversation, head/tail kept, middle sampled to the output budget
+- `--session ID_PREFIX --at INDEX` drill into a hit's pointer: every hit prints `id=` and `idx=` — this returns the exact messages around that index (±5 by default, `--before/--after` to widen) without re-running the search
+- `--limit N` max matching messages, default 20; use a high number for "all"
+- `--before N` messages before each hit, default 1
+- `--after N` messages after each hit, default 1
+- `--role user|assistant|all` filter matching messages, default `all`
+- `--source claude|codex|all` filter sources, default `all`
+- `--since today|Nd|YYYY-MM-DD` filter by message/session timestamp
+- `--sort newest|oldest|file` output order, default `newest`
+- `--root DIR` search this directory of `*.jsonl` transcripts instead of the default live stores (repeatable)
+- `--max-chars N` output budget, default 8000 — excess hits are omitted with a notice, never dumped
+- `--include-tools` also match inside tool_result blocks (excluded by default: they are file/command echoes, ~45% of bytes, and mostly restate the conversation)
+- `--case-sensitive` exact case match, useful for all-caps searches
+- `--json` machine-readable output (compact, same truncation and budget as text)
+- `--self-test` verify the tool against a built-in synthetic corpus (20 assertions, no dependencies) — run this after copying the skill anywhere
+
+## Output rules
+
+Summarize the hits; do not paste long transcript blocks. Give source, id/path, timestamp,
+and the compact context needed to understand what happened around the match.

package/skills/session-grep/adapters/_shared.mjs

@@ -0,0 +1,19 @@
+// Shared helpers for adapters. Files starting with _ are not loaded as adapters.
+
+// Flatten a message's content blocks to text. opts.includeTools: when false (the
+// default), tool_result blocks are excluded — they are file/command echoes, ~45% of
+// corpus bytes, and mostly restate what the conversation already says.
+export function contentToText(content, opts = {}) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const chunks = [];
+  for (const item of content) {
+    if (typeof item === 'string') chunks.push(item);
+    else if (item && typeof item === 'object' && (item.type !== 'tool_result' || opts.includeTools)) {
+      for (const key of ['text', 'output_text', 'input_text', 'content']) {
+        if (typeof item[key] === 'string') chunks.push(item[key]);
+      }
+    }
+  }
+  return chunks.join('\n');
+}

package/skills/session-grep/adapters/claude.mjs

@@ -0,0 +1,15 @@
+// Claude Code sessions: ~/.claude/projects/<project-slug>/<session-id>.jsonl,
+// one JSON record per line; messages under .message.content as typed blocks.
+import { contentToText } from './_shared.mjs';
+
+export default {
+  name: 'claude',
+  fallback: true, // claims any file no other adapter detects
+  detect: () => true,
+  message(obj, opts) {
+    if ((obj.type === 'user' || obj.type === 'assistant') && obj.message && typeof obj.message === 'object') {
+      return { role: obj.message.role || obj.type, text: contentToText(obj.message.content, opts), timestamp: obj.timestamp };
+    }
+    return null;
+  },
+};

package/skills/session-grep/adapters/codex.mjs

@@ -0,0 +1,17 @@
+// Codex CLI sessions: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl, one
+// {type, payload} record per line; messages are response_item/message payloads.
+// Boilerplate records (AGENTS.md preamble, IDE context, aborted turns) are skipped.
+import { contentToText } from './_shared.mjs';
+
+export default {
+  name: 'codex',
+  detect: (file) => file.includes('/.codex/') || /\/codex\//.test(file),
+  message(obj, opts) {
+    if (obj.type !== 'response_item' || !obj.payload || obj.payload.type !== 'message') return null;
+    const role = obj.payload.role || 'unknown';
+    if (!['user', 'assistant'].includes(role)) return null;
+    const text = contentToText(obj.payload.content, opts);
+    if (text.startsWith('# AGENTS.md instructions') || text.startsWith('# Context from my IDE setup:') || text.startsWith('<turn_aborted>') || text.slice(0, 5000).includes('<environment_context>')) return null;
+    return { role, text, timestamp: obj.timestamp };
+  },
+};

package/skills/session-grep/session-grep.mjs

@@ -0,0 +1,555 @@
+#!/usr/bin/env node
+// session-grep — literal/regex grep across AI coding-session transcripts (Claude Code,
+// Codex) returning bounded MESSAGE context around each hit, not raw JSONL lines.
+// Ported from owner-operator's sessions-grep skill; standalone here so it can be shared
+// and continuously eval-tuned (see eval/).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const opts = { limit: 20, before: 1, after: 1, role: 'all', source: 'all', sort: 'newest', json: false, regex: false, roots: [], maxChars: 8000 };
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--query') opts.query = args[++i];
+  else if (a === '--limit') opts.limit = Number(args[++i]);
+  else if (a === '--before') { opts.before = Number(args[++i]); opts.beforeSet = true; }
+  else if (a === '--after') { opts.after = Number(args[++i]); opts.afterSet = true; }
+  else if (a === '--role') opts.role = args[++i];
+  else if (a === '--source') opts.source = args[++i];
+  else if (a === '--since') opts.since = args[++i];
+  else if (a === '--sort') opts.sort = args[++i];
+  else if (a === '--root') opts.roots.push(args[++i]);
+  else if (a === '--max-chars') { opts.maxChars = Number(args[++i]); opts.maxCharsSet = true; }
+  else if (a === '--overview') opts.overview = true;
+  else if (a === '--skim') opts.skim = args[++i];
+  else if (a === '--session') opts.session = args[++i];
+  else if (a === '--at') opts.at = Number(args[++i]);
+  else if (a === '--self-test') opts.selfTest = true;
+  else if (a === '--include-tools') opts.includeTools = true;
+  else if (a === '--any') opts.any = true;
+  else if (a === '--regex') opts.regex = true;
+  else if (a === '--case-sensitive') opts.caseSensitive = true;
+  else if (a === '--json') opts.json = true;
+  else if (a === '--help' || a === '-h') usage(0);
+  else usage(1, `Unknown arg: ${a}`);
+}
+
+// ─── FORMAT ADAPTERS ────────────────────────────────────────────────────────
+// Loaded from the adapters/ folder next to this script — one file per session
+// format, each exporting {name, detect(file), message(record, opts), fallback?}.
+// Supporting a new JSONL-based tool = dropping one file in that folder (plus a
+// --self-test fixture below). `--source` values and dispatch derive from what's
+// loaded. Non-JSONL formats (Cursor's sqlite, opencode's split JSON) also need a
+// reader change here; see SKILL.md "Onboarding" for the format map.
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const ADAPTERS = {};
+{
+  const dir = path.join(scriptDir, 'adapters');
+  const loaded = [];
+  for (const f of fs.readdirSync(dir).filter((f) => f.endsWith('.mjs') && !f.startsWith('_')).sort()) {
+    const mod = await import(pathToFileURL(path.join(dir, f)).href);
+    if (mod.default?.name && mod.default.detect && mod.default.message) loaded.push(mod.default);
+  }
+  loaded.sort((a, b) => (a.fallback ? 1 : 0) - (b.fallback ? 1 : 0)); // fallbacks last
+  for (const a of loaded) ADAPTERS[a.name] = a;
+}
+// ────────────────────────────────────────────────────────────────────────────
+
+if (opts.selfTest) {
+  process.exit(await selfTest());
+}
+if (opts.at != null && !opts.session) usage(1, '--at requires --session ID_PREFIX');
+if (!opts.query && !opts.overview && !opts.skim && !(opts.session && opts.at != null)) usage(1, 'Missing --query (or use --overview / --skim ID / --session ID --at INDEX)');
+if (!Number.isFinite(opts.limit) || opts.limit < 1) usage(1, '--limit must be >= 1');
+if (!Number.isFinite(opts.maxChars) || opts.maxChars < 500) usage(1, '--max-chars must be >= 500');
+if (!Number.isFinite(opts.before) || opts.before < 0) usage(1, '--before must be >= 0');
+if (!Number.isFinite(opts.after) || opts.after < 0) usage(1, '--after must be >= 0');
+if (!['all', 'user', 'assistant'].includes(opts.role)) usage(1, '--role must be all, user, or assistant');
+if (opts.source !== 'all' && !ADAPTERS[opts.source]) usage(1, `--source must be all or one of: ${Object.keys(ADAPTERS).join(', ')}`);
+if (!['newest', 'oldest', 'file'].includes(opts.sort)) usage(1, '--sort must be newest, oldest, or file');
+const sinceTime = opts.since ? parseSince(opts.since) : null;
+if (opts.since && sinceTime == null) usage(1, '--since must be today, Nd, or YYYY-MM-DD');
+if (opts.any && opts.regex) usage(1, '--any and --regex cannot be combined');
+const queryRegex = opts.regex ? compileRegex(opts.query, opts.caseSensitive) : null;
+
+// --any: multi-word phrases rarely occur verbatim in transcripts, so match ANY word
+// and rank by how many distinct words a message hits. Low-signal words are dropped
+// from the word set so common glue doesn't dominate the ranking.
+const STOPWORDS = new Set(['the', 'and', 'was', 'were', 'did', 'does', 'you', 'your', 'why', 'how', 'what', 'when', 'where', 'which', 'who', 'for', 'that', 'this', 'with', 'from', 'have', 'has', 'had', 'are', 'not', 'but', 'about', 'into', 'out', 'our', 'they', 'them', 'then', 'than', 'its', 'get', 'got', 'can', 'could', 'would', 'should', 'ever', 'any', 'all', 'some', 'there']);
+let anyWords = null;
+if (opts.any) {
+  const raw = opts.query.split(/\s+/).filter(Boolean);
+  const strong = raw.filter((w) => w.length >= 3 && !STOPWORDS.has(w.toLowerCase()));
+  // Dedupe: repeated words must not double-count df or score.
+  anyWords = [...new Set((strong.length ? strong : raw).map((w) => (opts.caseSensitive ? w : w.toLowerCase())))];
+  if (!anyWords.length) usage(1, '--any needs at least one query word');
+}
+
+const home = os.homedir();
+
+// ─── SESSION_ROOTS — the folders this skill searches by default ─────────────
+// EDIT THIS on first use (or the agent running the skill should — see the
+// "Onboarding" section of SKILL.md, which lists known session homes per tool).
+// Any directory containing session *.jsonl files works. --root DIR overrides
+// per call without touching this.
+const SESSION_ROOTS = [
+  path.join(home, '.claude/projects'),           // Claude Code
+  path.join(home, '.codex/sessions'),            // Codex CLI
+  path.join(home, '.codex/archived_sessions'),   // Codex CLI (archived)
+];
+// ────────────────────────────────────────────────────────────────────────────
+
+const roots = (opts.roots.length ? opts.roots : SESSION_ROOTS).filter((dir) => fs.existsSync(dir));
+if (!roots.length) usage(1, 'No session roots found to search — edit SESSION_ROOTS at the top of this file (see SKILL.md "Onboarding") or pass --root DIR');
+
+// Browse modes answer "which session?" and "what happened in it?" in one call each —
+// whole-thread questions shouldn't cost 20 grep probes. A skim substitutes for many
+// probe calls, so it gets a roomier default budget.
+if (opts.skim && !opts.maxCharsSet) opts.maxChars = 16000;
+if (opts.overview || opts.skim) {
+  browse();
+  process.exit(0);
+}
+
+// Window mode: consume a hit's pointer. Every search hit prints `id=... idx=...`;
+// `--session ID --at IDX` returns the exact messages around that index — drill-in
+// without re-running the search. Context defaults widen to ±5 here (that's the point).
+if (opts.session && opts.at != null) {
+  if (!Number.isFinite(opts.at) || opts.at < 0) usage(1, '--at must be a message index >= 0 (from a hit\'s idx= field)');
+  const file = allSessionFiles().find((f) => sessionId(f).startsWith(opts.session));
+  if (!file) usage(1, `No session file matching id prefix "${opts.session}" under: ${roots.join(', ')}`);
+  const messages = parseMessages(fs.readFileSync(file, 'utf8'), sourceOf(file));
+  if (opts.at >= messages.length) {
+    usage(1, `--at ${opts.at} out of range: session ${sessionId(file)} has ${messages.length} messages (0..${messages.length - 1}). Note: indexes depend on --include-tools — drill in with the same setting the search used.`);
+  }
+  const b = opts.beforeSet ? opts.before : 5;
+  const a = opts.afterSet ? opts.after : 5;
+  const from = Math.max(0, opts.at - b);
+  const to = Math.min(messages.length - 1, opts.at + a);
+  console.log(`window id=${sessionId(file)} messages ${from}..${to} of ${messages.length} path=${file}`);
+  let size = 0;
+  for (let i = from; i <= to; i++) {
+    const m = messages[i];
+    const line = `[${i}]${i === opts.at ? '*' : ' '} ${m.role}${m.timestamp ? ' ' + String(m.timestamp).slice(0, 16) : ''}: ${truncate(m.text, i === opts.at ? 600 : 300)}`;
+    size += line.length;
+    if (size > opts.maxChars) { console.log(`... window truncated by --max-chars at [${i}]`); break; }
+    console.log(line);
+  }
+  process.exit(0);
+}
+
+const rg = spawnSync('rg', [
+  ...(opts.caseSensitive ? [] : ['-i']),
+  ...(opts.regex ? [] : ['--fixed-strings']),
+  '--files-with-matches',
+  '--glob',
+  '*.jsonl',
+  ...(anyWords ? anyWords.flatMap((w) => ['-e', w]) : [opts.query]),
+  ...roots,
+], { encoding: 'utf8' });
+
+if (rg.error) {
+  usage(1, `ripgrep (rg) is required but could not be run (${rg.error.code ?? rg.error.message}). Install it, e.g. \`brew install ripgrep\`.`);
+}
+let files;
+if (rg.status === 2 && opts.regex) {
+  // A JS-valid regex that ripgrep's engine rejects (lookaround, backrefs) must not
+  // die at the prefilter — fall back to scanning every session file with the JS matcher.
+  files = allSessionFiles();
+} else if (rg.status === 2) {
+  const detail = rg.stderr.trim() ? `\n${rg.stderr.trim()}` : '';
+  usage(1, `Invalid query for ripgrep.${detail}`);
+} else {
+  files = rg.status === 0 ? rg.stdout.trim().split('\n').filter(Boolean) : [];
+}
+const matches = [];
+const q = opts.caseSensitive ? opts.query : opts.query.toLowerCase();
+// --any rarity stats: document frequency per word across scanned messages. Rare words
+// are the signal; the ranking weights them (IDF) and the output reports the counts so
+// the caller learns which of its words are low-signal.
+const wordDf = anyWords ? Object.fromEntries(anyWords.map((w) => [w, 0])) : null;
+let messagesScanned = 0;
+
+for (const file of files) {
+  const source = sourceOf(file);
+  if (opts.source !== 'all' && source !== opts.source) continue;
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { continue; }
+  const messages = parseMessages(raw, source);
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    messagesScanned++;
+    const haystack = opts.caseSensitive ? msg.text : msg.text.toLowerCase();
+    let hitWords = null;
+    if (anyWords) {
+      hitWords = anyWords.filter((w) => haystack.includes(w));
+      for (const w of hitWords) wordDf[w]++;
+      if (!hitWords.length) continue;
+    }
+    if (opts.role !== 'all' && msg.role !== opts.role) continue;
+    if (!anyWords && (opts.regex ? !queryRegex.test(msg.text) : !haystack.includes(q))) continue;
+    const time = timeOf(msg.timestamp) ?? timeOf(messages[0]?.timestamp) ?? fs.statSync(file).mtimeMs;
+    if (sinceTime != null && time < sinceTime) continue;
+    matches.push({
+      source,
+      id: sessionId(file),
+      path: file,
+      index: i,
+      timestamp: msg.timestamp,
+      time,
+      ...(anyWords ? { matchedWords: hitWords } : {}),
+      before: messages.slice(Math.max(0, i - opts.before), i),
+      match: msg,
+      after: messages.slice(i + 1, i + 1 + opts.after),
+    });
+  }
+}
+
+// With --any, rank by summed word rarity (IDF): a hit on one rare identifier beats a
+// hit on three ubiquitous words. Recency breaks ties.
+if (anyWords) {
+  const idf = (w) => Math.log((messagesScanned + 1) / (wordDf[w] + 1));
+  for (const m of matches) m.score = round3(m.matchedWords.reduce((t, w) => t + idf(w), 0));
+  matches.sort((a, b) => b.score - a.score || (opts.sort === 'oldest' ? a.time - b.time : b.time - a.time));
+} else if (opts.sort === 'newest') matches.sort((a, b) => b.time - a.time);
+else if (opts.sort === 'oldest') matches.sort((a, b) => a.time - b.time);
+const limited = matches.slice(0, opts.limit);
+
+// Zero hits should steer the next query, not dead-end the agent: multi-word literal
+// phrases almost never occur verbatim in transcripts — say so and point at --any.
+const hint = !limited.length
+  ? (!opts.any && opts.query.trim().split(/\s+/).length > 1 && !opts.regex
+      ? 'no hits: multi-word phrases rarely occur verbatim in transcripts — retry with --any (matches any word, ranked by words matched), or grep ONE rare term (an identifier, error string, or filename)'
+      : opts.any
+        ? 'no hits for any query word: try different, rarer words (identifiers, error strings, filenames), or loosen --since/--role filters'
+        : 'no hits: try a rarer single term, or --any with several candidate words')
+  : null;
+
+// Per-word hit counts teach the caller which of its words are low-signal: a word
+// matching thousands of messages contributes nothing — drop it next query.
+const wordStats = anyWords
+  ? anyWords.map((w) => `${w}=${wordDf[w]}`).join(' ')
+  : null;
+
+// Output is budgeted (--max-chars, default 8k): a bad query can't flood the caller's
+// context. Hits are selected in rank order until the budget runs out (an oversized
+// FIRST hit is trimmed to fit rather than blowing the budget), and the header reports
+// the true emitted count.
+const OMIT = (n) => `... ${n} more matching messages omitted by the ${opts.maxChars}-char output budget — narrow with --role/--since${opts.any ? '/rarer words' : ''}, or raise --max-chars`;
+
+const HEADER_ALLOWANCE = 300;
+function selectWithinBudget(renderLen, trimContext) {
+  const emitted = [];
+  let size = HEADER_ALLOWANCE;
+  for (const m of limited) {
+    let entry = m;
+    let len = renderLen(entry);
+    if (size + len > opts.maxChars) {
+      if (emitted.length) break;
+      entry = trimContext(entry); // always emit at least the match itself, contextless
+      len = renderLen(entry);
+      if (size + len > opts.maxChars) break;
+    }
+    size += len;
+    emitted.push(entry);
+  }
+  return emitted;
+}
+
+if (opts.json) {
+  const slim = (msg) => ({ role: msg.role, text: truncate(msg.text, 300), timestamp: msg.timestamp });
+  const toEntry = (m) => ({ source: m.source, id: m.id, index: m.index, timestamp: m.timestamp, ...(anyWords ? { matchedWords: m.matchedWords, score: m.score } : {}), path: m.path, before: m.before.map(slim), match: slim(m.match), after: m.after.map(slim) });
+  const emitted = selectWithinBudget(
+    (m) => JSON.stringify(toEntry(m)).length,
+    (m) => ({ ...m, before: [], after: [] }),
+  ).map(toEntry);
+  const omitted = limited.length - emitted.length;
+  console.log(JSON.stringify({ query: opts.query, regex: opts.regex, any: !!opts.any, ...(anyWords ? { wordHits: wordDf, messagesScanned } : {}), rawFilesWithHits: files.length, totalMatches: matches.length, shown: emitted.length, ...(omitted ? { omittedByBudget: omitted, note: OMIT(omitted) } : {}), ...(hint ? { hint } : {}), matches: emitted }));
+} else {
+  const renderLines = (m) => [
+    `${m.source} id=${m.id} idx=${m.index} ts=${m.timestamp ?? ''}${anyWords ? ` matched=[${m.matchedWords.join(',')}] score=${m.score}` : ''}`,
+    `path=${m.path}`,
+    ...m.before.map((b) => `  before ${b.role}: ${truncate(b.text, 180)}`),
+    `  MATCH ${m.match.role}: ${truncate(m.match.text, 300)}`,
+    ...m.after.map((a) => `  after  ${a.role}: ${truncate(a.text, 180)}`),
+  ];
+  const emitted = selectWithinBudget(
+    (m) => renderLines(m).reduce((t, l) => t + l.length + 1, 6),
+    (m) => ({ ...m, before: [], after: [] }),
+  );
+  const omitted = limited.length - emitted.length;
+  console.log(`query=${JSON.stringify(opts.query)}${opts.regex ? ' regex=true' : ''}${opts.any ? ` any=true` : ''} raw_files_with_hits=${files.length} total_message_matches=${matches.length} shown=${emitted.length} sort=${opts.sort}${opts.since ? ` since=${opts.since}` : ''}${opts.caseSensitive ? ' case_sensitive=true' : ''}`);
+  if (wordStats) console.log(`word_hits: ${wordStats} (of ${messagesScanned} messages in matched files; high-count words are low-signal — prefer the rare ones)`);
+  if (hint) console.log(`hint: ${hint}`);
+  emitted.forEach((m, idx) => {
+    const [head, ...rest] = renderLines(m);
+    console.log(`\n[${idx + 1}] ${head}`);
+    for (const l of rest) console.log(l);
+  });
+  if (omitted) console.log(`\n${OMIT(omitted)}`);
+}
+
+function sourceOf(file) {
+  for (const [name, adapter] of Object.entries(ADAPTERS)) {
+    if (adapter.detect(file)) return name;
+  }
+}
+
+function parseMessages(raw, source) {
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    const msg = ADAPTERS[source].message(obj, { includeTools: opts.includeTools });
+    if (!msg || !msg.text.trim()) continue;
+    out.push(msg);
+  }
+  return out;
+}
+
+function sessionId(file) {
+  return path.basename(file, '.jsonl');
+}
+
+function round3(x) {
+  return Math.round(x * 1000) / 1000;
+}
+
+function allSessionFiles() {
+  const out = [];
+  for (const root of roots) {
+    for (const entry of fs.readdirSync(root, { recursive: true })) {
+      const p = path.join(root, String(entry));
+      if (p.endsWith('.jsonl') && fs.statSync(p).isFile()) out.push(p);
+    }
+  }
+  return out;
+}
+
+// --overview: one compact digest per session (id, dates, message counts, opening user
+// prompt) so the caller can pick the right session in a single cheap call.
+// --skim ID: the conversational spine of one session — user + assistant text only,
+// head/tail preserved and the middle sampled evenly to fit the output budget. Indexes
+// are printed so specifics can be drilled with a targeted --query afterwards.
+function browse() {
+  const files = allSessionFiles();
+  if (opts.skim) {
+    const file = files.find((f) => sessionId(f).startsWith(opts.skim));
+    if (!file) usage(1, `No session file matching id prefix "${opts.skim}" under: ${roots.join(', ')}`);
+    const messages = parseMessages(fs.readFileSync(file, 'utf8'), sourceOf(file));
+    const lines = messages.map((m, i) => `[${i}] ${m.role}${m.timestamp ? ' ' + String(m.timestamp).slice(0, 16) : ''}: ${truncate(m.text, 200)}`);
+    console.log(`skim id=${sessionId(file)} messages=${messages.length} path=${file}`);
+    const budget = opts.maxChars - 200;
+    const total = lines.reduce((t, l) => t + l.length + 1, 0);
+    if (total <= budget) {
+      for (const l of lines) console.log(l);
+      return;
+    }
+    const avg = total / lines.length;
+    // Budget is authoritative — no minimum floor (codex review: keep>=20 blew small
+    // budgets). Head/tail sizes scale down with the budget; middle picks are CENTERED
+    // in their strides so low sample counts don't cluster at the start of the middle.
+    const keep = Math.max(3, Math.floor(budget / avg));
+    const edge = Math.min(10, Math.floor(keep / 3), Math.floor(lines.length / 2));
+    const head = Math.max(1, edge);
+    const tail = Math.min(Math.max(1, edge), lines.length - head);
+    const middleKeep = Math.max(0, keep - head - tail);
+    const middle = lines.length - head - tail;
+    const stride = middleKeep > 0 ? middle / middleKeep : Infinity;
+    const chosen = new Set();
+    for (let i = 0; i < head; i++) chosen.add(i);
+    for (let i = 0; i < middleKeep; i++) chosen.add(head + Math.min(middle - 1, Math.floor((i + 0.5) * stride)));
+    for (let i = lines.length - tail; i < lines.length; i++) chosen.add(i);
+    let skipped = 0;
+    for (let i = 0; i < lines.length; i++) {
+      if (chosen.has(i)) {
+        if (skipped) console.log(`  ... ${skipped} messages sampled out (drill in with --query on anything above/below) ...`);
+        skipped = 0;
+        console.log(lines[i]);
+      } else {
+        skipped++;
+      }
+    }
+    if (skipped) console.log(`  ... ${skipped} messages sampled out ...`);
+    return;
+  }
+
+  // --overview
+  const digests = [];
+  for (const file of files) {
+    const source = sourceOf(file);
+    let raw;
+    try { raw = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    const messages = parseMessages(raw, source);
+    if (!messages.length) continue;
+    const first = messages.find((m) => m.role === 'user') ?? messages[0];
+    const times = messages.map((m) => timeOf(m.timestamp)).filter((t) => t != null);
+    digests.push({
+      id: sessionId(file),
+      source,
+      path: file,
+      from: times.length ? new Date(Math.min(...times)).toISOString().slice(0, 16) : '?',
+      to: times.length ? new Date(Math.max(...times)).toISOString().slice(0, 16) : '?',
+      user: messages.filter((m) => m.role === 'user').length,
+      assistant: messages.filter((m) => m.role === 'assistant').length,
+      mb: (raw.length / 1e6).toFixed(1),
+      opening: truncate(first.text, 220),
+      lastTime: times.length ? Math.max(...times) : 0,
+    });
+  }
+  digests.sort((a, b) => b.lastTime - a.lastTime);
+  console.log(`sessions=${digests.length} (newest first) — drill in with --skim ID or --query`);
+  let size = 0;
+  for (const d of digests) {
+    const block = `\nid=${d.id} source=${d.source} ${d.from} -> ${d.to} msgs=${d.user}u/${d.assistant}a size=${d.mb}MB\n  opening: ${d.opening}`;
+    if (size + block.length > opts.maxChars) {
+      console.log(`\n... remaining sessions omitted by --max-chars budget`);
+      break;
+    }
+    size += block.length;
+    console.log(block);
+  }
+}
+
+function truncate(s, n) {
+  const oneLine = s.replace(/\s+/g, ' ').trim();
+  return oneLine.length > n ? `${oneLine.slice(0, n)}...` : oneLine;
+}
+
+function timeOf(value) {
+  if (!value) return null;
+  const t = Date.parse(value);
+  return Number.isFinite(t) ? t : null;
+}
+
+function parseSince(value) {
+  const now = new Date();
+  if (value === 'today') return new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+  const days = value.match(/^(\d+)d$/);
+  if (days) return now.getTime() - Number(days[1]) * 24 * 60 * 60 * 1000;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return Date.parse(`${value}T00:00:00`);
+  return null;
+}
+
+function compileRegex(pattern, caseSensitive) {
+  try {
+    return new RegExp(pattern, caseSensitive ? 'u' : 'iu');
+  } catch (error) {
+    usage(1, `Invalid JavaScript regex: ${error.message}`);
+  }
+}
+
+function usage(code, msg) {
+  if (msg) console.error(msg);
+  console.error('Usage: session-grep.mjs --query TEXT [--any] [--regex] [--limit N] [--before N] [--after N] [--role user|assistant|all] [--source claude|codex|all] [--since today|Nd|YYYY-MM-DD] [--sort newest|oldest|file] [--root DIR ...] [--max-chars N] [--include-tools] [--case-sensitive] [--json] | --overview | --skim ID | --session ID --at INDEX | --self-test');
+  process.exit(code);
+}
+
+// ── self-test ───────────────────────────────────────────────────────────────
+// The skill carries its own verification: builds a synthetic corpus in a temp dir,
+// runs this script against it, and asserts every advertised behavior. Zero deps —
+// works wherever the skill is copied. `node session-grep.mjs --self-test`
+async function selfTest() {
+  const { execFileSync } = await import('node:child_process');
+  const self = process.argv[1];
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'session-grep-selftest-'));
+  const proj = path.join(dir, 'proj');
+  fs.mkdirSync(proj, { recursive: true });
+  const line = (role, content, ts) => JSON.stringify({ type: role, timestamp: ts, message: { role, content } }) + '\n';
+  const text = (t) => [{ type: 'text', text: t }];
+
+  // Session A: 30 messages; a rare identifier late; a tool_result echo; common words everywhere.
+  let a = '';
+  for (let i = 0; i < 12; i++) a += line(i % 2 ? 'assistant' : 'user', text(`common sidebar chatter number ${i} about the project`), `2026-06-01T10:${String(i).padStart(2, '0')}:00Z`);
+  a += line('assistant', text('the flumoxide bug came from spawnSync returning ENOENT'), '2026-06-01T10:20:00Z');
+  a += line('user', [{ type: 'tool_result', content: 'TOOLNOISE flumoxide echoed inside tool output ZEBRAECHO' }], '2026-06-01T10:21:00Z');
+  for (let i = 0; i < 12; i++) a += line(i % 2 ? 'assistant' : 'user', text(`more sidebar discussion segment ${i} winding down`), `2026-06-01T11:${String(i).padStart(2, '0')}:00Z`);
+  a += line('user', text('final closing message of session alpha'), '2026-06-01T12:00:00Z');
+  fs.writeFileSync(path.join(proj, 'aaaa1111.jsonl'), a);
+  // Session B: small, distinct.
+  fs.writeFileSync(path.join(proj, 'bbbb2222.jsonl'),
+    line('user', text('opening question about quixotic deployment'), '2026-06-05T09:00:00Z') +
+    line('assistant', text('quixotic deployment answered with lookahead syntax note'), '2026-06-05T09:01:00Z'));
+  // Session C: codex format (exercises the adapter registry + path detection).
+  fs.mkdirSync(path.join(dir, 'codex'), { recursive: true });
+  const codexLine = (role, t, ts) => JSON.stringify({ type: 'response_item', timestamp: ts, payload: { type: 'message', role, content: [{ type: 'output_text', text: t }] } }) + '\n';
+  fs.writeFileSync(path.join(dir, 'codex', 'rollout-cccc.jsonl'),
+    codexLine('assistant', 'zorptastic reply straight from the codex adapter', '2026-06-07T08:00:00Z'));
+
+  const run = (args) => execFileSync(process.execPath, [self, ...args, '--root', dir], { encoding: 'utf8' });
+  let n = 0;
+  const failures = [];
+  const check = (name, cond) => { n++; if (!cond) failures.push(name); };
+
+  try {
+    // literal + context + truthful shown count
+    const lit = JSON.parse(run(['--query', 'flumoxide', '--json']));
+    check('literal finds text block', lit.matches.some((m) => m.match.text.includes('spawnSync')));
+    check('shown equals matches length', lit.shown === lit.matches.length);
+    check('tool_result excluded by default', !lit.matches.some((m) => m.match.text.includes('TOOLNOISE')));
+    const withTools = JSON.parse(run(['--query', 'ZEBRAECHO', '--json', '--include-tools']));
+    check('--include-tools matches tool output', withTools.totalMatches === 1);
+    const withoutTools = JSON.parse(run(['--query', 'ZEBRAECHO', '--json']));
+    check('tool-only needle invisible by default', withoutTools.totalMatches === 0);
+
+    // --any: rarity ranking + dedupe
+    const any = JSON.parse(run(['--query', 'sidebar flumoxide sidebar', '--any', '--json']));
+    check('any dedupes words', Object.keys(any.wordHits).length === 2);
+    check('rare word ranks first', any.matches[0].matchedWords.includes('flumoxide'));
+    check('word df counted', any.wordHits.sidebar > any.wordHits.flumoxide);
+
+    // budget enforcement + omission notice
+    const tiny = run(['--query', 'sidebar', '--limit', '30', '--max-chars', '600']);
+    check('budget respected (<=600+slack)', tiny.length <= 900);
+    check('omission notice present', tiny.includes('omitted by the 600-char output budget'));
+    const tinyShown = Number(tiny.match(/shown=(\d+)/)[1]);
+    check('header shown = emitted blocks', (tiny.match(/\n\[\d+\]/g) || []).length === tinyShown);
+
+    // zero-hit hint
+    const miss = run(['--query', 'totally absent phrase here']);
+    check('multi-word miss hints --any', miss.includes('retry with --any'));
+
+    // regex incl. JS-only syntax (lookahead) falling back past rg
+    const la = JSON.parse(run(['--regex', '--query', 'quixotic(?= deployment)', '--json']));
+    check('JS-only regex still matches via fallback', la.totalMatches === 2);
+
+    // overview + spine
+    const ov = run(['--overview']);
+    check('overview lists both sessions', ov.includes('aaaa1111') && ov.includes('bbbb2222'));
+    const spine = run(['--skim', 'aaaa1111', '--max-chars', '900']);
+    check('skim within budget (+slack)', spine.length <= 1400);
+    check('skim keeps head', spine.includes('number 0'));
+    check('skim keeps tail', spine.includes('session alpha'));
+
+    // role filter still works
+    const role = JSON.parse(run(['--query', 'sidebar', '--role', 'user', '--json']));
+    check('role filter', role.matches.every((m) => m.match.role === 'user'));
+
+    // adapter registry: codex format parsed, source detected from path, --source filters
+    const cx = JSON.parse(run(['--query', 'zorptastic', '--json']));
+    check('codex adapter parses', cx.totalMatches === 1 && cx.matches[0].source === 'codex');
+    const cxOnly = JSON.parse(run(['--query', 'zorptastic', '--source', 'claude', '--json']));
+    check('--source filters by adapter', cxOnly.totalMatches === 0);
+
+    // pointer drill-in: consume a hit's id+idx via --session/--at
+    const hit = JSON.parse(run(['--query', 'flumoxide', '--json'])).matches[0];
+    const win = run(['--session', hit.id.slice(0, 6), '--at', String(hit.index)]);
+    check('window centers on the hit', win.includes(`[${hit.index}]*`) && win.includes('flumoxide'));
+    check('window includes neighbors', win.includes(`[${hit.index - 1}] `) && win.includes(`[${hit.index + 1}] `));
+  } catch (error) {
+    failures.push(`crashed: ${error.message}`);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+
+  if (failures.length) {
+    console.error(`self-test: ${failures.length}/${n} FAILED:\n  - ${failures.join('\n  - ')}`);
+    return 1;
+  }
+  console.log(`self-test: ok — ${n} assertions passed`);
+  return 0;
+}