TL;DR Turn it on with
/plugin enable cc-plugin-you-should-know@builtin. When a note shows up above the prompt, press 1 for the full explanation, or 2 if you already knew, and it won't bring that topic up again.
You should know is a mod built into Claude Code since v2.1.287, off by default. While Claude works on a long task, a second agent reviews the conversation every 6 steps and, when it finds something you might miss, leaves you a note above the prompt. Claude doesn't stop: it keeps working while you read.
What it caught
I tried it on a test project: a price sync against a supplier API that allows 10 requests per second and bans the key for an hour if you go over. I asked Claude for retries, a command to run it, and tests. Claude added a throttle of about 8 requests per second, and the tests passed. Six steps in, this appeared (my session was in Spanish, so the notes were too; translated here):
✦ Heads up · The 10 requests per second limit only holds within one run.
If two syncs overlap, together they go over it and the supplier bans the key.
1: Learn more 2: Knew this already 0: Dismiss
I pressed 1:
Two syncs at once can get the key banned
- The supplier allows 10 requests per second per key, retries included. Go over it
and the key is banned for an hour, and the shop shows stale prices.
- The main agent throttles each run to about 8 requests per second. That throttle
lives inside the process, so two processes don't know about each other.
- With 200 SKUs, a run takes about 25 seconds, more with retries. If a cron starts it
often, or someone runs it by hand while another is going, together they pass 16
requests per second.
- Make sure two never run at once, for example with a file lock (flock) in the cron.
1: Understood 2: Chat in main session 0: Dismiss
It's right: the throttle is a class inside the process. No test was going to catch that. Another run of the same task flagged something else: Claude had made up a list_skus() function on the supplier client, which the real API may not have, and the tests passed because they only talk to the fake client.
Notes come in the language you write in. Tagged Heads up, a note is about a decision Claude made in this session. Tagged You should know, it's about how something works that matters for your work. When nothing clears the bar, it says nothing.
Turn it on
1. Check your version
claude --version
You need 2.1.287 or later.
2. Enable the mod
Inside a session:
/plugin enable cc-plugin-you-should-know@builtin
Or from your shell, and it's there in your next session:
claude plugin enable cc-plugin-you-should-know@builtin
To turn it off, the same with disable. It's one of the mods that ship with Claude Code, like /diff.
What to do with each note
| Key | On the note | After Learn more |
|---|---|---|
| 1 | Learn more: asks for the full explanation | Understood: closes it |
| 2 | Knew this already: never offers that topic again | Chat in main session: puts the note in your prompt so you can raise it with Claude |
| 0 | Dismiss: closes it for now | Dismiss |
If you keep sending prompts without answering, the note goes away on its own after two. Ignore notes that way several times in a row and the mod starts skipping checks: one, then two, four, up to sixteen.
What it costs
claude plugin details cc-plugin-you-should-know@builtin reports 0 always-on tokens per session: it adds nothing to Claude's context. What it spends is the checks. Each one is an extra request to your session's model with the whole conversation, which the API serves mostly from the prompt cache, billed to your plan like the rest of the session. There's at most one every 6 steps of a turn, plus one each time you press Learn more. In my runs, each check took 7 to 12 seconds in the background.
That's why it only shows up on long tasks: a turn under 6 steps never gets checked.
If you never see it
- Short turns. Under 6 steps, no check.
- Where you run it. It only draws in the terminal and in the Code tab of the Desktop app. The VS Code panel and
claude -pshow nothing. - Your account. It's for sessions signed in with your Claude account and telemetry on, and it isn't available in organizations with HIPAA or zero data retention. If
/plugindoesn't list it under Installed with Show disabled, it isn't available to you. - To check it's working. Start with
CLAUDE_CODE_YOU_SHOULD_KNOW_DEBUG=1and each check leaves a line such asdebug · check 1 · step 6 · shown · 11.5s. That variable isn't documented: it comes from the v2.1.293 binary.
Official docs: Mods built into Claude Code
Requirements
- Claude Code v2.1.287 or later. Tested on v2.1.293 with Opus 5.5 on October 12, 2026.