{"id":25760,"library":"instrlint","title":"instrlint","description":"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.","status":"active","version":"0.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/jed1978/instrlint","tags":["javascript","claude","codex","cursor","lint","agent","instructions","cli","llm"],"install":[{"cmd":"npm install instrlint","lang":"bash","label":"npm"},{"cmd":"yarn add instrlint","lang":"bash","label":"yarn"},{"cmd":"pnpm add instrlint","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CLI tool — no programmatic API; use npx for one-off runs or install globally.","wrong":"npm install -g instrlint && instrlint","symbol":"instrlint","correct":"npx instrlint"},{"note":"CI exit-code mode is a subcommand, not a flag.","wrong":"instrlint --ci","symbol":"instrlint ci","correct":"instrlint ci"},{"note":"Requires clean git working directory for safety.","wrong":"instrlint fix","symbol":"instrlint --fix","correct":"instrlint --fix"},{"note":"Triggers LLM verification within Claude Code / Codex. No external API key.","wrong":"instrlint verify","symbol":"instrlint --verify","correct":"instrlint --verify"},{"note":"Only Traditional Chinese (zh-TW) is supported for Chinese output.","wrong":"instrlint --lang zh-CN","symbol":"instrlint --lang zh-TW","correct":"instrlint --lang zh-TW"}],"quickstart":{"code":"# Run in project root containing CLAUDE.md or AGENTS.md\nnpx instrlint@latest\n\n# Full Chinese output\nnpx instrlint --lang zh-TW\n\n# CI-compatible exit code\nnpx instrlint ci\n\n# Auto-fix safe issues (clean git required)\nnpx instrlint --fix\n\n# Install skill for Claude Code\nnpx instrlint install --claude-code\n\n# Then in Claude Code:\n/instrlint\n/instrlint --verify","lang":"javascript","description":"Quick-start for running instrlint via npx: default scan, Chinese output, CI mode, auto-fix, and skill installation for Claude Code slash commands."},"warnings":[{"fix":"Restart Claude Code after running `npx instrlint install --claude-code`.","message":"Claude Code custom commands only load at startup. /reload-plugins will NOT reload newly installed slash commands.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Commit or stash changes before running `instrlint --fix`.","message":"--fix requires a clean git working directory. Will abort if uncommitted changes exist.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Only use the CLI interface; do not depend on internal modules.","message":"v0.2.4 refactored internal types and unexported 31 symbols. Any direct require() of internal modules will break.","severity":"breaking","affected_versions":">=0.2.4"},{"fix":"Use `--lang zh-TW` for Traditional Chinese output.","message":"--lang only supports zh-TW for Chinese. Other Chinese variants (e.g., zh-CN) may display mixed language.","severity":"gotcha","affected_versions":">=0.2.2"},{"fix":"Use `--verify` to get LLM-validated findings or run `instrlint` without flags for default walkthrough.","message":"v0.2.3 introduced walkthrough mode for budget warnings. Raw suggestions are no longer printed by default when budget >200 lines.","severity":"deprecated","affected_versions":">=0.2.3"},{"fix":"Manually review any custom .ruleset or .globalconfig rules not covered.","message":"C# dead-rule detection checks .csproj, Directory.Build.props, and .editorconfig only. Does NOT check .ruleset or .globalconfig files.","severity":"gotcha","affected_versions":">=0.2.2"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Create a CLAUDE.md or AGENTS.md file, or run `npx instrlint` from the project root containing one.","cause":"No agent instructions file exists in the current directory or configured tool path.","error":"Error: No CLAUDE.md or AGENTS.md found"},{"fix":"Run `npx instrlint@latest` instead of `instrlint`.","cause":"Global install missing or npx not available.","error":"instrlint: command not found"},{"fix":"Commit or stash changes: `git stash push -m \"pre-instrlint-fix\"` then run `instrlint --fix`.","cause":"Uncommitted changes in the git working directory block --fix for safety.","error":"Error: Dirty working tree. --fix requires a clean git index."},{"fix":"Use `npx instrlint` or `instrlint` from the command line; instrlint has no programmatic API.","cause":"Trying to require() instrlint as a Node.js module instead of running as CLI.","error":"TypeError: instrlint is not a function"},{"fix":"Use one of: claude-code, codex, cursor. Or omit --tool to auto-detect.","cause":"Using --tool with an unsupported agent name.","error":"Warning: Unknown tool type 'copilot'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}