agnix - Agent Config Linter

Real-time validation for AI agent configuration files in VS Code. Install from the VS Code Marketplace.

758 rules | Real-time diagnostics | Auto-fix | Completion | Multi-tool support

Features

• Real-time validation - Diagnostics as you type

• Context-aware completions - Frontmatter keys, values, and snippets

• JSON Schema validation and autocomplete for .agnix.toml config files

• Validates 758 rules - From official specs and best practices

• Diagnostics panel - Sidebar tree view of all issues by file

• CodeLens - Rule info shown inline above problematic lines

• Quick-fix preview - See diff before applying fixes

• Safe fixes - Apply only high-confidence fixes automatically

• Ignore rules - Disable rules directly from the editor

• Multi-tool - Claude Code, Codex CLI, OpenCode, Kiro, Pi, Antigravity CLI, Grok Code, GitHub Copilot, Cline, Cursor, Amp, Gemini CLI, Windsurf (Devin Desktop)

Supported File Types

The extension starts when the workspace contains one of these files and sends them to agnix-lsp in any language mode. User-level and system files (for example ~/.codex/hooks.json or /etc/gemini-cli/policies/*.toml) are validated when opened.

Commands

Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

| agnix: Show Rule Documentation | - | Open docs for a rule (via CodeLens) | | agnix: Ignore Rule in Project | - | Add rule to .agnix.toml disabled list | | agnix: Restart Language Server | - | Restart the LSP server | | agnix: Show Output Channel | - | View server logs |

Context Menu

Right-click on agent config files to:

• Validate Current File
• Fix All Issues
• Preview Fixes (with diff)
• Fix All Safe Issues

Requirements

The agnix-lsp binary is automatically downloaded on first use. No manual installation required.

If you prefer to install manually:

# From crates.io
cargo install agnix-lsp

# Or download agnix-lsp from the releases page
# https://github.com/agent-sh/agnix/releases

Homebrew, npm and pip install only the agnix CLI, not agnix-lsp.

Settings

All settings can be configured via VS Code's Settings UI or settings.json. Changes take effect immediately without restarting the LSP server.

General Settings

Rule Categories

Enable or disable validation rule categories. All default to true.

Version Pinning

Pin tool versions for version-aware validation. All default to null (use defaults).

Spec Revisions

Pin specification revisions. All default to null (use latest).

Example settings.json

{
  "agnix.severity": "Error",
  "agnix.tools": ["claude-code", "cursor"],
  "agnix.rules.promptEngineering": false,
  "agnix.rules.disabledRules": ["PE-004"],
  "agnix.versions.claudeCode": "1.0.0"
}

Configuration Priority

VS Code settings take priority over .agnix.toml:

1. VS Code settings (highest priority)
2. .agnix.toml in workspace root
3. Default values (lowest priority)

File-Based Configuration

Create .agnix.toml in your workspace for team-shared config:

target = "ClaudeCode"

[rules]
disabled_rules = ["PE-004"]

See configuration docs for all options.

Troubleshooting

agnix-lsp not found

The extension automatically downloads agnix-lsp on first use. If automatic download fails:

# Manual install from crates.io
cargo install agnix-lsp

# Or specify full path in settings
"agnix.lspPath": "/path/to/agnix-lsp"

The auto-downloaded binary is stored in the extension's global storage directory.

No diagnostics appearing

1. Check file type is supported (see table above)
2. Verify status bar shows "agnix" (not "agnix (error)")
3. Run agnix: Show Output Channel for error details

Links

• agnix on GitHub
• Validation Rules Reference
• Agent Skills Specification
• Model Context Protocol

License

MIT OR Apache-2.0