Three hooks, a project wiki and gates keep Claude Code from forgetting after compaction and make it prove "done" (the author's hooks are public)
Polish front-end developer Mateusz Muszarski built his portfolio site with Claude Code in about two weeks and wrote up the setup: CLAUDE.md is a 76-line router into a 33-page project wiki; a SessionStart hook re-injects the working agreement, git state and lessons on every new session and after every compaction; a UserPromptSubmit hook scores each prompt and attaches up to 5 matching wiki pages; a Stop hook blocks once when code changed but the wiki didn't. Every correction becomes a one-line rule, a rule that slips back becomes a test, and "done" is a list of commands and screenshots that must pass. His hook scripts are public on GitHub, and we ran them on our test machine.
Visit site Claude Code hooks (SessionStart / UserPromptSubmit / Stop) + project wiki ↗- Pricing
- Paid
- Region
- Global
- Where it's from
- Overseas
- Added
- Oct 20, 2026
- Tested on
- Oct 20, 2026
- Version we used
- MuchaSsak/muszarski.com @ 090022f (2026-10-18): .claude/hooks/session-start.mjs, wiki-context.mjs, wiki-check.mjs, run with Node 20.19 outside Claude Code
- Categories
- CodingProductivity
- Original author
- Mateusz Muszarski ↗
- Our test
- Partly tested
- Cost / time
- The hooks are small Node scripts, free; you need Claude Code (a Claude plan or API). The author is on a subscription and didn't track tokens. The main cost is the up-front time to set up the wiki and gates.
The task
On a long project, Claude Code forgets what you agreed once the context is compacted, and tends to stop and report as soon as the work looks done.
Steps
- Start small (the author's own advice): create a lessons.md today and add one dated, imperative line every time you correct Claude, plus one gate Claude must run before it says done. The prompt below is our example of that habit, not the author's wording.
- Turn CLAUDE.md into a router: a "## Routing table" section with the header | Task touches | Read |, task keywords on the left and backticked wiki page paths on the right (e.g. .claude/project-info/site/i18n.md), plus the few rules that must never break; the knowledge itself lives in wiki pages under .claude/project-info/.
- Wire three hooks in .claude/settings.json (see .claude/hooks/ in the author's repo MuchaSsak/muszarski.com): SessionStart → session-start.mjs injects a "how we work" card, git state and the lessons' ## Rules on new sessions, resume, /clear and every compaction; UserPromptSubmit → wiki-context.mjs scores the prompt against the routing table and injects up to 5 matching pages; Stop → wiki-check.mjs --stop-hook blocks once when code changed but the wiki didn't.
- Promote rules that slip back into checks: in the author's case, CSS that folded animation and animation-timeline into one shorthand was rejected whole by Chrome, so the effect silently never ran; after it became a rule, three stylesheets slipped back the next day, so a unit test now reads every stylesheet.
- Define "done" as commands with exit codes: typecheck, lint, unit tests; Playwright e2e (axe WCAG 2.2 AA on every route, no sideways scroll from 320 to 2560 px, no text spilling out in any language); Lighthouse mobile performance at least 95 and every other category 100; a launch build fails if any placeholder is left.
- Make Claude look at its own work: Playwright screenshots from 390 to 1920 px in every language, and Claude has to open each one.
- Hand over big tasks in slices: research → build with real content → check → fix the weakest point, repeated until another pass finds nothing worth fixing. Missing facts become searchable placeholders logged in one register, and the launch build fails while any remain.
- Use subagents for reading, not writing: parallel research, fact-checking claims against the docs, and a fresh agent that never saw the draft reviewing it.
Prompt
From now on, whenever I correct you or a tool trips you up, append one dated, imperative rule under "## Rules" in .claude/project-info/lessons.md. Before you say you're done, run the typecheck, unit tests and e2e tests and list each command with its exit code; if any of them fails, you're not done.
What the author says
The author says (2026-10-18) he built this portfolio with Claude Code in about two weeks; CLAUDE.md is a 76-line routing table and the wiki has 33 pages. The card caps the injected lessons at 8,000 characters, the lessons file has outgrown that, and the last rules get cut. While writing the post, a subagent checked 12 claims against the docs in under a minute and all held. He also hit a background build whose log said Build failed but exited 0, because the output was piped through tail. He's explicit about the limits: one person, one project, Windows, no token cost tracking, and on a two-day script he'd write a short CLAUDE.md and stop there. The post was drafted with Claude Code from his wiki, code and notes.
Our test
We did not run these hooks inside Claude Code on a real project, and did not reproduce his gates, screenshots or subagent workflow. We cloned the author's public muszarski.com repo, ran the three hook scripts directly on our test machine with simulated hook input (stdin JSON), and checked the pipe exit-code pitfall.
What we found when we tried it:Tested 2026-10-20 (repo commit 090022f, Node 20): CLAUDE.md is indeed 76 lines, and the wiki check reported 33 pages, 0 errors, 0 warnings. Calling the UserPromptSubmit hook with the post's example prompt "have it consistent over languages" injected the same text shown in the post, pointing to .claude/project-info/site/i18n.md; prompts under 25 characters produced no output. Calling the SessionStart hook with {"source":"compact"} produced a ~9,900-character card that opens with "The context was just COMPACTED. This is not a pause", includes git state, and ends with a note that lessons.md was cut at its cap. Stop hook: after editing one code file, the first call returned decision: block listing the wiki page and log.md to update; the same state passed the second time; stop_hook_active: true passed immediately; after adding a malformed heading to log.md, it blocked and named that line. In bash, false | tail exited 0, and 1 with set -o pipefail.
How to get in
Published on muszarski.com and cross-posted to dev.to; the hooks are in the public GitHub repo MuchaSsak/muszarski.com (no license file, so treat them as a reference).
Who it suits
Anyone running Claude Code on a project that lasts weeks and keeps losing context after compaction, and solo developers with several sessions or machines working on one repo.
Pitfalls
- Hooks run shell commands with your full user permissions; read anyone else's hook before you add it.
- "Never read .env" in CLAUDE.md only guides Claude and blocks nothing; a deny rule in settings is what actually stops a read (the author says that's his next step).
- The lessons file outgrows the injection cap: running the card from the author's repo produced about 9,900 characters, ending with a note that lessons.md was cut. Merge and prune regularly, and drop rules that a test already enforces.
- Piping output through tail hides the real exit code: use set -o pipefail or grep the log for failures (in our test, false | tail exited 0, and 1 with pipefail).
- A sequential check script (the author's bun run check) stops at the first failure and hides the rest; after fixing one, rerun every check.
- Several sessions on one repo: stage only your own paths, never git add -A; give each build its own folder and port; stop servers by the port's PID, not by process name; if a push is rejected, git pull --rebase.
- Headless Chromium renders WebGL in software, so shaders look broken in screenshots; animated pages need reduced motion or a fixed clock, or you capture a random frame.
- The author is on Windows; the Git Bash path rewriting, taskkill and long-path traps are Windows-only.
More in this category
- A demo video per docs page that flags itself when the UI changesVideoScreenplayClaude CodeTool free; uses your agent's quota◐ Partly testedOverseas
- AI backend code that guards against races, leaks and bad migrationsCodingbackendskillsClaude CodePostgreSQLFree; about 2× tokens per task◐ Partly testedOverseas
- An afternoon of AI work, a 3D action game you play in the browserCodingClaude CodeTripoJimengSkill free; Claude quota plus asset tools◐ Partly testedChina
- Keep a long-running AI-built project from turning into a messCodingClaudeCodexoil-delegateNeeds Claude and Codex plans◐ Partly testedChina
- Use a web app once and get an AI write-up of how it worksResearchREAClaude CodeChromeFree tools; needs Claude or Codex◐ Partly testedOverseas