@codacy/tools-agentlinter-0

Table of Contents

• Overview
• Updating patterns
• Updating the Agentlinter version
• Development
• Notes for maintainers

Overview

Agentlinter is "ESLint for AI Agents" — a static analysis tool that scores, diagnoses, and auto-fixes AI agent configuration files (CLAUDE.md, AGENTS.md, SOUL.md, etc.). It checks for vague instructions, security issues, structural problems, inconsistencies, and more across 102+ rules.

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Updating the Agentlinter version

1. Update agentlinter version in devDependencies of package.json
2. Update preferredVersion in src/metadata.ts
3. Run pnpm install to fetch the new version
4. Run pnpm generate-payloads agentlinter-0 from the repo root to re-pin payload/package.json and regenerate its lockfile
5. Run pnpm prefetch to check for new/removed rules
6. Run pnpm test to verify compatibility
7. If the major version changes, create a new adapter package (agentlinter-1/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests
pnpm prefetch # Re-fetch patterns from Codacy API

To install agentlinter locally for manual testing:

npm install agentlinter

Notes for maintainers

• Workspace-level execution: Agentlinter operates on the entire workspace directory, not individual files. The adapter passes ctx.repositoryRoot to the tool and filters output by ctx.targetFiles post-hoc.
• Workspace diagnostics: Some diagnostics have file = "(workspace)" instead of a real file path. These are attached to the first agent file found in the target list (e.g. CLAUDE.md). If no agent file is in targets, they are skipped.
• Non-zero exit code: Agentlinter exits non-zero when diagnostics are found (similar to ESLint). The adapter captures stdout from the error and parses it normally — only a non-zero exit with empty stdout is treated as an error.
• No config files: Agentlinter has no native configuration files. All rule filtering is done post-hoc via enabled patterns in the Codacy config.
• Rule ID mapping: Rule IDs use / as separator (e.g. clarity/no-vague-instructions). The adapter converts / to _ and prefixes with the tool ID to build Codacy pattern IDs (e.g. Agentlinter_clarity_no-vague-instructions).