agnix — Config Linter for AI Coding Assistants
Catch broken agent configs before your AI tools silently ignore them: 455 rules validating CLAUDE.md, SKILL.md, hooks, and MCP, with autofixes built in.
Evidence shows a local static validator: no command execution, symlink rejection, file size/count/regex input limits, atomic writes, opt-in telemetry with compile-time feature gating and environment-aware disable. Fix paths distinguish --fix-safe from --fix-unsafe with --dry-run preview, so confirmation is adequate. Deductions: no explicit rollback/undo of applied fixes beyond atomic write guarantees; a promotional block for a tiyuvta inference service embedded in the README, and rule-source claims rely on an --explain command not shown in these files.
Workspace versions are consistent (0.52.2 across Cargo.toml, the pyproject shim, and a sync script), and the CLI provides graded diagnostics, help hints, and rule explanations. Deductions: a maintained-fork dependency (serde_norway, though justified), unverified availability of pinned versions like tokio 1.52.3, and self-admitted weaker Windows validation.
Clear audience across multi-tool users (Claude Code, Cursor, Copilot, Kiro, MCP) with CI and editor integrations; boundaries documented via target/tools filters and known limitations. Deductions: --target is self-described as legacy and only partially effective, so filter precision leans on the tools list with some ambiguity.
Clean architecture (crate layout, docs site, rules table), thorough multi-channel install notes, stable naming, candid known-limitations list (TOCTOU, platform differences), CI-enforced CHANGELOG, version-sync script. Deductions: license metadata says Apache-2.0 while README/Cargo say MIT OR Apache-2.0, an inconsistency; no FAQ; maintainer identity unverified and 48-hour security response is only an assertion.
High output usability (GitHub annotations, --strict, LSP, editors); addresses real pain (non-triggering skills, cross-tool drift) with clear marginal value and minimal local cost. No clear deduction, but actual rule effectiveness is unverified without execution — reflected in confidence, not extra credit.
Rule counts, source claims, and the --explain mechanism provide some traceability; CI/cargo-audit/CodeQL/fuzz are partially corroborated by workflow files. Deductions: the 455-rule figure and external citations (Vercel, Stack Overflow) cannot be verified statically, and fact versus marketing framing requires reader discernment given the README's promotional tone.
- License metadata (Apache-2.0) is inconsistent with the repository claim (MIT OR Apache-2.0); rely on the LICENSE files before compliance decisions.
- --fix-unsafe applies low-confidence fixes; preview with --dry-run --show-fixes first — there is no automatic rollback, so rely on version control.
- Publisher identity is unverified; the security contact is a personal Gmail address.
- Windows symlink behavior is self-admittedly under-validated; a TOCTOU window is acknowledged.
- The 455-rule count and external research citations are not independently verified; this is a static review with no execution.
What does this agent do, and when should you use it?
agnix is a static validation tool for AI coding assistant configurations, positioned as "the missing linter and LSP" for agent tooling. It ships 455 rules covering Agent Skills, Claude Code, GitHub Copilot, Cursor, Kiro, MCP, AGENTS.md, Cline, and Gemini CLI configuration files. Written in Rust, the project is organized as workspace crates: agnix-core (validation engine), agnix-cli (command line), agnix-lsp (language server), agnix-mcp (MCP server), and agnix-wasm (browser/runtime bindings). Diagnostics come with fix suggestions and support tiered auto-fix modes via --fix, --fix-safe, and --fix-unsafe, plus --dry-run diff previews. Editor integrations span VS Code, JetBrains, Neovim, and Zed, and an official GitHub Action validates configs in CI.
agnix scans agent configuration files in a repository (CLAUDE.md, AGENTS.md, SKILL.md, .cursor/rules/*.mdc, *.mcp., files under .kiro/, and others) and checks them against rule metadata generated from knowledge-base/rules.. It emits row/column diagnostics — e.g., "Invalid name 'Review-Code'" with a suggested lowercase-hyphen fix — and flags which issues are automatically fixable. CLI commands include agnix . (validate current directory), the --fix family for applying repairs, --strict (treat warnings as errors), --format github (GitHub Actions annotations), and agnix explain MCP-018 to explain a rule and its evidence. It also provides an LSP binary for live editor diagnostics, an MCP server binary for agent ecosystems, and WASM bindings powering the in-browser playground.
- A Claude Code developer: a single malformed field makes a skill invisible; validate SKILL.md frontmatter before every commit.
- Teams running Cursor, Claude Code, and Copilot together: each tool wants different formats; enforce validation in CI so a config valid in one tool doesn't silently break another.
- Engineers maintaining MCP setups: use agnix explain MCP-018 to review rule evidence and debug *.mcp. errors.
- Developers writing agent configs in VS Code or JetBrains: get real-time diagnostics and autofixes through the LSP-based extensions.
- Platform engineering teams: gate agent config quality in pipelines via the official agent-sh/agnix GitHub Action.
What are this agent's strengths and limitations?
- Broad coverage: 455 rules across 9 tool families (Claude Code 53, Kiro 53, Agent Skills 31, etc.) — the only tool in this source validating CLAUDE.md, SKILL.md, hooks, MCP, and Kiro together.
- Traceable rules: sourced from official specs, academic research, and real-world breakage patterns; agnix explain exposes each rule's evidence.
- Tiered auto-fix (--fix / --fix-safe / --fix-unsafe) plus --dry-run previews let CI and local workflows adopt different safety levels.
- Multi-form delivery: CLI, LSP, MCP server, WASM bindings, and VS Code/JetBrains/Neovim/Zed extensions, plus an official GitHub Action.
- A Rust core distributed via npm, Homebrew, pip, and Cargo means teams must choose an install path, and the crates.io name (agnix-cli) differs from the npm name — a potential source of confusion.
- Rule counts for some tools are thin — Copilot (6) and Cline (4) — limiting value for teams primarily on those tools.
- --fix-unsafe applies medium and LOW confidence fixes; undisciplined use can introduce unwanted changes, so teams need a fix policy.
- No benchmarks or false-positive rates are published in the source, leaving the actual quality impact of the rules unquantified.
How do you install or deploy this agent?
Pick one:
- npm (recommended, all platforms): npm install -g agnix
- Homebrew: brew tap agent-sh/agnix && brew install agnix
- pip: pip install agnix (or uvx agnix . to run without installing)
- Cargo: cargo install agnix-cliPre-built binaries are available on GitHub Releases.
Editor extensions: VS Code and JetBrains from their Marketplaces (VS Code item avifenesh.agnix), Neovim via the agent-sh/agnix plugin repo, Zed by searching "agnix" in Extensions.
How do you use this agent?
First run:
bash
agnix . # validate current directory
agnix --fix . # apply safe fixes
agnix --dry-run --show-fixes . # preview fixes with inline diffs
agnix --strict . # strict mode (warnings = errors)
agnix --format github . # GitHub Actions annotations
agnix explain MCP-018 # explain a rule and its evidence
agnix --target claude-code . # filter rules for a specific toolCI integration:
yaml
- name: Validate agent configs
uses: agent-sh/agnix@v0with:
target: 'claude-code'