cc-reflection teaches Claude Code to capture and expand observations mid-session

cc-reflection, described by author Bluestein, is a multi-part framework wired together around Claude Code's EDITOR hook. The hook (Ctrl-G) normally opens a temp file for the user to write into, then injects the content back into Claude's input. Bluestein replaced that gap with an `fzf` menu that acts as a control surface, enabling operations like prompt editing, agent-based prompt enhancement, and browsing a "seed store" of captured observations.

The framework's core insight is that noticing and analyzing compete for the same attention.

The framework's core insight is that noticing and analyzing compete for the same attention. To resolve this, cc-reflection separates the two: a `/reflection` skill fires and has Claude apply three sequential lenses — 一省 (am I building this correctly?), 二省 (am I building the right thing?), and 三省 (how am I working?) — generating internal "seedlings" and discarding any that don't feel rooted in the actual session. Surviving observations become seeds, which the user can act on immediately, dismiss, or defer. Crucially, the framework treats producing no output as a valid and desirable result, avoiding pollution of the seed store with fabricated insight.

When the user is ready to engage with a deferred seed, a thought agent reads it, pulls up relevant code, reconstructs context, and expands it into a detailed analysis with a concrete next step. That expansion can feed back into the main agent as a plan, or the thought agent can make changes directly. Separately, a dice accumulator models the organic nature of insight: after 7 turns without reflection, the system begins rolling 1d20 each turn; after 14 turns, 2d20; after 21, 3d20 — with any natural 20 triggering an explicit reflection nudge and a reset.

Key facts

1. 01Built around Claude Code's EDITOR hook (Ctrl-G), which opens a temp file and injects its contents back into Claude's input.
2. 02The hook's gap is replaced with an `fzf` menu acting as a control surface for prompt editing, agent enhancement, and seed browsing.
3. 03A `/reflection` skill applies three lenses in sequence: architecture/engineering, product/UX, and workflow/process — drawn from the Confucian 吾日三省吾身.
4. 04Observations are captured as 'seeds' with a proposed artifact; seeds can be fixed immediately, dismissed, or deferred for later expansion.
5. 05A thought agent expands deferred seeds into codebase-grounded analyses with a clear next step, which can feed back into the main agent.
6. 06A dice accumulator starts rolling 1d20 after 7 turns without reflection, adding a die every 7 turns; a natural 20 triggers a reflection nudge and resets the counter.
7. 07The framework treats producing no output as a valid result — fabricating insight to fill silence is explicitly rejected by design.

Topics