{
"markdown": "\n\n# reflect\n\n### *A session-local metacognition harness for long-running Claude Code work.*\n\n**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.**\n\n[](https://opensource.org/licenses/MIT)\n[](https://claude.com/claude-code)\n[](https://www.anthropic.com/claude/opus)\n[](https://cerebralvalley.ai/e/built-with-4-7-hackathon)\n\n
\n\n---\n\n## What is reflect?\n\nYou 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.\n\nreflect 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.\n\nSession-local. No persistence. No team sync. No telemetry. The file is deleted at session end.\n\n---\n\n## How it works\n\nTwo 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`.\n\n```mermaid\nflowchart LR\n A[Tool call] --> H{Revert signal?}\n U[User prompt] --> H2{Utterance negation?}\n H -->|T1 +100 or T2 +70| S[cum_x100 += weight]\n H2 -->|T3 +50| S\n S --> D{cum_x100 ≥ 240?}\n D -->|no| E[exit 0]\n D -->|yes| R[nohup bin/reflect.ts trigger]\n R --> P[3-layer prompt
L1 1h · L2 5m · L3 ephemeral]\n P --> API[claude-opus-4-7
thinking.adaptive
output_config.effort=high]\n API --> G[.reflect/session-guidance.md]\n G -. path-scoped rule auto-load .-> N[Next turn adjusts]\n```\n\n\nStatic SVG version of the diagram above — for npm.com and other viewers that don't render Mermaid
\n\n\n\n \n\nCold 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`](ARCHITECTURE.md). Protocol spec: [`REFLECT.md`](REFLECT.md). Cost math: [`docs/api-cost-economics.md`](docs/api-cost-economics.md).\n\n---\n\n## Install\n\n```bash\nnpm install @chanjoongx/reflect\nnpx reflect init # prints the 4 manual setup steps (auto-wire is v1.1)\n```\n\n> Published under the scoped name `@chanjoongx/reflect`. See [`CHANGELOG.md`](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 `` \"Honest gotchas\" below; v0.2 fix planned.\n\nThe v1 `init` prints copy-paste instructions; you manually:\n\n1. Copy `node_modules/@chanjoongx/reflect/.env.example` → `.env` and set `ANTHROPIC_API_KEY=sk-ant-...`\n2. 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`)\n3. 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)\n4. Add `.reflect/` to your `.gitignore`\n\n**Restart Claude Code** so it picks up the new hook and rule files.\n\n```bash\nnpx reflect status # verify hooks wired, API key present, last trigger\n```\n\nFull walkthrough: [`docs/getting-started.md`](docs/getting-started.md). Common issues: [`docs/troubleshooting.md`](docs/troubleshooting.md).\n\n---\n\n## Usage\n\nAfter 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.\n\nYou'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.\n\n```bash\nnpx reflect status # state, last trigger, cum_x100 vs threshold\n```\n\n```\n/brain-reflect # manual trigger from inside Claude Code (bypasses cooldown)\n```\n\n```bash\nexport REFLECT_DISABLED=1 # disable for current shell session\n# or set REFLECT_DISABLED=1 in .env for the whole project\n```\n\nOpen the optional [Viewer](#viewer-optional-local-dashboard) for a real-time dashboard of session state + reflection history + cross-session drift clusters.\n\nThat's it. No daily commands, no configuration once installed. Reflect stays out of the way until something needs your attention.\n\n---\n\n## Viewer (optional local dashboard)\n\nThe 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.**\n\n```bash\nnpm run viewer # build + serve production (recommended — low RAM)\n# or\nnpm run viewer:dev # Turbopack dev server with HMR (higher RAM on Windows)\n```\n\nOpen [http://127.0.0.1:3000](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`](web/README.md).\n\n---\n\n\nHonest gotchas
\n\nreflect is **not** a fix-all. Documented failure modes:\n\n- **Cold-start sessions** — first ~5 turns lack causal context. reflect declines to fire (two-layer safety net: hook threshold + prompt-level refuse).\n- **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.\n- **Regulatory / domain-opaque code** — tax / KYC / GDPR may produce vague reflections. Mitigation in v1.1 (user-supplied domain rule injection).\n- **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`](docs/api-cost-economics.md).\n\nFull mechanism detail: [`docs/measurements.md`](docs/measurements.md#failure-modes).\n\n \n\n\nComposition with stetkeep
\n\nreflect uses [`stetkeep`](https://github.com/chanjoongx/stetkeep) (CJ's existing MIT npm package) as a base dependency. Two distinct layers:\n\n- **stetkeep** — *prevention*. Static 16-entry false-positive catalog + PreToolUse safety net. Blocks bad edits before they happen.\n- **reflect** — *post-hoc reasoning*. Dynamic metacognition after revert clustering. Catches what static rules can't.\n\nYou 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.\n\n \n\n\nWhy Opus 4.7 specifically
\n\n> \"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\n\nThe reflection task is **causal reasoning over context**, not pattern classification:\n\n- \"What was I trying to do across the last 12 tool calls?\"\n- \"Why did the user push back?\"\n- \"What pattern in my actions led to failure?\"\n\nSmaller 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/`](experiments/).\n\n \n\n\nRoadmap
\n\n- **v1** (this hackathon) — single-shot Opus 4.7, session-local, honest failure modes\n- **v1.1** — opt-in *deep-reflect mode* (multi-turn dialogue), domain rule injection\n- **v2** — optional persistence (only if v1 signals warrant — see [`REFLECT.md`](REFLECT.md) ``)\n\n \n\n\nContributing
\n\nWe particularly want:\n\n- New revert-signal detection patterns (with reproducer)\n- Failure-mode reports (sessions where reflect fired but produced bad guidance)\n- Reflection prompt improvements (with ablation evidence)\n- Language ports — the harness is model-agnostic; Python / Rust ports welcome\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Process: open an issue → align scope → PR.\n\n \n\n\nSecurity & supply chain
\n\n- Zero runtime dependencies on the harness layer (TypeScript + Anthropic SDK only)\n- No network calls outside the single Opus 4.7 API call\n- No telemetry, no analytics, no data exfiltration\n- Pre-commit PII scanner (cloned from stetkeep)\n- Privacy policy: [`PRIVACY.md`](PRIVACY.md) · Vulnerability reports: [`SECURITY.md`](SECURITY.md)\n\n \n\n---\n\n## License\n\n[MIT](LICENSE).\n\n---\n\n\n\n**Built by [Chanjoong Kim](https://github.com/chanjoongx) · Hackathon week of 2026-04-21**\n*A harness for the model 6 months from now.*\n\n
\n",
"bytes": 10308,
"sha": "19ca4044b999b599d2e7013c709581304d36ab6478683cb3f15d887ad26d66d6",
"repo_slug": "chanjoongx/reflect",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_chanjoongx_reflect_reflect_26176cc5/readme"
}