Coding agents can load several layers of repository instructions before they touch the code. The same rule may live in AGENTS.md, CLAUDE.md, Copilot instructions, and editor-specific files. Those files quietly grow, drift, and spend context on repeated text.

Instruction Lint makes that cost visible before it becomes permanent. It also checks documented npm scripts against the repository, so an agent does not waste a run discovering that npm run verify never existed.

Try it

Run directly from npm:

npx --yes instruction-lint .

Scan with a hard total budget and fail on warnings:

npx --yes instruction-lint . \
  --max-tokens 8000 \
  --strict

Machine-readable output is available for agents and scripts:

npx --yes instruction-lint . --json

What it checks

| Rule | Finding | |---|---| | budget/total | All discovered instructions exceed the repository budget | | budget/file | One instruction file is unusually large | | content/duplicate | The same substantial rule block appears in multiple files | | reference/missing | A relative Markdown link points to a file that does not exist | | command/missing-script | An instructed npm run script is absent from the relevant package.json | | discovery/empty | No supported instruction files were found |

Commands such as cd packages/web && npm run build are checked against the package in that directory. Commands outside the scanned repository are ignored.

Token estimates use a transparent heuristic: about four ASCII characters per token and one token per non-ASCII character. The number is a budget signal, not a tokenizer claim.

Supported files

• AGENTS.md at the root or in nested packages
• CLAUDE.md and .claude/rules/*.md
• GEMINI.md
• .github/copilot-instructions.md
• .github/instructions/*.instructions.md
• .cursor/rules/*.md and .cursor/rules/*.mdc
• .cursorrules and .windsurfrules

Generated folders such as .git, node_modules, dist, build, target, and vendor are ignored.

GitHub Action

Add the audit to pull requests so instruction growth is reviewed like code:

name: Instruction budget

on: [push, pull_request]

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: howong217-ui/[email protected]
        with:
          max-tokens: 8000
          strict: true

The Action writes the same findings to the GitHub job summary. It does not post comments or request additional permissions.

Human and agent interfaces

The terminal report is designed for a quick review: total budget, file costs, and exact findings. --json returns a schema-versioned report with stable rule IDs, file paths, severities, and exit status so a coding agent can inspect the same evidence without parsing prose.

Instruction Lint does not call a language model, upload repository content, or rewrite rules automatically. The first release stays deliberately boring in the best way: the same files produce the same findings.

CLI

instruction-lint [path] [options]

--max-tokens <number>       Total estimated token budget (default: 12000)
--max-file-tokens <number>  Per-file estimated token budget (default: 4000)
--json                      Print machine-readable JSON
--strict                    Fail on warnings as well as errors
--version                   Print the installed version
-h, --help                  Show help

Development

npm install
npm run check
npm run demo

The analyzer uses only the Node.js standard library. Contributions should keep checks deterministic and include a focused test fixture.

Roadmap

• [x] Multi-agent instruction discovery
• [x] Context budgets and duplicate-block detection
• [x] Broken relative-link checks
• [x] JSON output and GitHub job summaries
• [ ] Budget comparison against the base branch
• [ ] SARIF output for GitHub code scanning
• [ ] Safe suggestions for consolidating duplicated rules

License

MIT