reflect

A session-local metacognition harness for long-running Claude Code work.

When your suggestions get reverted 3+ times within 10 tool calls, Opus 4.7 reads back recent tool calls + active rules + rolled-back diff, reasons about why, and injects guidance into the next turn.

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.

You'll know it fired when .reflect/session-guidance.md appears (or refreshes) in your project. The next turn auto-loads it via the path-scoped rule and adjusts.

npx reflect status         # state, last trigger, cum_x100 vs threshold

/brain-reflect             # manual trigger from inside Claude Code (bypasses cooldown)

export REFLECT_DISABLED=1  # disable for current shell session
# or set REFLECT_DISABLED=1 in .env for the whole project

Open the optional Viewer for a real-time dashboard of session state + reflection history + cross-session drift clusters.

That's it. No daily commands, no configuration once installed. Reflect stays out of the way until something needs your attention.

Viewer (optional local dashboard)

The repo also ships a localhost-only Next.js 16 dashboard at /web/ that reads your .reflect/ directory and renders session state, reflection history, and cross-session drift clusters. It never deploys, never makes API calls, binds to 127.0.0.1, and runs every file read through a PII redactor.

npm run viewer        # build + serve production (recommended — low RAM)
# or
npm run viewer:dev    # Turbopack dev server with HMR (higher RAM on Windows)

Open http://127.0.0.1:3000. 5 routes: / dashboard, /reflections, /patterns, /install, /roadmap. If .reflect/ is empty, synthetic fixtures in web/fixtures/ drive the UI so every route renders on a fresh clone. Full notes in web/README.md.

reflect is not a fix-all. Documented failure modes:

• Cold-start sessions — first ~5 turns lack causal context. reflect declines to fire (two-layer safety net: hook threshold + prompt-level refuse).
• False trigger on intent changes — if you change your mind mid-task, the reverts may be your shift, not assistant misbehavior. reflect flags false_trigger_likelihood: high and the next turn treats guidance as a question, not instruction.
• Regulatory / domain-opaque code — tax / KYC / GDPR may produce vague reflections. Mitigation in v1.1 (user-supplied domain rule injection).
• Cost on large prompts — cold call ≈ $0.05 (4,741-token L1 cached 1 h). Subsequent warm calls ≈ $0.01. See docs/api-cost-economics.md.

Full mechanism detail: docs/measurements.md.

reflect uses stetkeep (CJ's existing MIT npm package) as a base dependency. Two distinct layers:

• stetkeep — prevention. Static 16-entry false-positive catalog + PreToolUse safety net. Blocks bad edits before they happen.
• reflect — post-hoc reasoning. Dynamic metacognition after revert clustering. Catches what static rules can't.

You can run either independently. Together they're a "prevention + reflection" stack. stetkeep contents are NOT part of this hackathon submission — they're prior work, installed as an npm dependency.

"4.7 to me is a giant step up in capability. However, if you use it the same way that you used 4.6, you won't feel that step up. It's just amazing at long-running work." — Boris Cherny, Built with Opus 4.7 kickoff

The reflection task is causal reasoning over context, not pattern classification:

• "What was I trying to do across the last 12 tool calls?"
• "Why did the user push back?"
• "What pattern in my actions led to failure?"

Smaller models flatten this — they emit generic advice ("be more careful"). Opus 4.7 holds the causal chain across 20+ tool calls + 2–3 rule documents and produces a reflection that reads like a thoughtful teammate post-mortem. Methodology + decision log: experiments/.

• v1 (this hackathon) — single-shot Opus 4.7, session-local, honest failure modes
• v1.1 — opt-in deep-reflect mode (multi-turn dialogue), domain rule injection
• v2 — optional persistence (only if v1 signals warrant — see REFLECT.md <roadmap>)

We particularly want:

• New revert-signal detection patterns (with reproducer)
• Failure-mode reports (sessions where reflect fired but produced bad guidance)
• Reflection prompt improvements (with ablation evidence)
• Language ports — the harness is model-agnostic; Python / Rust ports welcome

See CONTRIBUTING.md. Process: open an issue → align scope → PR.

• Zero runtime dependencies on the harness layer (TypeScript + Anthropic SDK only)
• No network calls outside the single Opus 4.7 API call
• No telemetry, no analytics, no data exfiltration
• Pre-commit PII scanner (cloned from stetkeep)
• Privacy policy: PRIVACY.md · Vulnerability reports: SECURITY.md

License

MIT.

Built by Chanjoong Kim · Hackathon week of 2026-04-21 A harness for the model 6 months from now.