agnix

Lint agent configurations before they break your workflow

The linter for your AI coding stack -- skills, hooks, memory, plugins, MCP, and agent configs. CLI, LSP server, and IDE plugins for Claude Code, Cursor, GitHub Copilot, Codex CLI, and more.

145 validation rules | Auto-fix | VS Code + JetBrains + Neovim + Zed | GitHub Action

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 to apply fixes

Like what you see? Give it a star -- it helps other developers find agnix.

Why agnix?

The AI coding landscape is chaos. Every tool wants your config in a different format:

Tool	Config Files	Format
Claude Code	CLAUDE.md, .claude/settings.json	Markdown + JSON
Skills	.claude/skills/*/SKILL.md	Markdown with frontmatter
Hooks	.claude/settings.json hooks	JSON
Agents	.claude/agents/*.md	Markdown
Plugins	.claude/plugins/	JSON
Cursor	.cursor/rules/*.mdc, .cursorrules	MDC
GitHub Copilot	.github/copilot-instructions.md	Markdown
Codex CLI / AGENTS.md	AGENTS.md, AGENTS.local.md	Markdown
MCP	*.mcp.json	JSON Schema
Gemini CLI	GEMINI.md, GEMINI.local.md	Markdown

The problems are real:

• Skills don't auto-trigger - Vercel's research found skills invoke at 0% without explicit prompting. Wrong syntax means your skill never runs.
• Almost-right is worse than wrong - 66% of developers cite "AI solutions that are almost right" as their biggest frustration. Broken configs cause exactly this.
• Unbundled stack, fragmented configs - Developers mix Cursor + Claude Code + Copilot. A config that works in one tool silently fails in another.
• Inconsistent patterns become chaos amplifiers - When your config follows wrong patterns, AI assistants amplify the mistakes, not just ignore them.

agnix validates configs against 145 rules derived from official specs, research papers, and real-world testing. Catch issues before they reach your IDE.

Install

CLI

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

# Homebrew (macOS/Linux)
brew tap avifenesh/agnix && brew install agnix

# Cargo
cargo install agnix-cli

# Pre-built binaries: https://github.com/avifenesh/agnix/releases

Editor Extensions

Real-time diagnostics as you type, quick-fix code actions, hover documentation, context-aware completions.

Editor	Install	Details
VS Code	Install from VS Code Marketplace	Website guide
JetBrains	Install from JetBrains Marketplace	Website guide
Neovim	{ "avifenesh/agnix.nvim" }	Neovim docs
Zed	Search "agnix" in Extensions	Zed docs

GitHub Action

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

SARIF upload to GitHub Code Scanning

- name: Validate agent configs
  id: agnix
  uses: avifenesh/agnix@v0
  with:
    format: 'sarif'

- name: Upload SARIF results
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.agnix.outputs.sarif-file }}

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/avifenesh/agnix
    rev: v0.8.1
    hooks:
      - id: agnix

Claude Code Skill

Use /agnix directly in Claude Code via awesome-slash:

# Add the plugin
/plugin marketplace add avifenesh/awesome-slash
/plugin install agnix@awesome-slash

# Or via npm
npm install -g awesome-slash && awesome-slash

Then run /agnix to validate your project, /agnix --fix to auto-fix issues.

MCP Server

cargo install agnix-mcp

MCP server details

Tools available:

• validate_file - Validate a single config file
• validate_project - Validate all configs in a directory
• get_rules - List all 145 validation rules
• get_rule_docs - Get details about a specific rule

Claude Desktop configuration:

{
  "mcpServers": {
    "agnix": {
      "command": "agnix-mcp"
    }
  }
}

validate_file and validate_project support multi-tool filtering via tools:

• tools (preferred): comma-separated string ("claude-code,cursor") or string array (["claude-code","cursor"])
• target (legacy fallback): used only when tools is missing or empty
• tool names follow agnix canonical tool metadata (for example windsurf), with compatibility aliases accepted (copilot, claudecode)

Usage

# Validate current directory
agnix .

# Apply automatic fixes
agnix --fix .

# Apply only safe fixes (high-confidence, no semantic changes)
agnix --fix-safe .

# Strict mode (warnings = errors)
agnix --strict .

# Target specific tool
agnix --target claude-code .

# JSON or SARIF output
agnix --format json .
agnix --format sarif .

See Configuration Reference for all options including .agnix.toml config file.

Features

• Validation across 19 categories: Skills, Hooks, Agents, Plugins, MCP, Memory, Prompt Engineering, XML, References, Cross-platform, AGENTS.md, Copilot, Cursor, Cline, OpenCode, Gemini CLI, Codex CLI, Version Awareness
• Auto-fix: --fix applies all corrections, --fix-safe applies only safe ones, --dry-run previews them
• Completion: Context-aware completions for frontmatter keys, values, and snippets
• LSP server: Real-time diagnostics in any editor that supports LSP
• MCP server: Expose validation as AI-assistant tools
• Parallel validation: Uses rayon for fast multi-file processing
• Localization: English, Spanish, Chinese (Simplified) with --locale flag
• Cross-platform: Linux, macOS, Windows

Supported Tools

Tool	Rules	Config Files
Agent Skills	AS-, CC-SK-	SKILL.md
Claude Code	CC-*	CLAUDE.md, hooks, agents, plugins
GitHub Copilot	COP-*	.github/copilot-instructions.md, .github/instructions/*.instructions.md
Cursor	CUR-*	.cursor/rules/*.mdc, .cursorrules
MCP	MCP-*	*.mcp.json
AGENTS.md	AGM-, XP-	AGENTS.md, AGENTS.local.md, AGENTS.override.md
Gemini CLI	GM-*	GEMINI.md, GEMINI.local.md

Contributing

Contributions are welcome and appreciated. See CONTRIBUTING.md for the full development guide.

Found Something Off?

agnix validates against 145 rules, but the agent config ecosystem moves fast. If a rule is wrong, missing, or too noisy -- we want to know.

Report a bug | Request a rule

Your real-world configs are the best test suite we could ask for.

Contribute Code

Good first issues are labeled and ready: good first issues

Adding a new rule is one of the best ways to get started. Each rule is self-contained with clear inputs, outputs, and test patterns.

Other Ways to Participate

• Star this repository to follow updates
• Share your experience on social media
• Help with translations

Development

cargo build       # Build
cargo test        # Run tests
cargo run --bin agnix -- .  # Run CLI

Security

agnix implements ReDoS protection, file size limits, symlink rejection, path traversal detection, and fuzz testing. See SECURITY.md for reporting vulnerabilities and knowledge-base/SECURITY-MODEL.md for the detailed threat model.

Roadmap

See GitHub Issues for the full roadmap.

License

MIT OR Apache-2.0

Author

Avi Fenesh - @avifenesh