instrlint

library0.2.4jsnpmunverified

v0.2.4 — Modern linter for agent instructions files (CLAUDE.md, AGENTS.md, .cursorrules). Detects dead rules, token waste, contradictions, duplicates, stale @-refs, and config-redundant rules (TypeScript strict, Prettier, ESLint, EditorConfig, C# project settings). Cl100k_base token budget tracking, interactive refactoring walkthrough for oversized files, host-orchestrated LLM verification (no API key). Supports Claude Code, Codex, Cursor. 487 tests. Self-linting since v0.2.3. Release cadence: multiple releases per month. Differentiator: CLI+skill two-pass verification workflow and bucket-split decision guidance vs plain token counters.

testing devops llm-agents

npm install instrlint

github ↗package ↗

INSTALL

IMPORT

SIG · INSTRLINT

instrlint

testingjavascriptv0.2.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

instrlint

✓ npx instrlint

✗ npm install -g instrlint && instrlint

CLI tool — no programmatic API; use npx for one-off runs or install globally.

instrlint ci

✓ instrlint ci

✗ instrlint --ci

CI exit-code mode is a subcommand, not a flag.

instrlint --fix

✓ instrlint --fix

✗ instrlint fix

Requires clean git working directory for safety.

instrlint --verify

✓ instrlint --verify

✗ instrlint verify

Triggers LLM verification within Claude Code / Codex. No external API key.

instrlint --lang zh-TW

✓ instrlint --lang zh-TW

✗ instrlint --lang zh-CN

Only Traditional Chinese (zh-TW) is supported for Chinese output.

Quick-start for running instrlint via npx: default scan, Chinese output, CI mode, auto-fix, and skill installation for Claude Code slash commands.

# Run in project root containing CLAUDE.md or AGENTS.md npx instrlint@latest # Full Chinese output npx instrlint --lang zh-TW # CI-compatible exit code npx instrlint ci # Auto-fix safe issues (clean git required) npx instrlint --fix # Install skill for Claude Code npx instrlint install --claude-code # Then in Claude Code: /instrlint /instrlint --verify

instrlint --version

Debug

Known issues

gotchaClaude Code custom commands only load at startup. /reload-plugins will NOT reload newly installed slash commands.

fix

Restart Claude Code after running `npx instrlint install --claude-code`.

affects: >=0.0.0

gotcha--fix requires a clean git working directory. Will abort if uncommitted changes exist.

fix

Commit or stash changes before running `instrlint --fix`.

affects: >=0.1.0

breakingv0.2.4 refactored internal types and unexported 31 symbols. Any direct require() of internal modules will break.

fix

Only use the CLI interface; do not depend on internal modules.

affects: >=0.2.4

gotcha--lang only supports zh-TW for Chinese. Other Chinese variants (e.g., zh-CN) may display mixed language.

fix

Use `--lang zh-TW` for Traditional Chinese output.

affects: >=0.2.2

deprecatedv0.2.3 introduced walkthrough mode for budget warnings. Raw suggestions are no longer printed by default when budget >200 lines.

fix

Use `--verify` to get LLM-validated findings or run `instrlint` without flags for default walkthrough.

affects: >=0.2.3

gotchaC# dead-rule detection checks .csproj, Directory.Build.props, and .editorconfig only. Does NOT check .ruleset or .globalconfig files.

fix

Manually review any custom .ruleset or .globalconfig rules not covered.

affects: >=0.2.2

Errors

Common errors & fixes

Error: No CLAUDE.md or AGENTS.md found

No agent instructions file exists in the current directory or configured tool path.

fix

Create a CLAUDE.md or AGENTS.md file, or run `npx instrlint` from the project root containing one.

instrlint: command not found

Global install missing or npx not available.

fix

Run `npx instrlint@latest` instead of `instrlint`.

Error: Dirty working tree. --fix requires a clean git index.

Uncommitted changes in the git working directory block --fix for safety.

fix

Commit or stash changes: `git stash push -m "pre-instrlint-fix"` then run `instrlint --fix`.

TypeError: instrlint is not a function

Trying to require() instrlint as a Node.js module instead of running as CLI.

fix

Use `npx instrlint` or `instrlint` from the command line; instrlint has no programmatic API.

Warning: Unknown tool type 'copilot'

Using --tool with an unsupported agent name.

fix

Use one of: claude-code, codex, cursor. Or omit --tool to auto-detect.

Upgrade

Version history

0.2.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jed1978/instrlint ↗

packagehttps://www.npmjs.com/package/instrlint ↗