cc-hindsight

The prompt you'd write if you knew then what you know now.

npx cc-hindsight

cc-hindsight mines your coding-agent session history (Claude Code, kiro-cli)
into two things you can use tomorrow morning:

1. A oneshot prompt library. For each real task you've done, the realistic
   ideal first prompt: everything you knew and wanted at t=0 but didn't say,
   written in your own voice.
2. A distilled preference set. The things you keep re-telling your agent
   ("diagnose before acting", "pin the versions", "be terse"), surfaced as a
   paste-ready CLAUDE.md block so every future session starts aligned.

The t=0 problem

You get better results the more context you front-load into your first prompt,
yet we underspecify at t=0 and spend the session steering: correcting course,
restating preferences, answering questions the agent shouldn't have had to ask.

And the cost repeats every session. Your working preferences are stable facts
about how you like to work, yet you re-derive and re-type them project after
project instead of stating them once, upfront, where every future session reads
them from the first message.

All the evidence of what you should have said is already on disk. Claude Code
saves every session as JSONL under ~/.claude/projects/; kiro-cli keeps its
own store under ~/.kiro/sessions/cli. Plenty of tools read that data for
dashboards and transcripts. Nobody closes the loop from history back to
better prompting.

Before (what you actually typed at t=0):

help me script blocking a device on my home router

After (what cc-hindsight distilled from how that session actually went):

I want to automate my home router, starting with blocking a device. Get API
access working first, and store any credentials securely instead of asking me
to paste them in the clear. Anything that changes the network should be safe
by default: show me what it'll do and let me confirm before it runs. Then
prove it end-to-end on a real device. Research how others have done this
first, and keep the setup written down so I can reproduce it.

The second prompt was knowable at t=0. You just hadn't written it yet.

Quickstart

One command builds the whole library and shows it to you when it's done:

npx cc-hindsight distill    # offers to export first, then digest → cluster →
                            # author (asks before any claude call), then shows
                            # you the finished library

Prefer to drive each stage yourself? The pipeline is just three verbs:

npx cc-hindsight            # 1. scan: inventory your projects (read-only)
npx cc-hindsight export     # 2. export: human-only markdown per session
npx cc-hindsight distill    # 3. distill: digest → cluster → author (asks first)

Then browse and curate the results:

npx cc-hindsight list                # your library (✎ edited / ▲▼ rating badges)
npx cc-hindsight show <slug>         # read a oneshot
npx cc-hindsight copy <slug>         # → clipboard, paste into a fresh session
npx cc-hindsight edit <slug>         # open in $EDITOR; your edits are protected
npx cc-hindsight rate <slug> up      # record a verdict (up|down)
npx cc-hindsight prune               # remove orphaned entries (asks first)
npx cc-hindsight preferences         # → CLAUDE.md block
npx cc-hindsight status              # pipeline funnel + orphan/skip flags

Requires Node ≥ 22 on macOS or Linux (Windows is untested and currently
unsupported). scan and export are fully deterministic: no LLM, no
network. distill uses the claude CLI you already have, and never without
asking.

Multiple backends (Claude Code + kiro-cli)

cc-hindsight also mines kiro-cli session
history the same way. Every command takes --source claude|kiro|auto (default
auto: read whichever stores exist) and --kiro-dir / KIRO_CONFIG_DIR
(default ~/.kiro, parallel to --claude-dir). A machine with both stores
merges them into one library; the manifest tags each session's origin and the
export summary breaks the count down (9 claude + 3 kiro).

distill --runner claude|kiro|auto chooses which CLI does the distilling —
orthogonal to --source, so you can mine kiro history and distill with claude
or vice-versa (auto prefers the CLI matching your source, else whichever is
installed). preferences --target claude|kiro|agents emits a CLAUDE.md
block, a ~/.kiro/steering/ file, or a portable AGENTS.md section.

Privacy & trust

For a tool that reads your entire conversation history, auditability is the
product:

• Local-only. Everything is read from your disk and written to your disk
  (~/.cc-hindsight). No server, no accounts, no telemetry. The only network
  call is your own claude CLI doing what it already does.
• Three runtime dependencies. citty
  (zero-dependency CLI framework), zod (schema
  validation), and @clack/prompts
  (progress spinners, five micro-packages under the hood). All three are
  exact-pinned, and the entire transitive tree ships locked via
  npm-shrinkwrap.json. The whole data path is small enough to audit in one
  sitting.
• Consent-gated LLM use. distill states the exact invocation count and
  waits for [y/N] before anything runs on your subscription/credits.
  --dry-run shows the full plan for free. If you decline, it exits without
  invoking anything (exit code 2).
• Plain statement: exports contain your raw prompts, including anything
  sensitive you ever pasted into a session (keys, internal names, that one
  angry message). They live in your home directory with your permissions, and
  nothing ships them anywhere. A --redact option is on the roadmap.

How it works

flowchart TD
    A["~/.claude/projects/**/*.jsonl"] -->|"scan (read-only)"| B["inventory"]
    A -->|"export (deterministic)"| C["exports/*.md + manifest.json"]
    A -->|"anaphora + outcome evidence"| D["anaphora.json + outcomes.json"]
    C --> E
    D --> E
    subgraph distill ["distill: opt-in, consent-gated, resumable"]
        E["digest: 1 claude call / session"] --> F["cluster: 1 call"]
        F --> G["author: 1 call / task"]
    end
    G --> H["library/<slug>/ oneshot + provenance"]
    H --> I["list / show / copy / status"]
    H --> J["preferences → CLAUDE.md block"]

The extraction layer is a fidelity contract: eleven audited rules decide what
counts as human input (attachments typed while the agent was busy, recovered
slash commands, [decision] lines from option picks, [image pasted]
markers), with a regression fixture per rule. Fork/resume duplicates are
deduped globally. Short replies like "yes" and "option 2" get their antecedent
attached so the author stage knows what you approved. Sessions carry an
outcome classification, so a task where nothing ever succeeded gets skipped
instead of becoming a confident prompt that reproduces a failure path.

Authored oneshots pass a "knowable at t=0" test: they front-load intent,
constraints, preferences, and quality bars, while leaving out facts you only
discovered mid-session (paths, root causes, error messages). And they respect
an effort budget, staying around the length a motivated human would
actually type rather than ballooning into a 700-word spec.

Every distill stage checkpoints to disk after each unit of work: Ctrl-C loses
nothing, re-running resumes, --fresh resets deliberately, and status flags
library entries orphaned by re-clustering.

How it compares

Closest kin is Simon Willison's claude-code-transcripts: same local-first
values, same belief that transcripts are undervalued artifacts. The difference
is the direction of gaze: it renders your sessions (backward, for others);
cc-hindsight distills them (forward, for you).

FAQ

Does my data leave my machine?
No. The deterministic commands never touch the network. distill pipes
content to your locally installed claude CLI, the same thing that happens
when you use Claude Code, and nothing else.

What does distill cost?
Whatever your claude CLI costs you: it runs on your existing subscription or
API credits. The consent prompt states the exact invocation count up front
(one call per session digested, one to cluster, one per task authored), and
--dry-run prints the same plan without running anything. Checkpoints mean an
interrupted run isn't wasted money. Sessions too large for the input budget
(default 400k chars, --input-budget) are refused before anything is
spent. Re-run with --truncate=extreme to cut them (recorded in
provenance) or narrow the scope. Digest and author calls run 3 at a time by
default (--concurrency; 1 = sequential).

Subscription or API?
Either. cc-hindsight shells out to claude -p; however your CLI is
authenticated is how the calls are billed. --model passes through.

Why is a session missing from my exports?
Sessions with zero human messages are skipped naturally, --min-messages
filters thin ones, and fork/resume copies are deduped into their original
session. Note that dedupe is global across all projects: with --project, a
message duplicated by fork/resume is attributed to its earliest session even
when that session is outside the filter. Run export --verbose to see every
dropped piece with a reason. If genuine human input was dropped, that's a
bug: file an extraction-fidelity report.

Can I regenerate everything from scratch?
cc-hindsight distill --fresh clears the checkpoints (after confirming) and
re-runs. Old library entries from previous generations are flagged as orphans
in status.

Roadmap

• Claude Code plugin packaging for existing marketplaces (for
  distribution, without standing up a separate marketplace)
• An in-session skill variant ("distill this session as we go")
• Agent SDK orchestration exploration
• parentUuid-aware anaphora (branch-correct antecedents on forked
  conversations)
• --redact patterns for exports
• An opt-in community oneshot showcase

Development

npm install
npm test            # vitest: fixtures only, never reads your ~/.claude
npm run lint        # biome
npm run typecheck   # tsc --noEmit
npm run build       # tsdown → dist/

See CONTRIBUTING.md, especially the guide to adding a
fixture when you hit an unhandled transcript shape.

License

MIT

Author

Built by Aditya Singhal. If cc-hindsight surfaces
a pattern you didn't know you had, I'd love to hear about
it.