CLAUDE.md checker
Paste your CLAUDE.md or AGENTS.md and see what it costs your agent every session, which rules it is missing and what to cut.
Example, for illustration
About 2,300 tokens, read at the start of every session.
About 1.2% of a 200,000 token context window, every session.
MajorMost of this file is installer text
Three blocks pasted in by tools are read at the start of every session and say nothing about this project.
In CLAUDE.mdAbout 1,800 tokens
CriticalNo rule about env files
Nothing tells the agent which files hold secrets, so nothing stops it reading or committing them.
In CLAUDE.md
Nothing found here.
MajorTwo rules about builds disagree
One block says to run the build before every commit; your own rule says never to.
In CLAUDE.md
What is a CLAUDE.md file?
A CLAUDE.md file is a plain Markdown file that Claude Code reads at the start of every session. It is where you tell the agent the things it cannot work out from the code: the commands that build and test the project, the conventions you follow, and the rules it must not break.
Claude Code looks for it in a few places. ./CLAUDE.md or ./.claude/CLAUDE.md holds the project file your team shares through git. ~/.claude/CLAUDE.md holds your personal preferences for every project. ./CLAUDE.local.md holds notes for one project that only you need, and should go in .gitignore. Run /init in Claude Code to draft a first file, then check it here.
What the check looks at
Claude Code reads your CLAUDE.md at the start of every session, so every line costs context before you type anything. The check counts the tokens and shows what share of a 200,000 token window the file takes, every session.
Guardrails a real project needs and most files leave out: secrets, who deploys, database changes, destructive git commands, the test command and what the agent must never touch. The database rule is only asked for when your project has a database.
Text that tools paste into your file when you install them. It is read every session and usually says nothing about your project. Some tools write the block back if you delete it, and the check tells you which.
Two rules that contradict each other, rules too vague to follow (“be careful with the database”), rules that point at files or commands that no longer exist, and instructions planted inside the file that try to steer the agent somewhere you did not intend.
CLAUDE.md best practices
A CLAUDE.md is the briefing your agent reads before every session. The good ones are short and specific, and they hold only what the agent cannot work out from the code. Write each rule so you could check whether it was followed. “Run npm test before saying a change is done” can be checked. “Test your changes” cannot.
Keep it under 200 lines. Put commands first, since the agent needs them most. Move anything that only matters for one folder into a scoped rule or a separate file the agent reads when it gets there. If two rules disagree, the agent may follow either one, so read the file top to bottom after every edit.
Then cover the guardrails. These are the six areas the checker asks about, with a line for each that passes:
Which files hold secrets the agent must never read or commit?
Never read, print or commit .env files. Secrets live in .env.local only.
Who deploys to production, and may the agent ever do it?
Only Sam deploys to production. Never run vercel --prod.
How do database changes happen here, and what must the agent never run?
Schema changes go in a new file under supabase/migrations. Never run db push.
Which git commands must the agent never run?
Never run git reset --hard, git push --force or git stash on my work.
What command runs your tests?
Run npm test before saying a change is done.
Which files or folders must the agent never change?
Do not touch src/legacy/ or anything under vendor/.
A CLAUDE.md template that passes
This is a complete file for a small Next.js and Supabase app. It is about 30 lines, covers all six areas and states the stack, so the agent does not have to guess. Swap in your own commands and names, then paste it into the checker above to see where yours differs.
# Acme dashboard Next.js 15 app on Supabase. Deployed on Vercel. ## Commands - npm run dev: local server on port 3000 - npm test: unit tests (Vitest). Run before saying a change is done. - npm run lint: must pass before commit ## Layout - src/app: routes - src/lib/db: every database query lives here - supabase/migrations: schema changes, one file per change ## Rules - Never read, print or commit .env files. Secrets live in .env.local only. - Schema changes go in a new migration file. Never run db push. - Only Sam deploys to production. Never run vercel --prod. - Never run git reset --hard, git push --force or git stash on my work. - Do not touch src/legacy/. It is frozen until the rewrite. ## Conventions - Server components by default. Add "use client" only for state or effects. - Dates are stored in UTC and shown in the user's time zone. See @docs/api-conventions.md before changing anything in src/app/api.
The last line uses an @import. Claude Code loads the imported file along with this one, which keeps the main file readable. It still counts toward the tokens read every session.
CLAUDE.md or AGENTS.md?
Claude Code reads CLAUDE.md. AGENTS.md is the shared file other coding agents read, and Claude Code can use a repository's AGENTS.md too. If your team uses more than one agent, keep the rules in AGENTS.md and make CLAUDE.md a single line that imports it:
@AGENTS.md
Then there is one file to keep current, and Claude-only notes can go below the import. Check AGENTS.md the same way: paste it above.
Questions
Is it free?
Yes. Without an account you get the score, the token cost and the top three findings, and it counts as one of the 3 free checks a day you share with the prompt checker. With a free account you see every finding for one file, paid from the monthly allowance a free account gets. Pro checks up to 10 files at once against your project's saved memories and writes the fixed file.
Do you keep my file?
No. The file is checked and not stored unless you sign in and save the result.
Which files can I check?
Any agent instruction file as plain text: CLAUDE.md, AGENTS.md, .cursorrules, a file from .cursor/rules or .github/copilot-instructions.md. Paste one file here. Your global ~/.claude/CLAUDE.md works too.
How long should a CLAUDE.md be?
Anthropic's guidance is under 200 lines per file. Longer files cost more context and the agent follows them less reliably. Splitting a long file with @imports keeps it tidy but does not save tokens, because imported files load with the file that imports them.
Can I check from inside Claude Code?
Yes. The FixMyPrompt plugin adds a /fmp:doctor command that runs the same check on the agent files in your repo.
Checking a prompt instead of an agent file? Use the prompt checker.