claude-pop-quiz

A mandatory, automatic learning-check hook for Claude Code.

Stay fluent in the code your agent wrote: get pop-quizzed on your own sessions, on a cadence you can't skip.

Install · How it works · Configuration · Updates · Changelog

---

Agentic coding lets you ship work without reading what the agent wrote. The risk: you end up unable to explain code, decisions, and tooling that are nominally "yours", whether in an interview, a review, or just when the agent isn't around. This hook counters that by pop-quizzing you on your own sessions, on a cadence you can't skip.

Every ~40 to 45 actions in a chat (your messages plus every tool/file/agent call Claude makes), it pauses and makes you answer 5 questions about the technical substance of that session: the jargon used, the code written and why, and the files touched. You answer in your own words; Claude grades you and flags gaps.

After grading, Claude appends the results to a learning journal, a markdown revision log of every quiz: each question, your answer, the correct answer, a verdict, a one-line context note (the file or concept the question came from, so the entry stands alone months later), and links to study. Re-read it later, or point it at a git repo to version your progress. See JOURNAL.example.md for the format.

That journal's layout is a contract, not decoration: the hook parses it back to drive everything below, keyed on each entry's ### <verdict emoji> Q<n> · <topic title> header and its topic title. If the grader drifts off that shape, or renames a topic, the affected history goes quiet. doctor reports the parse coverage so drift shows up as a number instead of rotting unnoticed.

That journal is also read back in to make each round smarter:

• Leitner spaced repetition. Every topic's verdict history folds into a box: a correct answer promotes it, a miss resets it, a partial holds. The next quiz pulls your least-mastered topics, so weak areas keep coming back until they stick. Boxes are also time-based: a topic you have nailed rests for a while (a week in box 2, three weeks in box 3, two months in box 4) and then falls due again, so "mastered" means "known", not "never asked again".
• Adaptive difficulty. Your recent accuracy tunes the questions: foundational when you're below 60%, harder (edge cases, trade-offs, internals) above 85%.
• Streaks and accuracy. A correct-answer streak and lifetime accuracy show up in the quiz intro and in status to keep you going.
• Offline review drill. python3 ~/.claude/hooks/pop_quiz.py review [N] prints flashcards for the topics that are due. Pure read of the journal, no model and no network.

[!NOTE] Your real journal holds your actual answers, so it's personal and gitignored by default. The repo ships JOURNAL.example.md as a format sample only; your JOURNAL.md never gets committed.

How it works

It's two hooks pointing at one script, wired in your Claude Code settings.json:

Event	Mode	What it does
PreToolUse (all tools)	tool	Increments the per-chat counter silently, records the tool name and files touched for targeted questions, never interrupts
UserPromptSubmit	prompt	Increments, and if the chat crossed its threshold, injects the quiz and resets

Design choices worth knowing:

• Counts all activity, not just messages. A heavily agentic chat with 3 typed messages but 80 tool calls still gets examined. (UserPromptSubmit alone would never fire there.)
• Fires only at a message boundary. Tool calls increment but never inject, so the quiz appears at the start of your next message, never mid-task.
• Per chat. State is keyed by session_id, so concurrent chats each track their own count.
• Randomized threshold (default 40 to 45) so the cadence isn't gameable.
• Self-contained. State lives under <claude-dir>/state/; copy ~/.claude/ to another machine and it just works.

Install

git clone https://github.com/jay739/claude-pop-quiz.git
cd claude-pop-quiz
./install.sh

install.sh copies hooks/pop_quiz.py into ~/.claude/hooks/ and merges the hook config into ~/.claude/settings.json without touching your existing settings (idempotent, safe to re-run). Then open /hooks in Claude Code once, or restart, to load it. New chats pick it up automatically.

Prefer to wire it by hand? Copy the hooks block from examples/settings.json into your settings.

[!TIP] The hook loads automatically in new chats. To activate it in an already-open session, run /hooks once. Requires only Python 3.6+, no pip installs, no dependencies. macOS, Linux, and WSL use a real file lock; native Windows runs in a degraded lock-free mode (no fcntl) rather than failing silently.

Uninstall

./uninstall.sh

This is the beginning of the README. Read the rest at the original. Read the full README ↗