Agentlint#
"ESLint for your coding agents." Agentlint automatically scans, validates, and maintains agent context files — AGENTS.md, CLAUDE.md, skills, rules, workflows, and plans — keeping them structured, current, and aligned with the codebase .
The core problem it solves: agent context files are written once and silently go stale as modules, scripts, and workflows evolve . Agentlint provides a repeatable maintenance workflow through a CLI and a read-only MCP server. It also detects the active IDE and automatically routes maintenance rules to the optimal location for that client.
Core guarantees :
- Local-first — no hosted LLM, no database, no auth layer.
- Read-only MCP server — Agentlint returns guidance; the client agent makes repository changes.
- Lightweight — separate CLI and MCP packages with minimal dependencies and strict TypeScript throughout.
Packages on npm: @agent-lint/cli | @agent-lint/mcp
Package Structure#
Agentlint is a pnpm monorepo with four publishable packages :
| Package | Role |
|---|---|
@agent-lint/shared | Shared types, Zod schemas, artifact parsing helpers |
@agent-lint/core | Workspace discovery, scoring, plan building, guidelines |
@agent-lint/mcp | MCP server (stdio + HTTP transports), tools, resources |
@agent-lint/cli | CLI commands (init, scan, prompt, score) |
Entry points: packages/mcp/src/index.ts for the MCP package; packages/core/src/workspace-discovery.ts and packages/core/src/plan-builder.ts for core scan logic.
CLI Commands#
Quickstart (no global install required):
npx @agent-lint/cli
| Command | Purpose |
|---|---|
agent-lint init | Set up MCP config and optionally install maintenance rules |
agent-lint scan | Scan the workspace; report missing types, incomplete files, stale, conflicting, and weak findings |
agent-lint prompt | Print a ready-to-paste IDE prompt; auto-selects broad-scan or targeted-maintenance mode based on workspace state |
agent-lint score <file> | Score a context artifact against 12 quality dimensions; auto-detects artifact type from filename or accepts --type |
MCP Server & Tools#
The MCP package (packages/mcp/src/index.ts) exposes a read-only server over stdio or HTTP. All five tools are registered in packages/mcp/src/tools/index.ts; workspace scanning is gated behind an enableWorkspaceScan option .
Tools#
| Tool | Purpose |
|---|---|
agentlint_get_guidelines | Return artifact-specific guidance (do/don't, guardrails, template, quality checklist) before creating or editing context files |
agentlint_plan_workspace_autofix | Scan a workspace and return a step-by-step markdown fix plan |
agentlint_quick_check | Detect whether recent code changes require context-file updates |
agentlint_emit_maintenance_snippet | Return a reusable maintenance snippet for the detected IDE client |
agentlint_score_artifact | Score a context artifact against 12 quality dimensions; designed for autoresearch loops |
Resources#
| Resource URI | Purpose |
|---|---|
agentlint://guidelines/{type} | Readable guidelines for one artifact type |
agentlint://template/{type} | Skeleton template for a new artifact |
agentlint://path-hints/{type} | File discovery hints per IDE client |
Workspace Discovery & Scan#
discoverWorkspaceArtifacts() in packages/core/src/workspace-discovery.ts is the engine behind agent-lint scan and agentlint_plan_workspace_autofix.
Scan constraints : max depth 6, max 200 files, max 500 KB per file. Standard noise directories (node_modules, .git, dist, build, etc.) are skipped .
Artifact types detected: agents, skills, rules, workflows, plans. Each discovered artifact is analyzed for :
- Missing sections — required headings absent from the file
- Stale references — markdown links or code spans pointing to files that no longer exist
- Placeholder sections — sections containing only TODO/TBD/
<placeholder>text - Cross-tool leaks — e.g., Claude-specific patterns (
CLAUDE.md,mcpServers) found inside a Cursor or Copilot rules file - Weak signals — sections that exist but lack runnable commands or meaningful content
The plan builder (packages/core/src/plan-builder.ts) converts discovery results into a prioritized markdown action plan with remediation steps. It also sets a recommendedPromptMode: "broad-scan" when missing or incomplete artifacts exist, "targeted-maintenance" otherwise .
IDE Detection & Environment-Aware Routing#
detectInstalledClients() in packages/cli/src/commands/clients.ts detects which IDEs are active by checking PATH binaries, VS Code extension directories, and workspace-level config directories. It supports 13 clients: Claude Code, Codex, Cursor, OpenCode, Windsurf, Claude Desktop, VS Code, Kilo Code, Cline, Roo Code, Kiro, Zed, and Antigravity .
Based on the detected client, agent-lint init routes maintenance rules to the optimal location :
| Target | Client |
|---|---|
AGENTS.md (repo root) | Universal default |
CLAUDE.md (repo root) | Claude-family clients |
.cursor/rules/*.md / .windsurf/rules/*.md | Cursor / Windsurf managed rules |
.github/copilot-instructions.md | VS Code / GitHub Copilot |
Client-specific guidance is also injected into buildGuidelines() output so the agent receives IDE-aware instructions when calling agentlint_get_guidelines.
Guidelines & Artifact Scoring#
buildGuidelines() in packages/core/src/guidelines-builder.ts assembles the full guidance document returned by agentlint_get_guidelines. It composes: artifact spec, do/don't lists, guardrails, a 12-dimension quality checklist, a template skeleton, and client-specific notes. Workflow discipline guidance (plan-first, subagent strategy, verification gates) is appended for agents, workflows, and plans types .
12 quality dimensions scored by agentlint_score_artifact (0–100 total):
| Dimension | What it checks |
|---|---|
clarity | Headings, bullets, absence of vague phrases |
specificity | Code blocks, file paths, CLI commands, numeric constraints |
scope-control | Explicit in-scope / out-of-scope boundaries |
completeness | Presence of artifact-type-specific required sections |
actionability | Numbered steps, imperative verbs |
verifiability | Verification section with code blocks and evidence expectations |
safety | Safety/guardrails section, prohibition language (NEVER/DO NOT) |
injection-resistance | Guards against prompt injection, trust boundary statements |
secret-hygiene | No exposed secrets, tokens, or hardcoded env vars |
token-efficiency | Body under 5000 chars, no duplicate headings, short paragraphs |
platform-fit | Client-specific format (YAML frontmatter for skills, cross-tool leak detection) |
maintainability | No placeholders/TODOs, no stale years, minimal inline path references |
The score is designed to drive an autoresearch loop: score → improve → compare → keep or revert .
Quick Check#
agentlint_quick_check (core: packages/core/src/quick-check.ts) detects whether recent code changes require context-file updates — without a full workspace scan.
It matches against two signal types:
- Path-based: changed files matching patterns for
package.json, lockfiles,tsconfig.json, CI workflows (.github/workflows/*.yml), security-sensitive paths (auth/,.env), skills directories, and root context files (AGENTS.md,CLAUDE.md). - Description-based: keywords in commit/change descriptions such as "new module", "refactor", "security", "deploy", "dependency upgrade", and IDE client names (cursor, windsurf, copilot, claude, etc.).
For each matched signal, the tool returns a trigger (human-readable signal name), affected artifacts (which context files likely need updating), and a recommended action — often suggesting agentlint_plan_workspace_autofix for comprehensive follow-up.
