Free tool, runs in your browser

CLAUDE.md analyzer and generator

Paste a CLAUDE.md or AGENTS.md file and get a score out of 100, every problem with its line number, and a cleaned version you can copy back. No AI, no account, no upload.

Nothing leaves your browser. Every check here is plain JavaScript running on this page: regular expressions, string similarity and counting. There is no AI model, no API call, no account and no analytics on this page. Your file is read with the browser's own FileReader and stays in the tab. The only requests this page ever makes are for its own HTML, fonts and icon from locul.ai. There is no third-party request of any kind, and nothing about your file is ever sent anywhere. Open devtools, switch to the Network tab, and analyze a file: you will see the fonts and nothing else.

Works offline. Save the page and it still runs.

Analyze a file

Paste the contents below, drop a .md file onto the box, or pick one from disk. The file is read locally and is not sent anywhere.

Your CLAUDE.md or AGENTS.md contents

Load a file 0 characters

Which kind of file is this

A personal file applies to every project, so it is not expected to carry build and test commands. Choosing it turns those checks off rather than reporting them as gaps.

Generate a starter CLAUDE.md

Fill in what an agent cannot guess. The output is deliberately short, and it is built to score well in the Analyze tab. Pick a package manager and the command fields fill themselves in.

Project name

One line description

Language or runtime

Framework

Package manager

Install command

Dev or run command

Build command

Test command

Lint or typecheck command

Key directories, one per line, as path - what lives there

Conventions, one per line, three to five

Hard do-nots, one per line, three to five

Your CLAUDE.md

Fill the form above and this updates as you type.

What AGENTS.md is

A short, factual answer, with the parts that change over time left to your own tool's documentation rather than guessed at here.

What

AGENTS.md is an open, vendor-neutral convention for a single markdown file at the root of a repository that holds instructions for coding agents. It is documented at agents.md. There is no schema and no required sections: it is ordinary markdown, and the convention is the filename and the location, not the format.

Why

It exists because every agent vendor was inventing its own filename, and a repository worked on by more than one tool ended up with several files saying the same thing and drifting apart. One agreed filename means one file to maintain.

Who reads it

Support is broad and it keeps moving, so treat any list as a snapshot. The well established readers are OpenAI Codex, which drove the convention, Cursor, GitHub Copilot's coding agent and Google Jules. Rather than trusting a list on a web page, check your own tool's current documentation, or just test it: add a line to AGENTS.md that asks the agent to open its first reply with a specific word, and see whether it does.

Versus CLAUDE.md

Same job, same format, different filename. CLAUDE.md is the file Claude Code looks for, and it goes further than a single root file: Claude Code also reads a CLAUDE.md inside the subdirectory you are working in, layered on top of the root one, and a personal file at ~/.claude/CLAUDE.md that applies to all your projects. AGENTS.md aims at the opposite goal, one file that many different tools read.

Both

Do not maintain two copies, they will drift and then contradict each other. Keep one file as the source of truth and make the other name a symlink to it, so both tools read the same bytes:

ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

On Windows, or anywhere symlinks are awkward, the alternative is a one line CLAUDE.md that points at the real file: See @AGENTS.md.

Generate a starter AGENTS.md

These are the same fields as the Generate tab and they stay in sync, so you can fill either one. The output differs: AGENTS.md is written for a repository root read by several tools, so it names the project explicitly and avoids anything tool-specific.

Project name

One line description

Language or runtime

Framework

Package manager

Install command

Dev or run command

Build command

Test command

Lint or typecheck command

Key directories, one per line, as path - what lives there

Conventions, one per line, three to five

Hard do-nots, one per line, three to five

Your AGENTS.md

Fill either form and this updates as you type.

What makes a good CLAUDE.md file?

A good CLAUDE.md is short, specific, and made of commands rather than adjectives.

The test for any line is whether it changes what the agent would do. The exact test command passes: without it the agent guesses, runs the wrong thing, and reports a failure that was never real. Follow best practices fails, because nobody can act differently after reading it.

Four things earn their place in almost every project: the commands to install, run, build, test and lint, written out exactly; a short map of what lives where; the conventions a new contributor would have to be told, meaning the surprising ones rather than the ones a linter enforces; and the genuine do-nots. Everything else is usually a document pretending to be a config file.

Why does CLAUDE.md file size matter?

Because the file is prepended to every request in the project, so its size is a per-turn cost, not a one-off cost.

A 4,000 token CLAUDE.md is a surcharge on every question you ask in that repository, related or not. It also competes for attention with the code the agent is reading, so the three lines that matter carry the same weight as the paragraph about a refactor that finished last spring. Deleting is usually the highest-value edit here: a focused file in the low hundreds of tokens beats a thorough one in the thousands.

What are the most common CLAUDE.md mistakes?

The most common mistake is writing a style guide when the agent needed an operating manual.

No test or build command. The highest-value omission, and the one thing an agent genuinely cannot infer.
Secrets. A key or connection string pasted in for convenience. This file is normally committed, so it is now in the history of every clone. Remove it, then rotate it.
Conflicting rules, usually written months apart. The agent picks one, so the behaviour is no longer yours. A rule written twice is the same warning sign in a milder form.
Machine-specific absolute paths. A path under /Users/yourname works for one person and breaks in continuous integration.
Vague directives. Write good code, be careful, handle errors appropriately. Comforting to write, impossible to act on.
Politeness. Please, thank you, it would be nice if. The agent is not persuaded and you pay for the words.

Why CLAUDE.md files go stale

Because a CLAUDE.md only knows what you last typed into it, and nothing in your workflow reminds you to type again.

Someone writes we are currently on React 18, the team upgrades, and nobody edits the file, because editing it was never part of shipping the upgrade. Six months later the agent is told something false with total confidence, and false context is worse than none: it stops asking and starts assuming. The fix is to write instructions that cannot expire, pointing at the source of truth instead of copying a value out of it.

That burden is not specific to CLAUDE.md. Any file where you hand-write context for an AI starts decaying the moment you save it, which is the problem Locul was built for: rather than you maintaining a context file, it builds a second brain from the sources you already produce, and when a fact changes it marks the old version superseded and makes the new one active, keeping the history.

Where should CLAUDE.md live?

Put the main one at the repository root and commit it, so the whole team gets the same instructions.

Claude Code layers three levels. The root file is the shared one. A CLAUDE.md in a subdirectory is loaded on top of it rather than instead of it, so add one only where that part of the codebase needs different rules. And ~/.claude/CLAUDE.md applies to all your projects and is never committed, which makes it the right home for your local paths and your own habits. If a rule would break for a teammate, it belongs there.

How to use this analyzer

Paste the file, fix the critical findings, then delete before you add.

Fix anything marked Critical: a secret to rotate, a contradiction to resolve, a missing test or build command to write down.
Work through What to strip, which gives the exact lines to delete and a running token estimate.
Copy the cleaned version. It applies only the safe deletions, and marks anything needing your judgement instead of removing it quietly.

Questions

What is a CLAUDE.md file?

A CLAUDE.md is a markdown file that Claude Code reads automatically and prepends to your requests, so it functions as standing instructions for a project. It normally holds the commands to build, test and run the code, a short map of the repository, and the conventions a new contributor would need to be told. Claude Code reads one at the repository root, one in a subdirectory you are working in, and a personal one at ~/.claude/CLAUDE.md.

What makes a good CLAUDE.md file?

A good CLAUDE.md is short, specific, and made of commands rather than adjectives. The test is whether every line changes what the agent would do. Exact commands in a fenced code block pass that test. A line such as follow best practices does not, because there is no action the agent can take differently after reading it. Bullets beat paragraphs, and anything long enough to be a document belongs in a separate file the agent loads on demand.

How big should a CLAUDE.md file be?

Small enough that you would be happy paying for it on every single turn, because that is what happens. The file is prepended to every request in the project, so a 4,000 token CLAUDE.md is a 4,000 token surcharge on every question you ask, and it competes for attention with the code the agent is actually reading. A focused file in the low hundreds of tokens usually outperforms a thorough one in the thousands.

Is this CLAUDE.md analyzer free, and is my file uploaded anywhere?

It is free and nothing is uploaded. Every check is a deterministic JavaScript heuristic that runs in your browser on this page. There is no AI model, no API call, no account and no analytics on this page. Your file is read with the browser's own FileReader and never leaves the tab. The only requests the page makes are for its own HTML, fonts and icon, with no third-party request of any kind. You can verify that yourself: open devtools, switch to the Network tab, and analyze a file.

What is the difference between CLAUDE.md and AGENTS.md?

They do the same job in the same format, and differ mainly in which tool looks for which filename. CLAUDE.md is the filename Claude Code loads, and it supports per-directory files and a personal user-level file. AGENTS.md is an open, vendor-neutral convention for one repository-root file that many coding agents read, documented at agents.md. If you need both, keep one file as the source of truth and symlink the other name to it so they cannot drift apart.

Where should a CLAUDE.md file live in a repository?

Put the main one at the repository root and commit it, so the whole team gets the same instructions. Add a second CLAUDE.md inside a subdirectory only when that part of the codebase genuinely needs different rules, since it is loaded on top of the root file rather than instead of it. Keep anything personal to you, such as your own shell aliases or local paths, in ~/.claude/CLAUDE.md instead, because a machine-specific path in the committed file breaks for every teammate and in continuous integration.

Live, passive, local

Stop hand-maintaining the context your AI reads.

Locul is a second brain for your AI. It builds itself from the notes, documents and dictation you already produce, keeps itself current by superseding facts when they change, and serves the result to Claude Code, Claude Desktop, ChatGPT and Codex, Cursor and OpenClaw over MCP. Local-first on macOS and Windows.

Start free See pricing

Free tier: 500 active memories, local AI, no credit card.