ccpostmortem

Your Claude Code sessions already remember every dead end you hit — ccpostmortem reads them back.

Every Claude Code session is saved on your machine as a JSONL transcript. That history is normally write-only: nobody ever reads it again. ccpostmortem mines those transcripts into a searchable memory of what you tried, what failed and why, and what finally fixed it — then optionally feeds the relevant bits back to Claude before it repeats a mistake you already made.

No account. No cloud. No API key required. 100% local.

npx ccpostmortem

That's it — the first run indexes your existing history and shows you a summary in seconds.

What you get

ccpostmortem — instant summary of your history

  ccpostmortem  ·  indexed your Claude Code history

  149 sessions  ·  17 projects  ·  73 with failures
  2026-04-27 → 2026-06-07

  recurring snags:
    • file / path not found (49)
    • command not on PATH (30)
    • read a directory as a file (13)
    • non-zero exit code (8)
    • git error (8)

ccpostmortem search <query> — "have I hit this before?"

$ ccpostmortem search redis timeout

  ● 2026-05-21  my-api  (main)
    goal: the redis cache keeps timing out in production, please fix it
    tried & failed: `redis-cli ping` → Could not connect: ECONNREFUSED
    files: client.ts, alb.tf
    session 9f2c1a3b  ·  ccpostmortem show 9f2c1a3b

ccpostmortem show <id> — the full post-mortem of one session

Goal, every failed attempt with its cause, files touched, tools used, and whether it ended resolved.

ccpostmortem timeline [project] — chronological one-liner view

A quick scroll through what you worked on and which sessions ended unresolved (✗).

ccpostmortem hook install — the part that changes how Claude behaves

Installs a SessionStart hook so that when you open Claude Code in a project you've struggled in before, Claude automatically receives a short note:

Relevant history from your past Claude Code sessions (via ccpostmortem) — avoid repeating these dead ends: - [2026-05-21] redis cache timing out (client.ts) — tried & failed: redis-cli ping → ECONNREFUSED

Claude stops re-running the dead ends you already eliminated. Reversible any time with ccpostmortem hook uninstall.

Commands

Add --json to scan/search for machine-readable output you can pipe into other tools.

How it works

• Reads transcripts from ~/.claude/projects/**/*.jsonl (override with CCPOSTMORTEM_PROJECTS, or it follows CLAUDE_CONFIG_DIR).
• For each session it extracts the goal (your first prompt), every tool attempt, and failures — distinguished carefully: a tool result is only a failure when the harness flagged it (is_error) or a shell command emitted a strong failure signal. Reading a source file that merely contains the word "error" is not counted.
• Failures are rendered as what was tried → why it failed, and bucketed into human categories (file-not-found, command-not-on-PATH, network, test failures, …).
• Subagent transcripts are folded into their parent session.
• The index is cached at ~/.ccpostmortem/index.json; re-runs only re-parse transcripts whose files changed.

Privacy

Everything stays on your machine. ccpostmortem makes no network calls and needs no credentials. The optional --ai enrichment (roadmap) is the only thing that would ever call an API, and only if you explicitly opt in with your own key.

Install

# zero-install, always latest
npx ccpostmortem

# or install globally
npm i -g ccpostmortem
ccpostmortem hook install

Requires Node 18+. Pure JavaScript — no native modules, so it installs cleanly on macOS, Linux, and Windows.

Roadmap

• --ai mode: a one-line Haiku-written post-mortem per session (opt-in, your key).
• SQLite FTS backend for very large histories.
• Team mode: share an anonymized "gotchas" index across a repo, PR-reviewable.
• UserPromptSubmit matching tuned per-keystroke.

PRs welcome.

License

MIT