Pop Quiz para Claude Code
jay739/claude-pop-quiz
Quiz automático e obrigatório para você dominar seu próprio código gerado por agent
Ver no GitHubUm hook de gamificação obrigatório que pausa automaticamente suas sessões com Claude Code a cada ~40-45 ações e faz quiz sobre o código e decisões que o agent tomou. Usa repetição espaçada (Leitner) para revisar áreas fracas e ajusta dificuldade conforme seu desempenho, gerando um journal de aprendizado versionável.
Instalação
npx convez-ai jay739/claude-pop-quiz1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Garantir compreensão real do código gerado por agents, não apenas acumular tokens
- Treinar memória técnica e justificar decisões em code reviews e entrevistas
- Manter registro versionado de aprendizado com spaced repetition e dificuldade adaptativa
- Revisar offline com drill de flashcards dos tópicos com pior desempenho
Veredito

Abordagem criativa contra context loss em coding agents — força aprendizado ativo em vez de passividade. Bem implementada com Leitner e journal, mas exige disciplina do usuário para integrar em fluxo de trabalho real sem virar irritante.
README
A tradução para o português deste README ainda está na fila.
🎓 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" — 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–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 is also read back in to make each round smarter:
- Leitner spaced repetition. Every topic's verdict history folds into a box — a ✅ promotes it, a ❌ resets it, a 🟡 holds. The next quiz pulls your least-mastered topics and retires the ones you've nailed, so weak areas keep coming back until they stick.
- Adaptive difficulty. Your recent accuracy tunes the questions: foundational when you're below 60%, harder (edge cases, trade-offs, internals) above 85%.
- Streaks + accuracy. A correct-answer streak and lifetime accuracy show up in the quiz intro and in
statusto keep you going. - Offline
reviewdrill.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.mdas a format sample only — yourJOURNAL.mdnever 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. (
UserPromptSubmitalone 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–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/<you>/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
/hooksonce. 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 (nofcntl) rather than failing silently.
Uninstall
./uninstall.sh
Removes ~/.claude/hooks/pop_quiz.py and strips the two hook entries from
~/.claude/settings.json. State and journal are preserved — delete them manually
if you want a clean slate:
rm ~/.claude/state/pop_quiz_state.json
rm ~/.claude/state/pop_quiz_state.json.lock
🔄 Staying up to date
The hook checks itself for updates — no need to remember to git pull.
[!NOTE] This daily version check is the hook's only outbound network request — a single
GETto GitHub for the latest script. It sends nothing about you or your code. Turn it off completely withPOP_QUIZ_NO_UPDATE_CHECK=1.
-
Once a day (on a normal
UserPromptSubmit), it quietly asks GitHub whether a newer__version__exists. The check is throttled to once per 24h, time-boxed to ~2s, and fully offline-safe — any failure is swallowed so the hook never breaks or slows you down. Tool calls never hit the network. -
When a newer version is found, it appends a one-line nudge to its next message ("a newer version is available — run
… update"). You're told once per new version, not nagged every turn. -
Hands-off auto-update (opt-in): set
POP_QUIZ_AUTO_UPDATE=1and the daily check self-applies the new version instead of nudging — it downloads, backs up to.bak, atomically replaces the running script in place, and tells you once to reload. It's opt-in by default because auto-running code pulled from the network is a (small, it's your own repo) risk worth choosing deliberately. -
To upgrade in place manually any time:
python3 ~/.claude/hooks/pop_quiz.py updateThis downloads the latest hook from GitHub, backs up the current one to
.bak, and overwrites the running script keeping its installed filename. Restart Claude Code (or/hooks) to load it. Updates touch only the script file, so your state, journal, and defer count are guaranteed untouched (a regression test enforces this).
Check the version and update status any time:
python3 ~/.claude/hooks/pop_quiz.py status
The update command writes to its own path, so it works no matter what the
installed file is called — if you renamed it (e.g. grill_reminder.py), it
upgrades that file in place and keeps the name. Existing installs predating the
update checker need one manual update (or re-run install.sh) to gain it;
after that they self-notify.
Forked the repo? Point the checker at your copy with POP_QUIZ_REPO=you/your-fork
(and POP_QUIZ_BRANCH=…). Want no network at all? Set POP_QUIZ_NO_UPDATE_CHECK=1.
Scope
- Put the hook in
~/.claude/settings.json(user scope) → fires in every project. - Put it in a project's
.claude/settings.json→ fires only in that project.
🔧 Configuration
Everything is optional and tweakable — the hook ships with sane defaults and nothing is hard-coded into the script. Every knob is an environment variable:
| Variable | Default | What it does |
|---|---|---|
POP_QUIZ_MIN | 40 | Lower bound of the random action threshold (how often it fires) |
POP_QUIZ_MAX | 45 | Upper bound of the random action threshold |
POP_QUIZ_QUESTIONS | 5 | Number of questions per check |
POP_QUIZ_FORMAT | essay | essay, mcq, or mixed — see Quiz format |
POP_QUIZ_DEFER_LIMIT | 0 | Consecutive defers (across all chats) before tool use freezes; 0 = soft mode, never freeze |
POP_QUIZ_JOURNAL | <claude-dir>/state/learning_journal.md | Where the graded journal is written |
POP_QUIZ_JOURNAL_MAX_ENTRIES | 0 | Keep at most this many dated entries in the journal; 0 = unlimited |
POP_QUIZ_REPO | jay739/claude-pop-quiz | owner/repo the update checker pulls from (set if you forked) |
POP_QUIZ_BRANCH | main | Branch the update checker pulls from |
POP_QUIZ_NO_UPDATE_CHECK | (unset) | Set to any value to disable the daily online version check entirely |
POP_QUIZ_AUTO_UPDATE | (unset) | Set to any value to auto-apply a newer version on the daily check (else just nudge) |
How to set / change them
These values get baked into the hook command in your ~/.claude/settings.json.
Two ways to change them — both safe to repeat:
-
Re-run the installer with env vars (it rewrites the command for you):
POP_QUIZ_FORMAT=mcq POP_QUIZ_DEFER_LIMIT=3 ./install.shRun with no env and it also prompts you for format, defer limit, and max journal entries.
-
Edit the command directly in
~/.claude/settings.json— prepend the vars to both theUserPromptSubmitandPreToolUsecommands (the freeze needsPOP_QUIZ_DEFER_LIMITon both):"command": "POP_QUIZ_MIN=90 POP_QUIZ_MAX=110 POP_QUIZ_QUESTIONS=3 POP_QUIZ_FORMAT=mcq POP_QUIZ_DEFER_LIMIT=3 POP_QUIZ_JOURNAL=$HOME/notes/learning_journal.md python3 ~/.claude/hooks/pop_quiz.py prompt 2>/dev/null || true"
Changes take effect on new chats (or after /hooks). To see the current state at any time without opening Claude Code:
python3 ~/.claude/hooks/pop_quiz.py status
This prints the active sessions, action counts, defer tally, lock state, and lifetime quiz stats.
Common tweaks:
- Quiz less often: raise
POP_QUIZ_MIN/POP_QUIZ_MAX(e.g.90/110). - Go fast:
POP_QUIZ_FORMAT=mcq— one-line answers. - Force discipline:
POP_QUIZ_DEFER_LIMIT=3— freeze after 3 skips. - Back up your journal: point
POP_QUIZ_JOURNALat a tracked path. By default it's understate/(gitignored — personal data). - Cap journal size:
POP_QUIZ_JOURNAL_MAX_ENTRIES=100— Claude trims the oldest entries after each grading pass. - Turn it off entirely: run
./uninstall.sh, or remove the hook block fromsettings.jsonmanually.
🎯 Quiz format & "can't I just skip it?"
Format: pick your friction
POP_QUIZ_FORMAT | What you get |
|---|---|
essay (default) | Free-response answers in your own words. If you're short on time, Claude offers the MCQ quick version of the same questions. |
mcq | Every question is multiple choice (A–D, one correct). You answer in a single line of letters — e.g. 1C 2A 3D 4B 5A. Seconds, no typing. |
mixed | Half free-response, half multiple choice. |
Either way you're graded, corrected, and journaled — a 15-second MCQ round is real revision, not a bypass.
[!NOTE] MCQ options are constrained to be ungameable: all four roughly equal in length and specificity, the correct letter varied across questions, and distractors that encode real misconceptions. The old "just pick the longest option" tell no longer works.
Defer & the hard stop
When a quiz fires you can defer — say "defer" / "skip quiz", or just keep
working. But defers are counted globally, across every chat (opening a fresh
chat doesn't reset them). Once you hit POP_QUIZ_DEFER_LIMIT, the PreToolUse
hook denies every tool call — Claude can talk but can't edit, run, or search
anything until you answer a quiz. Submitting an answer (the hook recognizes the
one-line 1C 2A 3D 4B 5A shape) resets the counter and unlocks.
[!WARNING] The freeze is global — once the defer limit is hit, every chat is frozen, not just the one you deferred in. Answering any pending quiz unlocks them all. Set
POP_QUIZ_DEFER_LIMIT=0(the default) to stay in soft mode and never freeze.
"command": "POP_QUIZ_FORMAT=mcq POP_QUIZ_DEFER_LIMIT=3 python3 ~/.claude/hooks/pop_quiz.py prompt 2>/dev/null || true"
Honest about the limits
This is a discipline gate, not a vault. Two things no hook can do:
- Judge understanding. The hook checks an answer's shape, not its correctness — only the model grades that, and the model is cooperative, so it can be talked past. The hard stop forces you to submit an attempt, not to pass.
- Defend against its owner. It's your
settings.jsonand your script — one commented line disables it. It exists to stop drift, not a determined you.
The real lever is making the quiz cheap (MCQ = seconds) so answering beats dodging. The freeze is the backstop for when you'd otherwise let it slide.
Live per-question timer? Not possible in Claude Code — it's turn-based, and nothing runs during your think-time to enforce a countdown or auto-skip. The hook can read the clock and log how long you took, and a non-answer counts as a defer, but there's no live 15-second timer.
📁 Per-project topic hints
Drop a .pop-quiz-topics file in any project root (one topic per line; # lines are
comments). When a quiz fires in that project, the hook reads the file and tells Claude
to draw questions from those topics instead of guessing from the conversation alone:
# .pop-quiz-topics — Rust async project
Rust ownership and borrowing
async/await and tokio task model
error handling with anyhow / thiserror
The hook walks up from cwd to ~ — so a single file at ~/work/.pop-quiz-topics
covers every project under ~/work/ unless a closer file overrides it.
🔍 Targeted questions via tool context
The PreToolUse hook now records every tool name and the files it touches into the
session state. When a quiz fires, the directive includes a summary like:
Tools used this session: Edit(auth.py, config.json), Bash(), Read(auth.py, README.md)
This gives Claude concrete anchors to ask about — the actual files you changed — rather than having to reconstruct activity from conversation history.
🌍 Portability / cross-device
Claude Code stores settings, hooks, and state on the local filesystem — none of
it syncs through your Claude account. This hook is built to travel: no absolute
paths are baked in. Both the counter state and the default journal live under
<claude-dir>/state/, so you have two clean options:
- Copy
~/.claude/to the new machine — hooks, state, and journal come with it and just work. - Clone this repo + run
./install.shon each device — installs the hook and merges the config. The journal defaults to<claude-dir>/state/learning_journal.mdthere; setPOP_QUIZ_JOURNALif you want it somewhere tracked/backed-up.
Because the default is relative to <claude-dir>, the same hook works on every
machine with zero edits.
🔗 Related / prior art
I built this independently to solve my own problem — staying fluent in work an agent
did on my behalf. After building it I found
flyte/claude-code-quiz-master,
which targets the same "agentic context loss" problem with a manual /quiz
command and adds nice extras (grading levels, a review queue, module-focused quizzes,
forcing you to open files). Credit to them for prior work on the idea.
This project differs in approach: it's a mandatory, automatic hook that fires on an action-count cadence (every ~40–45 actions) across every chat, rather than a command you have to remember to run. The two are complementary — pull vs. push.
📜 Changelog
Version history lives in CHANGELOG.md. Current release: v0.4.0
(spaced repetition, accuracy in status, fairer MCQs, and the synthetic-prompt /
concise-answer bug fixes).
📄 License
MIT © 2026 Jayakrishna Konda — see LICENSE.