agnix

<div align="center"> <img src="editors/vscode/icon.png" alt="agnix" width="128"> <h1>agnix</h1> <p><strong>Lint agent configurations before they break your workflow</strong></p> <p> <a href="https://www.npmjs.com/package/agnix"><img src="https://img.shields.io/npm/v/agnix.svg?color=3C873A" alt="npm"></a> <a href="https://crates.io/crates/agnix-cli"><img src="https://img.shields.io/crates/v/agnix-cli.svg?color=E57324" alt="Crates.io"></a> <a href="https://github.com/agent-sh/agnix/releases"><img src="https://img.shields.io/github/v/release/agent-sh/agnix?color=0A7E8C" alt="Release"></a> <a href="https://github.com/agent-sh/agnix/actions/workflows/ci.yml"><img src="https://github.com/agent-sh/agnix/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT%2FApache--2.0-64748B.svg" alt="License"></a> <a href="https://github.com/hesreallyhim/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code"></a> </p> </div> <p align="center">Catch broken agent configs before your AI tools silently ignore them.<br>447 rules across Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and more -<br>validating CLAUDE.md, SKILL.md, hooks, MCP configs, and other agent files.</p> <p align="center"><strong>Auto-fix</strong> | <strong><a href="https://github.com/marketplace/actions/agnix-ci">GitHub Action</a></strong> | <strong><a href="https://marketplace.visualstudio.com/items?itemName=avifenesh.agnix">VS Code</a> + <a href="https://plugins.jetbrains.com/plugin/30087-agnix">JetBrains</a> + <a href="https://github.com/agent-sh/agnix.nvim">Neovim</a> + <a href="https://zed.dev/extensions?query=agnix">Zed</a></strong></p> <p align="center"> <a href="https://agent-sh.github.io/agnix/"><img src="https://img.shields.io/badge/Docs-Website-2563EB?style=for-the-badge" alt="Website"></a> <a href="https://agent-sh.github.io/agnix/playground"><img src="https://img.shields.io/badge/Try_it-Playground-E91E63?style=for-the-badge" alt="Playground"></a> <a href="https://dev.to/avifenesh/your-ai-agent-configs-are-probably-broken-and-you-dont-know-it-16n1"><img src="https://img.shields.io/badge/Blog-Post-0A0A0A?style=for-the-badge&logo=dev.to" alt="Blog Post"></a> </p> <p align="center"><em>New rules and tool support ship constantly. Follow for real-time updates:</em></p> <p align="center"> <a href="https://x.com/avi_fenesh"><img src="https://img.shields.io/badge/Follow-@avi__fenesh-1DA1F2?style=for-the-badge&logo=x&logoColor=white" alt="Follow on X"></a> </p>

Why agnix?

Your skills don't trigger. Vercel's research found skills invoke at 0% without correct syntax. One wrong field and your skill is invisible.

"Almost right" is the worst outcome. 66% of developers cite it as their biggest AI frustration. Misconfigured agents produce exactly this.

Multi-tool stacks fail silently. Cursor + Claude Code + Copilot each want different formats. A config that works in one tool breaks in another.

Bad patterns get amplified. AI assistants don't ignore wrong configs - they learn from them.

agnix validates all of it - 447 rules sourced from official specs, academic research, and real-world breakage patterns. Auto-fix included.

Want to try it first? Open the playground - paste any agent config, see diagnostics instantly. No install, runs in your browser.

Quick Start

$ npx agnix .
Validating: .

CLAUDE.md:15:1 warning: Generic instruction 'Be helpful and accurate' [fixable]
  help: Remove generic instructions. Claude already knows this.

.claude/skills/review/SKILL.md:3:1 error: Invalid name 'Review-Code' [fixable]
  help: Use lowercase letters and hyphens only (e.g., 'code-review')

Found 1 error, 1 warning
  2 issues are automatically fixable

hint: Run with --fix, --fix-safe, or --fix-unsafe to apply fixes

https://github.com/user-attachments/assets/72d5fe7c-476f-46ea-be64-5785cf6d5600

Install

# npm (recommended, all platforms)
npm install -g agnix

# Homebrew (macOS/Linux)
brew tap agent-sh/agnix && brew install agnix

# Cargo
cargo install agnix-cli

Pre-built binaries | All install options

Editor Extensions

| Editor | Install | |--------|---------| | VS Code | VS Code Marketplace | | JetBrains | JetBrains Marketplace | | Neovim | { "agent-sh/agnix", config = function() require("agnix").setup() end } | | Zed | Search "agnix" in Extensions |

Editor setup guide

GitHub Action

- name: Validate agent configs
  uses: agent-sh/agnix@v0
  with:
    target: 'claude-code'

Usage

agnix .              # Validate current directory
agnix --fix .        # Apply only safe fixes
agnix --fix-safe .   # Explicit safe-only fix mode
agnix --fix-unsafe . # Apply all fixes, including medium and LOW confidence
agnix --dry-run --show-fixes .  # Preview fixes with inline diff output
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 .  # Legacy target preset (primarily affects CC-* rules)
agnix --target kiro .         # Legacy target preset (use tools = [...] for tool-only filtering)

Full CLI reference | Full rules reference

Supported Tools

| Tool | Rules | Count | Config Files | |------|-------|-------|--------------| | Agent Skills | AS-*, CC-SK-* | 31 | SKILL.md | | Claude Code | CC-* | 53 | CLAUDE.md, hooks, agents, plugins | | GitHub Copilot | COP-* | 6 | .github/copilot-instructions.md, .github/instructions/*.instructions.md | | Cursor | CUR-* | 16 | .cursor/rules/*.mdc, .cursorrules, .cursor/hooks.json, .cursor/agents/**/*.md, .cursor/environment.json | | Kiro | KIRO-*, KR-SK-*, KR-AG-*, KR-HK-*, KR-PW-*, KR-MCP-* | 53 | .kiro/steering/**/*.md, .kiro/skills/**/SKILL.md, .kiro/agents/**/*.{json,md}, .kiro/hooks/*.kiro.hook, .kiro/settings/mcp.json, .kiro/powers/*/POWER.md | | MCP | MCP-* | 12 | *.mcp.json | | AGENTS.md | AGM-*, XP-* | 13 | AGENTS.md, AGENTS.local.md, AGENTS.override.md | | Cline | CLN-* | 4 | .clinerules, .clinerules/*.md, .clinerules/*.txt | | Gemini CLI | GM-* | 9 | GEMINI.md, GEMINI.local.md, .gemini/settings.json (hooks), gemini-extension.json (extensions), .geminiignore |

Architecture

Rust workspace crates:

• agnix-rules - rule metadata generated from knowledge-base/rules.json
• agnix-core - shared validation engine library
• agnix-cli - command-line interface binary
• agnix-lsp - language server binary
• agnix-mcp - MCP server binary
• agnix-wasm - WebAssembly bindings for browser/runtime integrations

Contributing

Contributions welcome. See CONTRIBUTING.md for the development guide.

Report a bug | Request a rule | Good first issues

License

MIT OR Apache-2.0

---

<p align="center"> <a href="https://github.com/agent-sh/agnix/stargazers">Star this repo</a> to help other developers find agnix. </p>