1
Your rules file
You already have a rules file. Here it is.
CLAUDE.md
- answer first, details second
- run the tests before every commit
- no console.log in shipped code
- one commit per change
- ask before touching 3+ files
This file is called CLAUDE.md. Claude Code reads it at the start of every session.

Each line is one instruction you wrote, in your own words. These are five real ones.
2
The problem
Some lines are obeyed, some forgotten. Nothing tells you which.
CLAUDE.md
- answer first, details second
- run the tests before every commit
- no console.log in shipped code
- one commit per change
- ask before touching 3+ files
← ignored today. Nothing told you.
A sentence in a file has no alarm on it.

When a line is ignored, nothing turns red and nothing beeps. You find out later, if at all.
3
The loop
So you correct it. It obeys once. Then it forgets.
you correct
it obeys once
it forgets
you correct again
4 or 5
→
8
of every 100 messages were corrections. June to August 2026, counted from the real chat log. The rules file grew the whole time.
4
A check
A sentence cannot fail. A check can.
the rule, a sentence
- answer first, details second
A check is a small yes-or-no test that the computer runs by itself. It does not read the sentence. It looks at the real thing.
→
the check, a yes-or-no test
Is the answer on line one of the last reply?
yes
no
Nothing in between. No opinion, no AI judging it. Yes means the rule held, no means it broke.
5
The table
Each rule becomes one line in a table: a name, the rule, and its check.
CLAUDE.md
- answer first, details second
- run the tests before every commit
- no console.log in shipped code
- one commit per change
- ask before touching 3+ files
namethe rule, plain wordsthe check (yes = the rule holds)
answer-firstthe answer is line onenode tools/answer-first.mjs
tests-greenthe test suite passesbash tests/run.sh
no-consoleno console.log shipped! grep -rq console.log src
one-commitone change per commitnode tools/one-commit.mjs
ask-first3+ files need a yesnode tools/ask-first.mjs
This table is a file called claims.tsv, one line per rule. You write the check, or you ask Claude Code: "write a check for this rule". Anything that can answer yes or no works.
6
One check runs
Yes, the rule holds. No, the rule is red. Nothing in between.
namethe rule, plain wordsthe check
answer-firstthe answer is line onenode tools/answer-first.mjs
tests-greenthe test suite passesbash tests/run.sh
no-consoleno console.log shipped! grep -rq console.log src
yes
Run one: the answer is on line one. The check says yes. The rule holds.
no
Run two, an hour later: the answer sits at the bottom of a long reply. The check says no. The rule is RED. No opinion, no AI judging it.
7
The timer
Every 30 minutes, whether or not a session is open.
a timer built into your Mac. 48 runs a day.
namethe ruleresult
answer-firstthe answer is line one
tests-greenthe test suite passes
no-consoleno console.log shipped
one-commitone change per commit
ask-first3+ files need a yes
metacognition GREEN: 11 of 11 rules held  · 14:30 · next 15:00
It prints one line and keeps a record on your Mac. No window, no sound, no internet.
8
Session start
Claude Code sees the red rule before it sees your question.
$ claude
metacognition RED: 1 of 11 rules broken: answer-first
 
> what should I work on?
First the red rule: my last reply put the answer at the bottom. From now on it goes on line one.
Now your question: ...
A hook is a small step that Claude Code runs by itself at a fixed moment. This one prints the last verdict as the first line of every session.
9
Corrections
Every correction is logged. The third time, it becomes a check.
"again, answer first"
"redo, the answer is still at the bottom"
"not what I asked. Answer first!"
3 times = a pattern
namethe rulethe check
tests-greenthe test suite passesbash tests/run.sh
no-consoleno console.log shipped! grep -rq console.log src
answer-firstthe answer is line onenode tools/answer-first.mjs
A new line in the table, with its own check. From now on the timer checks it 48 times a day, and the light shows whether the mistake comes back.
10
Nothing stays red
A rule red for more than a day stops Claude Code from ending its reply, until someone decides.
RED for 26 h   tests-green   the test suite passes
Two ways out, and both are decisions. Silence is not one of them.
Fixed it
node red-debt.mjs fixed "tests-green"
Not fixing it now, and why
node red-debt.mjs debt "tests-green"
"the test needs a fix from another team on Monday"
That note lasts 24 hours. Then it asks again. Nothing stays red by accident.
11
The map
Every rule sits on the step where it applies. One look tells you where the work breaks.
ask
plan
build
test
commit
Drawn from the table of rules, fresh every 30 minutes. Red is the rule failing right now. Grey is a rule with no check yet.
12
Proof
Ten rules broken on purpose. Ten caught. Zero false alarms.
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
A test computer with nothing else on it. Ten rules, each broken on purpose: one at a time.
10 of 10 caught
0 false alarms in 20 runs with nothing broken
12 September 2026. The records are on GitHub, in the repo.
13
Install
One line to install. It asks nothing.
$ npx metacognition
installed: the checks, 3 hooks, the table of rules, a timer every 30 min
3 hooks added to settings.json (your other hooks are kept, a backup is written first)
running the checks once ...
metacognition GREEN: 11 of 11 rules held
Paste it into the terminal where you run Claude Code. Mac or Linux. Thirty seconds later you see your first verdict: one line, GREEN or RED, and which rule.
14
Try first, undo
Try it first. Uninstall keeps your data.
$ npx metacognition --dry-run
  would: copy the checks and the hooks to ~/.claude/metacognition/
  would: add 3 hooks to settings.json (backup first)
  would: write the 30-minute timer
dry run: nothing was changed.
$ npx metacognition --uninstall
  removed the 3 hooks, the timer and the code. Your records and your table of rules stay.
15
You might ask
Five questions people ask first.
Who writes the check?
You do, or you ask Claude Code: "write a check for this rule". Anything that can answer yes or no works.
What if a rule has no check?
It stays a note: grey on the map, still visible, never pretending to be checked.
Does it send anything anywhere?
No. No internet, no account. It reads your files and writes one line and one record on your Mac.
Does it slow Claude Code down?
No. One line at the start of a session. The checks run on the timer, not inside your chat.
What does it cost?
Nothing. Free and open, MIT licence. github.com/jazzs-thoughts/metacognition
click, or press → to continue