reflect

What is reflect?

You let Claude Code run for hours in auto mode. It does great work — and somewhere around hour two, it starts repeating the same misjudgment. You revert. It tries again. You revert.

reflect catches that cluster. When ≥3 revert signals appear within 10 tool calls (weighted threshold: 3 hard reverts = 3.0, or 2 hard + 1 utterance = 2.5, crosses the 2.4 cutoff), reflect hands recent history to Opus 4.7 and gets back one structured reflection — pattern, signal, adjustment, confidence — written to .reflect/session-guidance.md. Your next turn reads it via path-scoped rule injection and adjusts.

Session-local. No persistence. No team sync. No telemetry. The file is deleted at session end.

How it works

Two hooks watch for three tiers of revert signal. PostToolUse catches Tier 1 (git revert, git restore, git checkout HEAD -- — weight 1.0) and Tier 2 (rm/unlink of a user file, build-artifact paths excluded — weight 0.7). UserPromptSubmit catches Tier 3 (utterance negation like "no wait", "undo that" — weight 0.5). Weights accumulate as cum_x100 (integer × 100, so shell arithmetic needs no bc). When cumulative weight crosses 240, a single-shot Opus 4.7 call fires; the hook exits in ≤50 ms while the API call runs in the background via nohup.

flowchart LR
  A[Tool call] --> H{Revert signal?}
  U[User prompt] --> H2{Utterance negation?}
  H -->|T1 +100 or T2 +70| S[cum_x100 += weight]
  H2 -->|T3 +50| S
  S --> D{cum_x100 ≥ 240?}
  D -->|no| E[exit 0]
  D -->|yes| R[nohup bin/reflect.ts trigger]
  R --> P[3-layer prompt<br/>L1 1h · L2 5m · L3 ephemeral]
  P --> API[claude-opus-4-7<br/>thinking.adaptive<br/>output_config.effort=high]
  API --> G[.reflect/session-guidance.md]
  G -. path-scoped rule auto-load .-> N[Next turn adjusts]

Cold call ≈ $0.05 (measured D2) · warm call ≈ $0.01 (measured D2, 95.9% L1 cache hit) · latency 5–6 s, non-blocking. Detailed architecture: ARCHITECTURE.md. Protocol spec: REFLECT.md. Cost math: docs/api-cost-economics.md.

Install

npm install @chanjoongx/reflect
npx reflect init      # prints the 4 manual setup steps (auto-wire is v1.1)

Published under the scoped name @chanjoongx/reflect. See CHANGELOG.md for the current version. The binary stays reflect (so npx reflect ... works unchanged). The unscoped reflect name is taken by a pre-existing JavaScript parser; scoping keeps the CLI identity clear and avoids name collision. v1 is hackathon-week build — expect rough edges. Path-scope delivery gap (root-level files) is a known limitation — see <details> "Honest gotchas" below; v0.2 fix planned.

The v1 init prints copy-paste instructions; you manually:

1. Copy node_modules/@chanjoongx/reflect/.env.example → .env and set ANTHROPIC_API_KEY=sk-ant-...
2. Copy node_modules/@chanjoongx/reflect/.claude/settings.example.json → .claude/settings.json (or merge the hooks.PostToolUse + hooks.UserPromptSubmit blocks into your existing settings.json)
3. Copy node_modules/@chanjoongx/reflect/.claude/rules/reflect-rules.md → .claude/rules/reflect-rules.md (path-scoped: src/**, lib/**, app/**, packages/** — v0.2 widens to include root-level files like README/CHANGELOG)
4. Add .reflect/ to your .gitignore

Restart Claude Code so it picks up the new hook and rule files.

npx reflect status      # verify hooks wired, API key present, last trigger

Full walkthrough: docs/getting-started.md. Common issues: docs/troubleshooting.md.

Usage

After install, reflect runs silently in the background. There's nothing to type day-to-day — the hook watches your tool calls and fires Opus 4.7 only when 3+ revert signals cluster within 10 turns.