claude-idea-capture

Your best ideas die in cleared Claude Code sessions. This catches them automatically - and can mine the ones you already lost.

You're deep in a debugging session and you stumble onto something genuinely reusable: a clean pattern, a nasty gotcha, a "huh, this could be its own tool" moment. You don't stop to write it down. Then you /clear, and it's gone.

git clone https://github.com/MatasMartin/claude-idea-capture && cd claude-idea-capture && ./install.sh
# then just use Claude Code normally. /clear as usual - ideas auto-log to ~/.claude/IDEAS.md
~/.claude/idea-capture/backfill.sh all   # one-time: mine every past session you've ever run

No SaaS, no external service, no API key beyond the claude CLI you already have. Your ideas live in one plain markdown file you own.

What it actually captures

Not a schema - here are real, unedited entries the hook wrote from my own sessions (one backfill over 3 months surfaced 23 of these, including a feature I'd half-built and abandoned):

## 2026-06-19 · Session-client vs admin-client NULL actor in Supabase RPC
- **What:** RPCs invoked with the service-role client write NULL into audit `actor_id`
  because auth.uid() is null; use the request-scoped client (or pass the actor explicitly)
  for anything that must be attributed.
- **Why reusable:** Silent audit-trail corruption that passes every test - shows up only
  when someone asks "who did this?" months later.
- **Category:** learning-note   **Value:** high   **Effort:** low
- **Next action:** reference
- **Status:** open

## 2026-06-11 · Verify responsive layout at widths WIDER than the design frame
- **What:** Testing only at the Figma frame width hides gaps that "balloon" on a 1920px
  monitor. Always measure at a width wider than the largest frame.
- **Why reusable:** Catches a whole class of layout bugs the design files can't show you.
- **Category:** checklist   **Value:** high   **Effort:** low
- **Next action:** publish
- **Status:** open

/review-ideas then splits these into Opportunities (repo/product/plugin - the shippable stuff) vs Learnings (your craft knowledge), so the rare star-worthy idea never gets buried under a hundred notes.

Why this isn't just another note command

There are a few "save an idea mid-session" tools already (see Prior art). They're all manual - you have to remember to run them, in the exact moment you're trying not to break focus. That's the part that fails.

The bet here is different: capture should be automatic, retrieval should be deliberate.

And the non-obvious bit that makes automatic capture possible: /clear doesn't delete anything. Claude Code writes every message to a .jsonl transcript on disk as you go. The SessionEnd hook fires with the path to that file right when you clear - so the cheapest, most natural moment to reflect on a session is the exact moment you wipe it from context. Haiku reads the saved file, not the thing you just cleared.

That same fact is why the backfill works: your last six months of ideas are already sitting in ~/.claude/projects/**/*.jsonl. This just reads them.

What you get

How it works

mid-task idea ──/capture-idea──▶ append entry to ~/.claude/IDEAS.md
/clear or quit ──SessionEnd hook──▶ Haiku reads the transcript FILE ──▶ appends qualifying ideas
weekly-ish    ──/review-ideas────▶ Opportunities vs Learnings, triage, archive stale
one time      ──backfill.sh all──▶ same reflection over every past session

The reflection samples both ends of long transcripts (the design decision usually happens early, then gets buried under tool-call spam), feeds recent + rejected titles back to stay precise, and the log is never auto-loaded into your context - read on demand only, so it can't bloat your sessions or your CLAUDE.md.

Install

git clone https://github.com/MatasMartin/claude-idea-capture.git
cd claude-idea-capture
./install.sh

The installer copies the two commands into ~/.claude/commands/, the scripts into ~/.claude/idea-capture/, seeds an empty ~/.claude/IDEAS.md, and merges the SessionEnd hook into ~/.claude/settings.json without touching your existing settings (timestamped backup first). Idempotent. Requires jq and the claude CLI.

Use it

# in a Claude Code session:
/capture-idea a clean retry-with-backoff wrapper worth extracting   # log one now
/capture-idea                                                        # log what we just solved
/review-ideas                                                        # triage the log

# from a shell:
DRYRUN=1 ~/.claude/idea-capture/backfill.sh all   # preview what would be scanned, free
~/.claude/idea-capture/backfill.sh 15             # mine your 15 most recent sessions
~/.claude/idea-capture/backfill.sh all            # mine everything

Cost & privacy (read before enabling)

• Cost: one Haiku pass per session-end over at most ~120 KB of transcript - fractions of a cent. Even at 40 /clears a day it's noise on your bill. A full-history backfill of ~100 sessions ran me a couple of dollars; DRYRUN=1 is free. Deeper reads: export IDEA_CAPTURE_MODEL=sonnet.
• Privacy: every session-end sends that session's transcript to the model (your own Claude account - nothing leaves your existing trust boundary). But if a session had secrets on screen, that text is in the transcript it reads. The log file is .gitignored by default.
• Kill switch: export IDEA_CAPTURE_DISABLE=1 skips it for a session; delete the SessionEnd block from settings.json to turn it off for good.

Limitations (the honest edges)

• Haiku misses subtle ideas and occasionally miscategorizes. /capture-idea in the moment is always higher quality; /review-ideas is where you fix categories and feed back noise.
• Dedup is soft (recent + rejected titles fed to the model, plus a hard per-session guard). A backfill that re-reads overlapping content can still produce a near-duplicate now and then - easy to spot and archive.
• It runs claude -p in the background. A recursion guard and a kill switch are built in, but it is spending tokens silently by design - which is why the cost section above exists.
• macOS + Linux. Built and tested on macOS (bash 3.2). The backfill has a Linux stat fallback; concurrent session-ends are serialized with a mkdir mutex (no flock needed). File an issue if your distro misbehaves.

Prior art (credit where due)

This problem is real enough that several people have taken a swing at it, and this borrows good ideas from all of them:

• claude-stash and the /notes skill - mid-session manual capture. This adds the automatic + backfill halves.
• claude-diary - append-only session diary + a reflect step. Closest in spirit; this is lighter and focused purely on ideas worth keeping, with value/effort triage.
• claude-reflect - hook-driven, confidence-scored learnings synced into CLAUDE.md. This deliberately keeps the log out of CLAUDE.md so it never bloats context.

If you just want manual capture, those are great. If you want the "I never have to remember, and it can mine my history" version, that's this.

License

MIT. Do whatever you want with it.