prumo is an MCP server that inspects coding-agent context files against a git repository, reports stale/broken references, and offers a safe auto-fix plus two measurement reports.
prumo_check — scans context files (CLAUDE.md, AGENTS.md, SKILL.md, .cursor/rules, etc.) and reports case mismatches, broken wikilinks/markdown links/heading anchors, missing paths, commands naming undefined scripts/targets, agent config pointing at nothing, and notes never mentioned in the index; honors .prumo-baseline.json and writes nothing.
prumo_fix — rewrites only case mismatches and paths/links to the names git recorded for renames; leaves unverifiable suggestions alone.
prumo_drift — measures which context sections cite files that changed after the section was last written, ordering the most moved first as a review reading order.
prumo_budget — estimates byte/line/word/token costs of each context file, growth since a commit, and duplicated paragraphs.
All tools are read-only except prumo_fix, and all work over stdio from agents like Claude Code.
Provides a GitHub Action that runs prumo checks in CI, annotates pull request lines with findings, and fails the job when context files need review.
Provides a pre-commit hook that runs prumo checks before each commit.
Three months ago someone wrote this in CLAUDE.md:
The sidebar logo lives in `layouts/AppLayout.vue`.The folder has since been renamed to Layouts, with a capital L. Windows and macOS still open that path, so nothing ever complained. Linux and CI don't, and every agent that reads the file gets sent somewhere that doesn't exist.
That line survived six hand-run audits of the same files. prumo found it in four seconds.
Related MCP server: claude-init
If you already have Node.js 18+ and git, you are ready. Nothing to install, nothing to configure, no account to create. From a terminal inside any git repository:
npx @tomd4vs/prumoprumo locates your context files on its own: CLAUDE.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md, installed skills in .claude/skills/ and the rest. Every file and folder it looks for is in the reference.
For frequent use, install it once:
npm install -g @tomd4vs/prumo # available everywhere on your machine
npm install --save-dev @tomd4vs/prumo # or as a dev dependency of one projectEither way the command is prumo, with zero dependencies. Errors at this step, such as an old Node or a folder that isn't a git repository, are in Troubleshooting.
A clean run:
prumo — 1 context file, 401 files tracked by git
nothing to review.A run with findings, annotated:
prumo — 3 context files, 412 files tracked by git ← what it read
1 historical entry exempt from path checks ← what it skipped on purpose
CASE MISMATCH (1) wrong letter case: works on Windows and macOS, fails on Linux and CI
CLAUDE.md:18 ← file and line
layouts/AppLayout.vue ← what the note says
-> resources/js/Layouts/AppLayout.vue ← what the repository has
BROKEN LINK (2) points at a page or heading that is not there; 1 with a likely destination
CLAUDE.md:21 [[deploy-checklist]] -> deploy_checklist ← the file it probably meant
CLAUDE.md:30 [[old-architecture]] ← no candidate: renamed or deleted
MISSING PATH (1) the note cites it, but git tracks no such file or folder
docs/setup.md:44 config/database.php ← file, line, dead path
Copy the template into `config/database.php`… ← the sentence, so you can judge
4 to review, --fix corrects 1 ← 1 + 2 + 1Every finding carries a file, a line number and the correction, and a missing path says where git moved it when the history holds a rename. Nothing is guessed and nothing is written. What each finding means, and what to do about it, is in the reference. If it flags a line you know is correct, Silencing a finding covers the two ways to say so.
Three limits, chosen on purpose and explained in Design:
It does not judge claims. Whether "this flag disables caching" is still true needs a model, and that is a different tool.
It does not edit beyond letter case and the renames git itself recorded. A link suggested from a name is an educated guess, and a missing path with no history may be missing on purpose.
It makes no network calls. No telemetry, no account, no model.
Every check was measured on public repositories before it shipped, and the design page publishes the numbers, the ugly ones included.
prumo is a plain CLI, so any agent with shell access can run it.
Ask the agent to run it. npx @tomd4vs/prumo works in any git repository, and covers skills installed under .claude/skills/ on its own. For a repository that is itself a skill, name the file: npx @tomd4vs/prumo . SKILL.md. The text output names the file, the line and the correction, which is enough for an agent to act on without parsing. --format json returns the same findings as structured data.
Expose it as a tool. The package also ships prumo-mcp, an MCP server over stdio with four tools: prumo_check, which is read only, prumo_fix, which rewrites letter case and the renames git recorded, and the two reports, prumo_drift and prumo_budget, read only as well. In Claude Code:
claude mcp add prumo -- npx -y -p @tomd4vs/prumo prumo-mcpThe configuration for any other MCP client is in Agents.
Add a slash command. A file at .claude/commands/prumo.md turns the check into /prumo:
Run `npx @tomd4vs/prumo` and fix every finding it reports.Run it after every edit. A PostToolUse hook runs prumo whenever the agent writes a context file, so the findings land in the transcript and it can fix them in the same turn. The hook, for bash and for PowerShell, is in Agents.
prumo exits non-zero on findings, so it drops into a pipeline as a single step. The shortest form is the action this repository ships:
# .github/workflows/docs.yml
name: docs
on: [push, pull_request]
jobs:
prumo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: TomD4vs/prumo@v1It annotates the exact line of the pull request and fails the job when something needs review. npx @tomd4vs/prumo --quiet after actions/setup-node does the same in any pipeline. Use actions/checkout as normal; prumo reads the git index, so a checkout that omits it will not work. Three options cover the rest:
--baseline records what a repository with a backlog already has, once; later runs fail only on what is new.
--since origin/main checks only the context files a pull request touched.
--sarif FILE writes the findings for code scanning, and .pre-commit-hooks.yaml runs the same check before each commit through the pre-commit framework.
The action's inputs, the SARIF upload and the pre-commit block are in the reference.
Beyond the checks, two commands measure instead of judging, and exit 0 whatever they find:
prumo drift # which sections describe code that changed since they were written
prumo budget # what each context file costs the agent, and what is written twicedrift reads from git blame when each section was last written, counts the commits that touched the files it cites since then, and lists the sections most moved first: a reading order for a review, since a section whose files changed forty times may still be right. budget estimates the tokens each file costs at every session, how much that grew since a commit, and which paragraphs are written in more than one place. Both are on the reference, and both are tools of the MCP server.
Page | What it answers |
Every option and exit code, what each finding means, how to silence one, what | |
Every integration in full: the MCP server, the | |
Why so few checks: the measurement that removed the symbol checker, and the filters that keep the rest quiet | |
Error messages, and the questions people ask before adopting it | |
Calling it from code, and running the test suite |
MIT
Reports what each context file costs the agent that reads it at every session: bytes, lines, words and an estimate of tokens at four characters each, largest first; how much each grew since an earlier commit, the one thirty days ago unless since names another; and the paragraphs of twelve words or more written in two places. It measures and counts; nothing here is a finding. Nothing is written.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Path to the git repository. Defaults to the current working directory of the server. | |
| since | No | The commit or branch to compare sizes with. Omit for the commit thirty days ago, or the first commit of a younger repository. | |
| targets | No | Markdown files or folders to check, relative to the repository. Omit to auto-detect CLAUDE.md, AGENTS.md, installed SKILL.md files and the rest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description reinforces this with 'Nothing is written' and 'It measures and counts', adding clarity about its observational nature and that it produces no findings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single run-on sentence but remains readable. It is front-loaded with the core purpose, yet the inclusion of multiple clauses (growth, paragraphs, ordering) makes it slightly dense. Still, it avoids unnecessary fluff and is relatively concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully specifies what is measured (bytes, lines, words, tokens, growth, paragraphs), the ordering ('largest first'), and the default time window ('thirty days ago'). It also clarifies that it is not a finding tool, making its role complete for a reporting utility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters (repo, since, targets) at 100% coverage, including defaults and auto-detection behavior. The main description adds minor detail like 'largest first' ordering but does not materially enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports context file costs (bytes, lines, words, token estimate) and provides growth metrics since a commit, with explicit ordering. It also distinguishes itself from a 'finding' tool, which helps differentiate it from siblings like prumo_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for session-based budget tracking ('at every session') and clarifies it is not for findings, but it does not explicitly name sibling tools or state when to prefer this over prumo_check, prumo_fix, or prumo_drift.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the context files a coding agent reads (CLAUDE.md, AGENTS.md, SKILL.md, .cursor/rules and the rest) against the git index of a repository. Reports paths whose letter case disagrees with git, broken [[wikilinks]], markdown links and heading anchors, paths that no longer exist, commands naming a script or target no package.json, Makefile or composer.json defines, agent configuration that points at nothing (a rule whose globs match no file, a skill without a description, an MCP server or a hook naming a missing script), and notes an index never mentions. Findings recorded in a .prumo-baseline.json at the repository root are held back and counted in stats.baselined. Nothing is written.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Path to the git repository. Defaults to the current working directory of the server. | |
| targets | No | Markdown files or folders to check, relative to the repository. Omit to auto-detect CLAUDE.md, AGENTS.md, installed SKILL.md files and the rest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/destructive/idempotent hints, the description discloses a genuinely non-obvious behavior: findings recorded in .prumo-baseline.json at the repository root are held back and counted in stats.baselined. It also explicitly confirms 'Nothing is written.' No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded: purpose first, then a detailed finding taxonomy, then baseline behavior, then the read-only guarantee. The enumeration of finding types is verbose yet earns its place because it is exactly what an agent needs to decide whether to invoke the check; slightly tighter phrasing would reach 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only checker with no output schema, the description exhaustively covers what is checked, discloses the baseline suppression mechanism, and explicitly guarantees no writes. The only gap is the unstated output/return format (stats.baselined is mentioned but not the overall response shape), which is minor given the tool's clearly defined purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds marginal value by spelling out the auto-detected file set (CLAUDE.md, AGENTS.md, SKILL.md, .cursor/rules and 'the rest'), which fleshes out what omitting targets means, but the schema already documents both parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Checks') with a well-scoped resource: the context files a coding agent reads, compared against the git index of a repository. It enumerates nine concrete categories of findings, and the closing 'Nothing is written' separates it cleanly from the prumo_fix sibling. This goes far beyond a restatement of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's nature clear — a read-only validation pass over agent context files — and 'Nothing is written' implicitly contrasts with prumo_fix. However, it never explicitly names alternatives or states when to prefer this tool over prumo_fix or prumo_drift, so usage guidance stays at the implied level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports which sections of the context files describe code that changed after the section was last written: for every section that cites a file or a folder the repository has, when the section last changed according to git blame, how many of the files it cites changed since, and how many commits touched them. Sections come back ordered, the most moved first. It is a reading order for a review, never a finding: a section whose files changed may still be right. Nothing is written.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Path to the git repository. Defaults to the current working directory of the server. | |
| targets | No | Markdown files or folders to check, relative to the repository. Omit to auto-detect CLAUDE.md, AGENTS.md, installed SKILL.md files and the rest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description explains the git-blame-based drift computation, the ordering of results, and that a changed section 'may still be right.' It also explicitly reassures that 'Nothing is written,' adding meaningful behavioral context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence contributes value: the report computation, ordering, review interpretation, and safety confirmation. The first sentence is long and somewhat complex, but the information is efficiently packed and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains what is returned: sections, file-change counts, commit counts, and ordering by 'most moved first.' It is complete enough for a read-only reporting tool, though it does not specify the exact output structure or edge-case behavior for empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's algorithm explanation clarifies the conceptual meaning of the targets as context-file sections, but it does not add new details about repo path resolution or target format beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Reports', and names the resource: sections of context files that have drifted from cited code changes. It also distinguishes itself from siblings by framing the output as 'a reading order for a review, never a finding,' so an agent can tell prumo_drift apart from prumo_check or prumo_fix.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool: to get a review reading order of drifted context sections. It also provides an exclusion, 'never a finding,' but it does not explicitly name sibling alternatives or say when prumo_check/fix/budget should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrites case mismatches in place to the spelling the git index holds, and a missing path or a markdown link to the name git recorded when it renamed the file, then reports what remains. Nothing else is touched: a link suggested from a name, a missing path with no history and a deleted file are never edited.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Path to the git repository. Defaults to the current working directory of the server. | |
| targets | No | Markdown files or folders to check, relative to the repository. Omit to auto-detect CLAUDE.md, AGENTS.md, installed SKILL.md files and the rest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond the annotations: it edits 'in place', reports what remains, and explicitly delimits what it will never touch (suggested links, missing paths without history, deleted files). This complements the idempotentHint and destructiveHint annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary behavior is front-loaded, and the exclusion list is packed into a clear second sentence. Every clause contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two optional parameters and no output schema, the description covers the key action, its scope, and the fact that results are reported. It does not elaborate on the exact format of the report, but the 'reports what remains' phrase gives sufficient expectation for an agent without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline applies. The description does not add any parameter-specific meaning; it focuses on tool behavior. With both 'repo' and 'targets' already well-documented in the schema, no additional semantic guidance is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('rewrites') and resource (case mismatches in git index spelling, missing paths/links to renamed files), and explicitly distinguishes itself from siblings by describing exactly what it fixes. The boundary statement 'Nothing else is touched' further clarifies the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when case mismatches or renamed-file paths need fixing—but does not explicitly name alternatives like prumo_check or prumo_drift. It does provide strong when-not guidance by listing cases that are never edited, which helps an agent avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0prumo_budgetprumo_checkprumo_driftprumo_fixScored across 4 tools
Each tool has a distinct responsibility: check audits, fix repairs safe path/link issues, drift measures staleness, and budget measures size. There is no real overlap; check/fix are clearly read vs. write counterparts.
All tools follow the same prumo_ prefix with a single lowercase operation word, giving the set a uniform and predictable command surface. The names are short and consistently formatted.
Four tools is well-scoped for a focused context-file health server; each tool earns its place. The set is neither too thin nor overloaded.
The core lifecycle of audit, safe repair, drift review, and cost measurement is well covered. The main gap is that prumo_fix only handles a subset of the findings prumo_check reports, leaving broken wikilinks, dead commands, and dangling agent config to manual fixes.
Research-backed linting + generation for agent context files (CLAUDE.md, AGENTS.md, Cursor rules).
Static linter for CLAUDE.md-style agent constitution files: 10 operational-guardrail checks.
Static linter for CLAUDE.md-style agent constitution files: 10 operational-guardrail checks.
MEOK AGENTS.md Linter MCP — validates the cross-vendor coding-agent spec (Cursor / Claude Code /
