Prumo

[prumo, a context linter for coding agents. Is your documentation still true?]

Checks the context files your coding agent reads against the code beside them.

[npm version] [CI] [MIT license]

[Leia em português]

[prumo in a terminal: one command, then a case mismatch, two broken links and a missing path, each with its correction]

The problem

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.

Quick start

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/prumo

prumo 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 machinenpm install --save-dev @tomd4vs/prumo     # or as a dev dependency of one project

Either 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.

Reading the result

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 + 1

Every 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).

What it will not do

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.

Using it from an agent

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-mcp

The 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.

Continuous integration

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.ymlname: docson: [push, pull_request]jobs:  prumo:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: TomD4vs/prumo@v1

It 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.

Three reports

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 writtenprumo budget    # what each context file costs the agent, and what is written twiceprumo coverage  # which folders of the code no context file mentions, most active first

drift 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.

Documentation

License

MIT