instrlint

0.2.4 verified Fri May 01 auth: no javascript

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.

Common errors

error Error: No CLAUDE.md or AGENTS.md found ↓

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

error instrlint: command not found ↓

cause Global install missing or npx not available.

fix

Run npx instrlint@latest instead of instrlint.

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

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

error TypeError: instrlint is not a function ↓

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

error Warning: Unknown tool type 'copilot' ↓

cause Using --tool with an unsupported agent name.

fix

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

Warnings

gotcha Claude 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`.

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

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

breaking v0.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.

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.

deprecated v0.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.

gotcha C# 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.

Install

npm install instrlint

yarn add instrlint

pnpm add instrlint

Imports

instrlint
wrong
```
npm install -g instrlint && instrlint
```
correct
```
npx instrlint
```
CLI tool — no programmatic API; use npx for one-off runs or install globally.
instrlint ci
wrong
```
instrlint --ci
```
correct
```
instrlint ci
```
CI exit-code mode is a subcommand, not a flag.
instrlint --fix
wrong
```
instrlint fix
```
correct
```
instrlint --fix
```
Requires clean git working directory for safety.
instrlint --verify
wrong
```
instrlint verify
```
correct
```
instrlint --verify
```
Triggers LLM verification within Claude Code / Codex. No external API key.
instrlint --lang zh-TW
wrong
```
instrlint --lang zh-CN
```
correct
```
instrlint --lang zh-TW
```
Only Traditional Chinese (zh-TW) is supported for Chinese output.

Quickstart

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