rewound 0.2.0

package/LICENSE

@@ -0,0 +1,31 @@
+rewound — Source-Available License (v0.1)
+
+Copyright (c) 2026 David Erner
+
+Personal use
+------------
+You may use, copy, and modify this software free of charge for your own
+personal projects, on your own machines.
+
+Commercial / team use
+----------------------
+Use by a company, team, or on behalf of an organization requires a paid
+license: USD $29 per individual, or USD $99 per team of up to 10 people —
+one-time, per major version. See the README for how to purchase, or contact
+the author. Version 0.x has no license-key enforcement; purchasing a license
+is how you comply with these terms.
+
+Source availability
+--------------------
+The source is provided so you can read it, audit it, and build it yourself.
+This is not an open-source license: no OSI-approved license grant is made,
+and redistribution (including publishing forks or copies) is not permitted
+without written permission from the author.
+
+No warranty
+-----------
+This 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
+author be liable for any claim, damages, or other liability arising from the
+use of this software.

package/README.md

@@ -0,0 +1,126 @@
+# rewound
+
+Grep for everything your AI coding agents ever did.
+
+## The problem
+
+Heavy users of coding agents accumulate gigabytes of session transcripts that are effectively write-only memory:
+
+- **No search.** Claude Code has no cross-session full-text search. Finding "the session where we fixed the auth bug" means manual archaeology through JSONL files.
+- **History is perishable.** Claude Code deletes transcripts older than 30 days by default (`cleanupPeriodDays`, swept at startup) — your reasoning history evaporates.
+- **Agents can't remember.** Every new session rediscovers what a previous session already solved. Nobody serves the agent itself.
+
+rewound indexes every session transcript on your machine into a local SQLite/FTS5 database and exposes it three ways: a CLI, an MCP server your agents can query directly, and a phone-friendly local web UI. Everything runs on your machine. Nothing leaves it.
+
+## 60-second demo
+
+```
+$ rewound index
+files scanned: 3310  new: 3310  updated: 0
+messages indexed: 368687  parse errors: 1
+elapsed: 29962ms
+
+$ rewound search "fts5 trigger bug"
+/home/dev/myapp · Fix fts5 trigger bug · 2026-07-01T10:00:05.000Z
+found and fixed the **fts5** **trigger** bug by rewriting the AFTER UPDATE **trigger**
+  ↳ resume: claude --resume 3f1a2c9e-...
+
+(1 hit in 5ms)
+```
+
+Those numbers are real, from indexing a working machine's actual Claude Code history: 3,310 session files / 2+ GB / 368,687 messages, cold-indexed in 30 seconds (target was 5 minutes), incremental re-index in 148ms (target 5s), search in single-digit milliseconds (target 100ms).
+
+## Install
+
+```bash
+npm install -g rewound
+rewound index
+```
+
+Or without installing: `npx rewound index`. Node 20+ required. The CLI is also installed
+as `rw` — same commands, fewer keystrokes (`rw search "auth bug"`).
+
+<details>
+<summary>Build from source</summary>
+
+```bash
+git clone <this-repo> && cd rewound
+npm install
+npm run build
+node dist/cli.js index          # or: npm link, then `rewound index`
+```
+
+</details>
+
+By default rewound reads `~/.claude/projects/**/*.jsonl` (read-only — it never modifies your transcripts) and writes its own database to `~/.rewound/rewound.db`. Override the DB path with `--db <path>` or `REWOUND_DB=<path>`.
+
+### Your history outlives Claude Code's cleanup
+
+Claude Code deletes transcripts older than ~30 days at startup. rewound's index is permanent: once a session is indexed, it stays searchable even after the source file is gone (it's kept as an *archived* session). Anything from before you started indexing is already unrecoverable — so the best moment to run `rewound index` is now, and then regularly. A cron line makes it automatic:
+
+```
+@hourly rewound index
+```
+
+Incremental runs take well under a second when little has changed.
+
+## The surfaces
+
+### CLI — available now
+
+```
+rewound index [--roots <dir...>] [--db <path>] [--json]
+rewound search <query> [--project <substr>] [--since <ISO|7d|24h>] [--role user|assistant] [--sidechains] [--limit N] [--json]
+rewound sessions [--project <substr>] [--limit N] [--json]
+rewound show <session-id-or-prefix> [--json]
+rewound stats [--json]
+```
+
+`search` supports relative time windows (`--since 7d`), project filtering, and role filtering. Query terms are quoted automatically so punctuation never throws an FTS syntax error; pass `--raw` if you want real FTS5 query syntax.
+
+Results are built to be scanned by a human eye: your own words and the agent's prose rank above tool output that merely mentions the term (a `cat` of a file no longer buries the sentence where you actually discussed the bug), and each session appears once — its best hit plus a `+N more matches in this session` count. Pass `--all-matches` to disassemble a session into every matching message.
+
+Two search tips from real-corpus testing: scope with `--project` when your memory is project-specific — cross-cutting terms (preferences, conventions, tool names) appear in *every* project's sessions and will drown an unscoped query. And run `rewound index` before hunting for recent work; indexing is incremental and takes well under a second when little has changed.
+
+### MCP server — available now
+
+`rewound mcp` starts a stdio MCP server so a Claude Code agent can search its own history mid-session — the moat feature. Three tools:
+
+- `search_history({query, project?, since?, limit?, all_matches?})` — ranked excerpts (≤700 chars each) with session id/title/date, one best hit per session by default, and a hint to fetch more context.
+- `get_session_summary({session_id})` — title, project, dates, message count, tools/models used, first prompt and last response (truncated).
+- `get_session_excerpt({session_id, match_uuid?, context?})` — the matched message plus surrounding context, readable.
+
+Every response is capped near 8KB so agent context isn't blown out by a single tool call. Add it to your Claude Code MCP config:
+
+```json
+{ "mcpServers": { "rewound": { "command": "npx", "args": ["-y", "rewound", "mcp"] } } }
+```
+
+(Running from a source checkout instead? Point `command`/`args` at your local build, e.g. `"command": "node", "args": ["/path/to/rewound/dist/cli.js", "mcp"]`.)
+
+### Web UI — available now
+
+`rewound serve` starts a local, phone-friendly web UI: full-text search with filters, readable session transcripts with one-tap resume-command copy, per-project timeline, and cost rollups.
+
+```
+rewound serve                  # http://127.0.0.1:4321
+rewound serve --host 0.0.0.0   # reachable over Tailscale — search your history from your phone
+```
+
+Server-rendered with zero frontend build step, colorblind-safe palette (blue/orange, no red/green status pairs), and everything — including clipboard copy — works over plain HTTP on your tailnet.
+
+## Privacy
+
+100% local. No telemetry, no network calls, no account. Your transcripts never leave your machine — rewound reads `~/.claude/projects` read-only and writes its own database to `~/.rewound/rewound.db`. Even "archive mode" (kept history after Claude Code prunes the source file) lives entirely in your local SQLite file.
+
+## Cost estimates
+
+`rewound stats` and search results include an **estimated** cost per session, computed from a static $/Mtok table (updated by hand, not live pricing). Treat it as a rough API-equivalent value, not a bill.
+
+## Roadmap
+
+Keyword-first search is deliberate for v0.x — it's fast, local, and predictable. Local hybrid/semantic search (vector index built with a local embedding model, no API keys, fused with FTS ranking) is planned once the keyword surface has proven itself; the gap it closes is vocabulary mismatch ("that time the port was already taken" vs `EADDRINUSE`).
+
+## License & pricing
+
+Source-available; **free for personal use**. Commercial/team use requires a paid license: **$29 individual · $99 team (up to 10 seats)** — one-time, per major version. v0.x ships with no license-key enforcement; buying a license is how you comply, and how you keep this maintained. See [LICENSE](LICENSE).

package/dist/adapters/claude-code.js

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+function extractBlockText(block) {
+    if (block == null)
+        return "";
+    if (typeof block === "string")
+        return block;
+    if (Array.isArray(block)) {
+        return block.map(extractBlockText).filter(Boolean).join("\n\n");
+    }
+    if (typeof block === "object") {
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            return b.text;
+        if (b.type === "thinking" && typeof b.thinking === "string")
+            return b.thinking;
+        if (b.type === "tool_result")
+            return extractBlockText(b.content);
+        // tool_use, image, and any unknown block type contribute no searchable text.
+    }
+    return "";
+}
+function extractUserContent(content) {
+    if (typeof content === "string")
+        return { text: content, toolText: "" };
+    if (!Array.isArray(content))
+        return { text: extractBlockText(content), toolText: "" };
+    const prose = [];
+    const tool = [];
+    for (const block of content) {
+        const isToolResult = block != null && typeof block === "object" && block.type === "tool_result";
+        const t = extractBlockText(block);
+        if (!t)
+            continue;
+        (isToolResult ? tool : prose).push(t);
+    }
+    return { text: prose.join("\n\n"), toolText: tool.join("\n\n") };
+}
+function extractAssistantContent(content) {
+    const tools = [];
+    if (!Array.isArray(content))
+        return { text: extractBlockText(content), tools };
+    const parts = [];
+    for (const block of content) {
+        if (block && typeof block === "object") {
+            const b = block;
+            if (b.type === "tool_use" && typeof b.name === "string") {
+                tools.push(b.name);
+                continue;
+            }
+        }
+        const t = extractBlockText(block);
+        if (t)
+            parts.push(t);
+    }
+    return { text: parts.join("\n\n"), tools };
+}
+function decodeProjectDir(filePath) {
+    const dirName = path.basename(path.dirname(filePath));
+    return dirName.replace(/-/g, "/");
+}
+function walk(dir, found) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            walk(full, found);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+            found.push(full);
+        }
+    }
+}
+export class ClaudeCodeAdapter {
+    id = "claude-code";
+    discover(roots) {
+        const found = [];
+        for (const root of roots)
+            walk(root, found);
+        return found;
+    }
+    parse(filePath, fromByte = 0) {
+        const id = path.basename(filePath, ".jsonl");
+        const buf = fs.readFileSync(filePath);
+        const slice = buf.subarray(fromByte);
+        // Only ever consume complete, newline-terminated lines. If the file is
+        // mid-write (the writer appended a record's bytes but hasn't flushed its
+        // trailing "\n" yet), the last fragment in `slice` is torn — leave it
+        // unconsumed and unparsed so the next incremental call re-reads it whole,
+        // rather than either erroring on it or silently skipping past it.
+        const lastNewline = slice.lastIndexOf(0x0a); // "\n"
+        const consumedSlice = lastNewline === -1 ? slice.subarray(0, 0) : slice.subarray(0, lastNewline + 1);
+        const bytesConsumed = fromByte + consumedSlice.length;
+        const text = consumedSlice.length > 0 ? consumedSlice.toString("utf8") : "";
+        const lines = text.length > 0 ? text.split("\n") : [];
+        const messages = [];
+        let title;
+        let gitBranch;
+        let projectDir;
+        let startedAt;
+        let endedAt;
+        let parseErrors = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let record;
+            try {
+                record = JSON.parse(trimmed);
+            }
+            catch {
+                parseErrors++;
+                continue;
+            }
+            if (!record || typeof record !== "object" || typeof record.type !== "string") {
+                parseErrors++;
+                continue;
+            }
+            if (record.cwd && !projectDir)
+                projectDir = record.cwd;
+            if (record.gitBranch && !gitBranch)
+                gitBranch = record.gitBranch;
+            if (record.type === "user" || record.type === "assistant") {
+                const msg = record.message;
+                const isAssistant = record.type === "assistant";
+                const userContent = isAssistant ? undefined : extractUserContent(msg?.content);
+                const { text: msgText, tools } = isAssistant
+                    ? extractAssistantContent(msg?.content)
+                    : { text: userContent.text, tools: [] };
+                const usage = isAssistant && msg?.usage
+                    ? {
+                        input: msg.usage.input_tokens ?? 0,
+                        output: msg.usage.output_tokens ?? 0,
+                        cacheRead: msg.usage.cache_read_input_tokens ?? 0,
+                        cacheWrite: msg.usage.cache_creation_input_tokens ?? 0,
+                    }
+                    : undefined;
+                messages.push({
+                    uuid: record.uuid ?? "",
+                    role: record.type,
+                    ts: record.timestamp ?? "",
+                    text: msgText,
+                    toolText: userContent?.toolText || undefined,
+                    tools,
+                    model: isAssistant ? msg?.model : undefined,
+                    isSidechain: Boolean(record.isSidechain),
+                    usage,
+                });
+                if (record.timestamp) {
+                    if (!startedAt || record.timestamp < startedAt)
+                        startedAt = record.timestamp;
+                    if (!endedAt || record.timestamp > endedAt)
+                        endedAt = record.timestamp;
+                }
+            }
+            else if (record.type === "ai-title") {
+                if (typeof record.aiTitle === "string")
+                    title = record.aiTitle;
+            }
+            // system, attachment, file-history-snapshot, last-prompt, mode,
+            // permission-mode, bridge-session, and any unrecognized type: skip silently.
+        }
+        return {
+            id,
+            source: "claude-code",
+            projectDir: projectDir ?? decodeProjectDir(filePath),
+            projectDirSource: projectDir ? "cwd" : "fallback",
+            filePath,
+            title,
+            gitBranch,
+            startedAt,
+            endedAt,
+            messages,
+            parseErrors,
+            bytesConsumed,
+        };
+    }
+}

package/dist/cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from "commander";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { openDb, resolveDbPath, getSessionByIdOrPrefix, getMessagesForSession, listSessions, getStats, getNewestMessageTs, parseJsonStringArray, } from "./db.js";
+import { ClaudeCodeAdapter } from "./adapters/claude-code.js";
+import { indexAll } from "./indexer.js";
+import { search, collapseSnippetWhitespace } from "./search.js";
+import { startMcpServer } from "./mcp.js";
+import { buildServer } from "./server.js";
+const DEFAULT_ROOTS = [path.join(os.homedir(), ".claude", "projects")];
+const defaultLog = (line) => console.log(line);
+export function highlightSnippet(snippet) {
+    return snippet.replace(/\x01/g, "\x1b[1m").replace(/\x02/g, "\x1b[0m");
+}
+export function stripSnippetMarkers(snippet) {
+    return snippet.replace(/[\x01\x02]/g, "");
+}
+export function parsePositiveInt(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new InvalidArgumentError(`"${value}" is not a positive integer.`);
+    }
+    return n;
+}
+export function runIndex(opts, log = defaultLog) {
+    const db = openDb(resolveDbPath(opts.db));
+    const adapter = new ClaudeCodeAdapter();
+    const roots = opts.roots && opts.roots.length > 0 ? opts.roots : DEFAULT_ROOTS;
+    const stats = indexAll(db, adapter, roots);
+    db.close();
+    if (opts.json) {
+        log(JSON.stringify(stats));
+        return;
+    }
+    log(`files scanned: ${stats.filesScanned}  new: ${stats.filesNew}  updated: ${stats.filesUpdated}`);
+    log(`messages indexed: ${stats.messagesIndexed}  parse errors: ${stats.parseErrors}`);
+    log(`elapsed: ${stats.elapsedMs}ms`);
+}
+export function runSearch(query, opts, log = defaultLog) {
+    const start = Date.now();
+    const db = openDb(resolveDbPath(opts.db));
+    const hits = search(db, query, opts);
+    // A stale index misses recent work silently; on a zero-hit search, say how far
+    // the index actually covers so "it's not indexed yet" is distinguishable from
+    // "it doesn't exist". Text mode only — JSON output stays machine-clean.
+    const newestTs = !opts.json && hits.length === 0 ? getNewestMessageTs(db) : undefined;
+    db.close();
+    const elapsedMs = Date.now() - start;
+    if (opts.json) {
+        log(JSON.stringify({
+            hits: hits.map(({ text, ...rest }) => ({ ...rest, snippet: stripSnippetMarkers(rest.snippet) })),
+            elapsedMs,
+        }));
+        return;
+    }
+    for (const hit of hits) {
+        log(`${hit.projectDir} · ${hit.title ?? hit.sessionId} · ${hit.ts}`);
+        log(highlightSnippet(collapseSnippetWhitespace(hit.snippet)));
+        if (!opts.allMatches && hit.matchesInSession > 1) {
+            const extra = hit.matchesInSession - 1;
+            log(`  (+${extra} more ${extra === 1 ? "match" : "matches"} in this session)`);
+        }
+        log(`  ↳ resume: claude --resume ${hit.sessionId}`);
+        log("");
+    }
+    if (newestTs) {
+        log(`index covers through ${newestTs} — looking for something newer? run \`rewound index\` first`);
+    }
+    log(`(${hits.length} ${hits.length === 1 ? "hit" : "hits"} in ${elapsedMs}ms)`);
+}
+export function runSessions(opts, log = defaultLog) {
+    const db = openDb(resolveDbPath(opts.db));
+    const rows = listSessions(db, { project: opts.project, limit: opts.limit });
+    db.close();
+    if (opts.json) {
+        log(JSON.stringify(rows));
+        return;
+    }
+    for (const r of rows) {
+        log(`${r.startedAt ?? "?"}  ${r.projectDir}  ${r.title ?? r.id}  msgs=${r.messageCount}  estApiCost=$${r.estCostUsd.toFixed(4)}`);
+    }
+}
+export function runShow(idOrPrefix, opts, log = defaultLog) {
+    const db = openDb(resolveDbPath(opts.db));
+    const session = getSessionByIdOrPrefix(db, idOrPrefix);
+    if (!session) {
+        db.close();
+        log(`no session found matching "${idOrPrefix}"`);
+        return;
+    }
+    const messages = getMessagesForSession(db, session.id);
+    db.close();
+    if (opts.json) {
+        log(JSON.stringify({
+            session,
+            messages: messages.map((m) => ({
+                uuid: m.uuid,
+                role: m.role,
+                ts: m.ts,
+                text: m.text,
+                tools: parseJsonStringArray(m.tools),
+                model: m.model ?? undefined,
+                isSidechain: Boolean(m.is_sidechain),
+            })),
+        }));
+        return;
+    }
+    log(`# ${session.title ?? session.id}  (${session.projectDir}, ${session.gitBranch ?? "?"})`);
+    for (const m of messages) {
+        const tools = parseJsonStringArray(m.tools);
+        const toolSummary = tools.map((t) => `[tool: ${t}]`).join(" ");
+        const sidechain = m.is_sidechain ? " (sidechain)" : "";
+        log(`[${m.ts}] ${m.role}${sidechain}: ${m.text}${toolSummary ? " " + toolSummary : ""}`);
+    }
+}
+export function runStats(opts, log = defaultLog) {
+    const db = openDb(resolveDbPath(opts.db));
+    const stats = getStats(db);
+    db.close();
+    if (opts.json) {
+        log(JSON.stringify(stats));
+        return;
+    }
+    // "est. API cost" not "cost": figures are token usage at API list prices — a heavy
+    // subscription user's total can read like absurd spend without that framing.
+    log(`sessions: ${stats.totalSessions}  messages: ${stats.totalMessages}  est. API cost: $${stats.totalCostUsd.toFixed(2)}`);
+    for (const p of stats.byProject) {
+        log(`  ${p.projectDir}: sessions=${p.sessions} messages=${p.messages} estApiCost=$${p.estCostUsd.toFixed(4)}`);
+    }
+}
+export async function runMcp(opts) {
+    const db = openDb(resolveDbPath(opts.db));
+    await startMcpServer(db);
+}
+// Exported for tests: a bad --port parse (NaN/negative/non-integer) must fall back
+// to the default instead of crashing fastify's listen().
+export function resolveServePort(port) {
+    return port !== undefined && Number.isInteger(port) && port >= 0 ? port : 4321;
+}
+export async function runServe(opts, log = defaultLog) {
+    const db = openDb(resolveDbPath(opts.db));
+    const app = buildServer({ db });
+    app.addHook("onClose", async () => {
+        db.close();
+    });
+    const port = resolveServePort(opts.port);
+    const host = opts.host ?? "127.0.0.1";
+    const address = await app.listen({ port, host });
+    log(`rewound serve listening on ${address}`);
+    if (host === "0.0.0.0") {
+        log("bound to 0.0.0.0 (Tailscale/phone mode) — reachable from other devices on your network");
+    }
+    return app;
+}
+export function buildProgram() {
+    const program = new Command();
+    program.name("rewound").description("Grep for everything your AI coding agents ever did.");
+    program
+        .command("index")
+        .option("--roots <dirs...>", "root directories to scan")
+        .option("--db <path>", "database path")
+        .option("--json", "output JSON")
+        .action((opts) => runIndex(opts));
+    program
+        .command("search <query>")
+        .option("--project <substr>", "filter by project directory substring")
+        .option("--since <iso-or-relative>", "ISO timestamp or relative like 7d / 24h")
+        .option("--role <role>", "filter by role: user or assistant")
+        .option("--sidechains", "include sidechain (subagent) messages")
+        .option("--all-matches", "show every matching message, not one best hit per session")
+        .option("--limit <n>", "max results", parsePositiveInt)
+        .option("--raw", "treat query as raw FTS5 match syntax")
+        .option("--db <path>", "database path")
+        .option("--json", "output JSON")
+        .action((query, opts) => runSearch(query, opts));
+    program
+        .command("sessions")
+        .option("--project <substr>", "filter by project directory substring")
+        .option("--limit <n>", "max results", parsePositiveInt)
+        .option("--db <path>", "database path")
+        .option("--json", "output JSON")
+        .action((opts) => runSessions(opts));
+    program
+        .command("show <session-id-or-prefix>")
+        .option("--db <path>", "database path")
+        .option("--json", "output JSON")
+        .action((idOrPrefix, opts) => runShow(idOrPrefix, opts));
+    program
+        .command("stats")
+        .option("--db <path>", "database path")
+        .option("--json", "output JSON")
+        .action((opts) => runStats(opts));
+    program
+        .command("mcp")
+        .description("start an MCP stdio server exposing search_history, get_session_summary, get_session_excerpt")
+        .option("--db <path>", "database path")
+        .action((opts) => runMcp(opts));
+    program
+        .command("serve")
+        .description("start the local web UI (search, session detail, timeline, stats)")
+        .option("--port <n>", "port to listen on", (v) => parseInt(v, 10), 4321)
+        .option("--host <host>", "host to bind (use 0.0.0.0 for Tailscale/phone access)", "127.0.0.1")
+        .option("--db <path>", "database path")
+        .action(async (opts) => {
+        await runServe(opts);
+    });
+    return program;
+}
+// npm always installs `bin` entries as symlinks, so argv[1] is the symlink path while
+// import.meta.url resolves through it to the real file — must compare real paths.
+export function isMainModule(argv1, moduleUrl) {
+    if (argv1 === undefined)
+        return false;
+    try {
+        return fs.realpathSync(argv1) === fileURLToPath(moduleUrl);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule(process.argv[1], import.meta.url)) {
+    buildProgram().parseAsync(process.argv);
+}