agents-md-linter

Make your repo understandable to AI coding agents.

A fast, local CLI tool that scans your software repository and generates or audits an AGENTS.md file so AI coding agents know exactly how to work in your codebase.

The Problem

You invite an AI coding agent (like Claude Code, Cursor, OpenHands, or Devin) into your repository. It tries to help, but it runs npm test instead of pytest, it modifies compiled files in dist/, and it hallucinates environment variables because it doesn't know your project's rules.

The Solution

AGENTS.md is a repository-level instruction file for AI coding agents. Just as README.md is for humans, AGENTS.md tells AI agents:

• How to install dependencies and run tests.
• Which files to avoid (like generated code).
• Where secrets live and how to handle them safely.
• Your project's specific coding conventions.

agents-md-linter automates this. It scans your repo, detects your stack, and generates a comprehensive AGENTS.md draft. It also audits existing files to ensure they meet best practices.

Installation

You can run the tool directly using npx without installing it globally:

npx agents-md-linter init

Or install it as a dev dependency:

npm install -D agents-md-linter

Quickstart

1. Generate a draft:

   npx agents-md-linter init

   Scans your repo, detects your framework, test commands, and package manager, then creates AGENTS.md.

2. Fill in the blanks: Open AGENTS.md and replace the TODO placeholders with your project-specific context.

3. Audit for completeness:

   npx agents-md-linter audit

   Checks that your AGENTS.md includes required sections like test commands and security warnings.

CLI Commands

init

Scans the repo and generates a draft AGENTS.md.

npx agents-md-linter init

audit

Checks whether an existing AGENTS.md has required sections.

npx agents-md-linter audit --strict

fix

Updates missing sections or suggests patches to an existing AGENTS.md.

npx agents-md-linter fix

print

Prints detected repo metadata (language, framework, commands, etc.) without writing any files.

npx agents-md-linter print

Before and After

Before AGENTS.md:

Agent: "I've updated the code. Running npm test... Error: command not found."

After AGENTS.md:

Agent: "I read AGENTS.md. I see this is a Python project using Poetry. I ran poetry run pytest and all tests passed. I also made sure not to touch the __pycache__ directory as instructed."

Generated AGENTS.md Sample

Here is a snippet of what the generator produces:

## Setup Instructions
**Prerequisites:** Node.js ≥ 18.

1. Clone the repository.
2. Install dependencies:
   \`\`\`bash
   pnpm install
   \`\`\`

## Testing Instructions
Test framework: **jest**

Run all tests:
\`\`\`bash
pnpm test
\`\`\`
> Always run tests before opening a pull request.

See full examples in the examples/ directory.

Architecture

graph TD
    A[CLI Entry] --> B[Scanner]
    B --> C[Detectors]
    C -->|Stack, Framework, Commands| B
    B --> D{Command}
    D -->|init| E[Generator]
    D -->|audit| F[Auditor]
    D -->|fix| G[Merger]
    E --> H[AGENTS.md]
    F --> I[Audit Report]
    G --> H

Loading

Supported Stacks

The scanner automatically detects and configures instructions for:

• Languages: TypeScript, JavaScript, Python
• Frameworks: Next.js, React, FastAPI, Django, Express, Vue, Svelte, Flask
• Package Managers: npm, pnpm, yarn, poetry, pip, pipenv
• Tooling: Jest, Vitest, Pytest, ESLint, Prettier, Ruff, Black
• Workspaces: Monorepos (Turborepo, npm workspaces, etc.)
• CI/CD: GitHub Actions

Roadmap

1. VS Code Extension: Inline linting for AGENTS.md directly in your editor.
2. GitHub Action: Automatically audit AGENTS.md on PRs to ensure instructions stay up-to-date.
3. Go & Rust Support: Add stack detection for Go modules and Cargo.
4. Ruby & Java Support: Add stack detection for Rails, Spring, and Gradle.
5. Custom Rules: Allow teams to define custom audit rules in .agentslinterrc.
6. Watch Mode: Run agents-md-linter audit --watch during development.
7. JSON/SARIF Output: Export audit results for integration with security dashboards.
8. LLM Context Optimizer: A command to minify AGENTS.md for agents with small context windows.
9. Docker Detection: Automatically document docker-compose commands.
10. Database Detection: Auto-detect Prisma, Alembic, or Drizzle migration commands.

Contributing

We welcome contributions! See our Contributing Guide for details on how to add new detectors, rules, or features.

Summary:

1. Fork the repo.
2. Create a feature branch.
3. Add tests for your changes.
4. Open a PR against main.

Security

agents-md-linter is fully local and deterministic. It never reads the contents of your secret files (like .env) — it only detects their presence to warn AI agents. It makes no network calls and requires no LLM API keys. See SECURITY.md.

License

MIT License. See LICENSE for details.