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 layouts/AppLayout.vue -> resources/js/Layouts/AppLayout.vue
↑ what the note says ↑ 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, and when it stays quiet about a line you expected it to flag, prumo --explain CLAUDE.md:12 says what it read there and which filter decided (why a line was or was not reported).
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 five tools: prumo_check, which is read only, prumo_fix, which rewrites letter case and the renames git recorded, and the three reports, prumo_drift, prumo_budget and prumo_coverage, 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, three 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 twice
prumo coverage # which folders of the code no context file mentions, most active firstdrift 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 what the context files cost at every session, with the files a CLAUDE.md imports, and what they add only when a skill, a folder's note or a scoped rule is used, how much that grew since a commit, and which paragraphs are written in more than one place. coverage lists the folders of the code, package by package in a workspace, that no context file mentions, the most commits in ninety days first: what the agent is never told about. All three are on the reference, and all three 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 the context files cost the agent: bytes, lines, words and an estimate of tokens at four characters each, and when each is read, at every session with the files a CLAUDE.md imports, or only when used, as a skill, the note of a folder or a scoped rule is, the cost at every session 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 declare readOnly/idempotent/non-destructive, and the description corroborates with 'Nothing is written.' It adds genuine behavioral context beyond the annotations: the default comparison point (the commit thirty days ago), auto-detection of CLAUDE.md/AGENTS.md/SKILL.md, and the per-session vs. on-demand reading distinction. The garbled syntax undercuts the value, but the content is there.
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 core is one sprawling run-on sentence whose middle clauses ('when each is read, at every session with the files a CLAUDE.md imports, or only when used...') are close to unparseable, followed by two short tag sentences. The verb is front-loaded, but the structure fails to make the content scannable.
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 zero-required-parameter, read-only reporting tool with no output schema, the description does convey what is measured (bytes, lines, words, token estimate at 4 chars, growth since a commit, duplicated long paragraphs) and the default behaviors. It is substantively complete even though the prose is hard to follow.
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 schema already documents repo, since, and targets, including their defaults and auto-detect list. The description restates the same default ('the one thirty days ago') and auto-detection behavior without adding syntax or format detail, so baseline 3 applies.
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 first clause states a specific verb and resource: 'Reports what the context files cost the agent: bytes, lines, words and an estimate of tokens.' It also distinguishes itself from diagnostic siblings by asserting 'nothing here is a finding,' implying contrast with prumo_check, though it never names any sibling outright.
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?
There is no explicit when-to-use statement and no named alternative among prumo_check, prumo_fix, prumo_coverage, or prumo_drift. The only oblique guidance is 'It measures and counts; nothing here is a finding,' which hints the tool is for measurement rather than issue detection but leaves the routing entirely to inference.
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, heading anchors and @ imports of a CLAUDE.md, 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?
Annotations already cover readOnly/idempotent/non-destructive, and the description usefully reinforces this with 'Nothing is written' while adding real behavior context: baseline suppression via .prumo-baseline.json and stats.baselined. It does not describe output format, but that is secondary for a read-only checker.
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 purpose is front-loaded in the first clause, followed by a dense but purposeful enumeration of finding categories, ending with the baseline rule. The long list is information-heavy rather than padded, though it could be trimmed slightly.
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?
With no output schema, the description does the work of conveying what is reported (paths, links, imports, agent config, notes) and the baseline/stats behavior. An agent has enough to call it correctly, though the return shape is only loosely sketched.
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 coverage is 100%, so both parameters are fully documented in the schema; the description's mention of auto-detecting CLAUDE.md/AGENTS.md/SKILL.md maps to targets but adds no syntax beyond it. Baseline 3 is appropriate when the schema carries parameter detail.
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 opens with a precise verb+resource: checking context files a coding agent reads against a git index, then enumerates the specific finding classes. This clearly distinguishes it from the sibling prumo_fix (which would repair, not 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?
Usage is implied by the check/read-only framing, and the targets param's auto-detect behavior hints at the default mode. However, it never states when to run this versus prumo_fix or the other siblings, nor any preconditions (e.g., must be a git repo).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports the folders of the code that no context file mentions: every top-level folder, or every package of a workspace, that no context file cites a path in and that holds no context file of its own, with the files git tracks in it, its commits in the last ninety days and its last commit, the most active first. It is what the agent is never told about, never a finding: a folder may be left out of the notes on purpose. 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?
Annotations already cover readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is settled. The description adds real context beyond that: the exact returned fields (git-tracked files, commits in the last ninety days, last commit), the ordering ('most active first'), and the important caveat that omission may be intentional. It does not discuss cost or scale, but it goes well past the 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 core purpose is front-loaded in the opening phrase, which is good, but the remainder is a single long run-on sentence with heavy nested clauses ('that no context file cites a path in and that holds no context file of its own') that slows parsing. It is information-dense rather than padded, but the structure could be split into shorter sentences without losing content.
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?
With no output schema, the description carries the burden of explaining returns and does so adequately: it enumerates the per-folder fields and the sort order, and it warns that absence is not necessarily a defect. What is missing is any indication of scope limits or expected result size, but an agent has enough to call it correctly and read the response.
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% for both parameters (repo and targets), so the schema already explains defaults and auto-detection. The description references the notion of context files that 'targets' checks but adds no syntax, format, or precedence detail beyond the schema, so the baseline 3 applies.
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?
States a specific verb and resource ('Reports the folders of the code that no context file mentions') and then enumerates exactly what is reported: top-level folders or workspace packages not cited by a context file, with git-tracked files, 90-day commits, and last commit, most active first. This is precise enough to distinguish it from prumo_check, prumo_drift, and prumo_budget without opening any schema.
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 clause 'It is what the agent is never told about, never a finding' gives interpretive context for when the output matters and steers the caller away from treating gaps as defects, and 'Nothing is written' reinforces the read-only nature. However, it never names an alternative sibling or states an explicit when-to-use condition, so usage is only implied.
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, a markdown link or an @ import 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?
Annotations already disclose readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the bar is lower, yet the description still adds real value by defining the bounded rewrite surface and the three classes of edits it refuses to make. It does not discuss auth, rate limits, or failure modes, keeping it out of 5 territory.
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, no filler, with the core action front-loaded and the safety scope trailing. The first sentence is clause-dense and slightly hard to parse, but every clause carries information.
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 mutating tool with no output schema, the description adequately covers what gets changed, what never gets changed, and that it 'reports what remains.' The only meaningful gap is the absent relationship to prumo_check and any dry-run expectation.
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 'repo' and 'targets' (including the CLAUDE.md/AGENTS.md/SKILL.md auto-detection behavior) are already fully documented in the schema. The description adds no parameter-level detail; baseline 3 applies.
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 opens with a concrete verb and resource ('Rewrites case mismatches in place') and enumerates the exact defect classes it repairs (case mismatches, missing paths, markdown links, @ imports). An agent can tell it is the mutating counterpart to prumo_check, though no sibling is named explicitly.
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?
It supplies clear when-not conditions: 'a link suggested from a name, a missing path with no history and a deleted file are never edited.' This scopes invocation precisely. It stops short of pointing at prumo_check as a dry-run/alternative, so it is context-rich but not a full when/when-not/alternatives triad.
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.9.7prumo_coveragev0.1.0prumo_budgetprumo_checkprumo_driftprumo_fixScored across 5 tools
Each tool targets a distinct function: prumo_check diagnoses, prumo_fix rewrites, prumo_budget measures cost, prumo_coverage surfaces unmentioned folders, and prumo_drift finds stale sections. The check/fix split (read-only findings vs. in-place repair) and the coverage/budget/drift separation are explicitly bounded in the descriptions, so an agent can select confidently.
All five tools follow the same prumo_<noun> snake_case pattern with no deviations or mixed conventions. The set is perfectly predictable.
Five tools is well-scoped for a focused context-file hygiene server; each covers a genuinely separate concern (find, fix, cost, coverage, drift) and none feels redundant or padded.
The surface covers the core lifecycle of auditing, repairing, and reporting on agent context files, plus cost/coverage/drift analytics. The only gap is that findings are held back via a .prumo-baseline.json with no tool to generate or update it, which an agent must handle manually.
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 /
