claude-watch

the problem

Claude Code forgets. On purpose.

When your context window fills up, Claude Code runs /compact — summarizing and discarding old messages to free tokens. That transcript is gone. If you want to look up what you actually said three sessions ago, you can't.

01 — before

Sessions live in a jsonl graveyard.

A growing pile of .jsonl files under ~/.claude/projects/… with no search, no timeline, and no way to distinguish a live session from a compacted one.

02 — after

Captured the moment before `/compact`.

claude-watch listens for the PreCompact hook that fires just before summarization runs, syncs the full transcript to a plain .md file, and updates a SQLite FTS5 index. Nothing is lost.

03 — reach

Every session, searchable.

Type words. Get answers. Same index the web UI uses, available in the CLI too.

what you get

One binary. Real memory.

No CGO. No Docker. No database server. Plain-text storage, a searchable index, and a local web UI at localhost:7823 — that's the whole surface.

Survives /compact.

The PreCompact hook fires before summarization, giving us the full transcript before it's destroyed.

ii.

Fast full-text search.

SQLite FTS5. Implicit AND across words. Hyphens and apostrophes split into parts.

iii.

Plain markdown files.

Sessions land as human-readable .md. No proprietary format. Version-control them if you want.

iv.

CLI without SQLite.

list, export, and search work straight against Claude's JSONL. No server needed.

Local web UI.

Browse sessions by project, read full conversations with markdown, tool calls, and compaction markers rendered.

vi.

Agent-aware.

install-skill teaches Claude Code, Codex, and Cursor to route history lookups through the CLI.

vii.

Dark theme, honest.

Built for the terminal-adjacent life. Web UI auto-follows the system and remembers your toggle.

viii.

Transparent setup.

Shows exactly what will be written to ~/.claude/settings.json before touching a byte.

command reference

Small surface. Real power.

One binary, seven subcommands. Full details, flags, and JSON output in the README.

claude-watch serve

Start the local server and open the web UI at localhost:7823. First run installs Claude Code hooks after you confirm.

claude-watch list

List sessions across every project. Reads Claude's JSONL directly — no SQLite required.

claude-watch search <query>

Full-text search every captured conversation. Same FTS5 index as the web UI. --json for scripting.

claude-watch export --session-id

Export any conversation to a clean markdown file. Add --include-tool-msg for full detail.

claude-watch install-skill

Ship the agent skill file to Claude Code, Codex, and Cursor so they use claude-watch for history lookups.

claude-watch hook <event>

Process a Claude Code hook event from stdin. Wired automatically on first serve.

claude-watch rebuild

Force rebuild the SQLite FTS5 index from your .md session files.

how it works

Event-driven. No polling.

Claude Code fires hook events at key points. Each hook pipes JSON straight into the claude-watch binary, which syncs the exact JSONL file it points at — no filesystem scanning, no ticker.

SessionStart

Records the new session and creates an empty markdown stub. Session metadata lands in SQLite immediately.

UserPromptSubmit · Stop

Incremental sync of the transcript into markdown, then updates the SQLite FTS5 index. Fires on every prompt and every assistant stop.

PreCompact critical

Fires before Claude compacts the context. claude-watch flushes the full transcript to disk right here — so nothing is lost when summarization runs.

SessionEnd

Final sync of the transcript. The session is now preserved in full and available for search, export, and browsing.