plugin canary-in-a-claude-mine
Canary in a
Claude mine.
A long Claude Code session does not fail loudly. It fills up, and somewhere past the hour mark the answers get a little more confident and a little less true. You notice two or three replies later, when something it told you turns out not to exist.
This plugin gives you the moment before that. One small mark as the very first thing in every reply, and a hook that notices the turn it goes missing. That turn is your signal to clear the window and brief it again.
Get it on GitHub Read the limits firstWhy it exists
Models drop their least important instruction first. That is the whole trick, and I did not invent it: a post on agentsroom.dev described putting a throwaway instruction in your project file and watching for the day it disappears. Begin every reply with a name. When the name is gone, the session is going.
What the post left to you was the watching. You have to notice a missing word, every reply, while you are busy with the actual work. I built the part that does the noticing, and a log that writes down at which turn it happened, so after a few sessions you know when your own sessions start to slip instead of guessing.
What it does
Plants the word
When a session starts, it hands Claude one instruction: the very first characters of every message it writes in a turn are 🐤 and a period: the short lines before a tool call and the final reply alike, before any greeting or heading. A prefix, never a sign-off. Any word or a single emoji works. Nothing to add to your project file, though a two-line section at the top of it makes the first turn stick. It plants the word again after every clear and every compact, so the tripwire is always armed.
Checks every turn
At the end of each turn it reads the transcript and looks at the first word of the reply. Present, nothing happens. You never see it work.
Raises the alarm once
The turn the word is missing, it stops Claude from ending the turn. It reads its own log first: if the word was never there yet, or sits at the end of the message instead of the start, that is a placement slip, not degradation, and the hook asks for the same reply with the word first and nothing else. If the word had been there for turns and is now gone, that is the drop, and Claude has to tell you in one line: the canary dropped, look twice at the last couple of replies, compact or clear and brief again. Once, not a nag. If your workspace keeps session notes, it writes them first, so nothing is lost in the reset.
Keeps the record
Every turn goes in a small log with its turn number, and every miss with its kind: misplaced, unprimed, or a real drop. Read it after a week and you have a real number for when your sessions degrade, measured on your own work, instead of a rule of thumb from someone else's.
What it cannot do
It is a proxy, not a measurement. A dropped word means attention has diluted. It does not prove the next answer is wrong, and a present word does not prove it is right. Expect the odd false alarm and the odd miss.
It cannot fix a bloated project file. If your CLAUDE.md is enormous, attention is diluted from the first turn and no canary will tell you. Trimming the file is the fix. This only tells you when the session on top of it has gone stale.
It does not clear the window for you. A hook cannot run that command. You do. And it only watches the main conversation, not the helpers Claude spins up on the side.
The price is one word of noise at the top of every reply. I find it disappears after a day. You may not.
Installing it
It is a Claude Code plugin. Python that ships with your Mac, nothing else, no account, no service in the middle, and it never calls out to the internet. Two commands inside Claude Code:
/plugin marketplace add aguevara92/Canary-in-a-Claude-mine /plugin install canary-in-a-claude-mine@canary-in-a-claude-mine
Want a different word? Write it to a file and the plugin picks it up:
echo Sparrow > ~/.claude/canary
Pick one that never shows up in a normal reply. That is the only rule.
Read the repoMost of what I build ends up looking like this
A small, specific thing that removes one real problem. Somebody else had the idea; the work was making it run without a human watching. If that is the kind of help you want inside your own business, that is what I do.
or just take the code, it is yours
Talk to me