npx agentmd-cli init

🔥 Why this exists

Every AI coding agent now reads a rules file. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor reads .cursor/rules. Gemini CLI reads GEMINI.md. Copilot reads copilot-instructions.md.

The format is standardised. The content is not. So this happens on every team, in every repo:

Week 1   Someone writes CLAUDE.md in a hurry before a demo.
Week 3   It's 400 lines. Nobody has read it since week 1.
Week 8   The stack moved to Pydantic 2. The file didn't. The agent still writes .dict().
Week 12  The agent confidently violates a rule that was in the file the whole time.
Week 16  Someone starts a new repo and writes the same 400 lines again, slightly differently.

Three failures hide inside that story, and they are the three things nobody had a tool for:

And the fourth, the one every tech lead recognises: the rules that matter most are the unwritten ones, repeated in every code review. extract writes them down from your repo.

🚀 Quick start

Four commands. Each one is copy-paste and does exactly what it says.

1. Scan the stack, install matching standards, pin breaking library changes

npx agentmd-cli init

  ✓ Next.js                  package.json (next)
  ✓ PostgreSQL               package.json (pg)
  ⇅ Next.js 16               package.json (next ^16.1.0)   (version pin)
  ⇅ Pydantic 2               pyproject.toml (pydantic>=2.6) (version pin)

Recommended packages for claude:
  Security       authentication, owasp, sql-injection
  Database       postgres, indexes, migration
  ...
Install these? [Y/n]

2. Infer your team's unwritten conventions from git history and configs

npx agentmd-cli extract          # add --dry to print without writing

Gathered evidence from 14 files (96k chars, claude-opus-5)
  ✓ 9 conventions → .agentmd/presets/local-Team-conventions.md
  Run `agentmd link` to wire it in.

3. Lint a diff against your standards — deterministic, offline, zero tokens

npx agentmd-cli review --fast --fail-on=high

Reviewing 1 changed file against 12 standards (patterns only)

  HIGH   src/repo.ts:14  Security/sql-injection › sql-string-interpolation  [pattern]
         SQL built by string interpolation — use a parameterised query.

  1 finding at or above "high" — failing.

4. Measure whether the agent actually obeys the rules

npx agentmd-cli test              # needs ANTHROPIC_API_KEY

Rule efficacy — 3 standards × 3 tasks  (claude-opus-5)

  ✓ Security/jwt            3/3
  ✗ API/pagination          1/3   task 2: ignored "Use cursor pagination" — offset/limit used

Score: 7/9 (78%)

Then npx agentmd-cli link writes everything into CLAUDE.md, AGENTS.md, .cursor/rules, GEMINI.md or copilot-instructions.md, and you commit .agentmd/ so the whole team gets the same rules.

🏛 The four pillars

⇅ Breaking-change version pins

init reads the majors from package.json, pyproject.toml, requirements.txt and go.mod. link writes short, hand-written, version-specific rules into the agent file — only the breaking differences models routinely get wrong:

### Version pins (detected from this project)

**Pydantic 2** — _pyproject.toml (pydantic>=2.6)_
- Use `.model_dump()` / `.model_dump_json()` / `.model_validate()` — `.dict()`, `.json()`, `.parse_obj()` are deprecated v1 names.
- Validators are `@field_validator` and `@model_validator`; `@validator` and `@root_validator` are deprecated.

**Next.js 16** — _package.json (next ^16.1.0)_
- Request APIs are async only — `params`, `searchParams`, `cookies()`, `headers()` must be awaited.
- `middleware.ts` is `proxy.ts`; the old filename is not picked up.

Pins exist for Next.js 13–16, React 18–19, Pydantic 1–2, SQLAlchemy 2, Django 5, Prisma 5–7, Tailwind 3–4, Express 5, Zod 4, ESLint 9, Vue 3, Go 1.22–1.25 and Python 3.12–3.13. Bump a dependency, run link, and the agent file follows.

🎯 File-glob context scoping

link never pastes standards into your prompt — every target gets a short block of links, so 30 standards add a few hundred tokens, not thousands. For Cursor it goes further and writes one scoped .mdc rule per standard with file globs by category:

The Postgres standard costs nothing while you edit CSS.

🧬 Convention extraction

extract reads the folder structure, lint/format/type configs, package.json scripts, the last 50 commit subjects and a bounded sample of source and tests, then asks Claude for only the conventions with evidence in that sample — each rule cites the file or config it came from. The result is a normal standard (Team/conventions) in your manifest: link includes it, update leaves it alone, remove removes it.

🛡 Zero-cost enforcement + agent test suites

Every review starts with a deterministic pattern fast-path — interpolated SQL, SELECT *, eval/exec, shell commands built from variables, MD5/SHA-1 for secrets, Math.random() tokens, jwt.decode without verify, wildcard CORS, hard-coded secrets, Pydantic v1 calls, sync cookies() in Next.js 15+ — scoped to the standards you installed. --fast stops there: no key, no network, milliseconds. The full review sends the diff and standards to Claude (prompt-cached) or, with --local, to Ollama on your machine. test generates adversarial tasks per standard, runs them with the standard in context, and judges every attempt — so you know which rules the model actually follows.

⚙️ How it works

flowchart LR
    R["<b>This repo</b><br/>_canonical/ → 11 family dirs"] -->|HTTPS, no account| C["<b>agentmd-cli</b><br/>init · install · link"]
    C --> M[".agentmd/manifest.json<br/>.agentmd/presets/*.md"]
    M --> L["CLAUDE.md · AGENTS.md<br/>.cursor/rules · GEMINI.md<br/>copilot-instructions.md"]
    L --> A["Your agent"]
    P["Version pins<br/>package.json · pyproject · go.mod"] --> L
    X["agentmd extract<br/>your repo's conventions"] --> M
    A -->|diff| V["agentmd review<br/>patterns → model"]
    A -->|tasks| T["agentmd test<br/>obedience score"]

1. Content is written once in _canonical/<Category>/<name>.md and generated per model family — XML-tagged sections for Claude, compact imperative bullets for OpenAI, and so on.
2. The CLI fetches the family you use straight from this repository over HTTPS, records it in .agentmd/manifest.json with a checksum, and keeps the markdown in .agentmd/presets/.
3. link writes a managed block into whichever agent files your tools already read, plus the version pins, plus scoped rules for Cursor. Everything outside the block is yours.
4. update respects your edits — a package you tuned is skipped unless you pass --force; outdated tells you what drifted.
5. review and test close the loop: the diff is checked against the rules; the rules are checked against the model.

🤖 Supported agents

Teach the agent itself. Two Agent Skills ship with the toolchain — agentmd-usage (the registry playbooks) and agentmd-standards (the discipline of following what's installed):

npx skills@latest add Aaditya1273/Agent.md -a claude-code -a cursor -y

Connect the MCP. The registry is also an MCP server, so an agent can search and read standards mid-task:

claude mcp add --transport http agentmd https://agent.md/api/mcp     # Claude Code
codex  mcp add agentmd --url https://agent.md/api/mcp                # Codex
gemini mcp add --transport http agentmd https://agent.md/api/mcp     # Gemini CLI

Cursor and VS Code add it in one click from agent.md. Claude Code users can also /plugin marketplace add Aaditya1273/Agent.md for /agentmd:setup and /agentmd:review.

📦 What's in this repo

This repository is the registry — the markdown the CLI installs. Nothing else lives here, so it stays easy to read, diff and review.

_canonical/<Category>/<preset>.md     the source of truth: one file per standard
claude/<Category>/<preset>/…          that standard, in Claude's native shape
open-ai/<Category>/<preset>/…         …and in OpenAI's, and nine more families

The count that matters is 302; the 3,322 files are the same standards in each family's native shape. The CLI (agentmd-cli on npm), the VS Code extension, the MCP server and the website are the tooling around this content — docs for all of them at agent.md.

📚 The registry

Browse everything with logos and search at agent.md, or from the terminal:

npx agentmd-cli search "rate limiting"
npx agentmd-cli list claude/Security
npx agentmd-cli info Security/jwt
npx agentmd-cli install Security/jwt          # one package
npx agentmd-cli install Database/             # a whole category

Every install fetches the file straight from this repository over HTTPS. No mirror, no account, no telemetry.

🛡 Enforce it in CI

Drop this into .github/workflows/agentmd-review.yml in your own repo. Zero token cost, no API key, nothing leaves the runner:

name: agentmd review
on: [pull_request]
permissions:
  contents: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx agentmd-cli review --base origin/${{ github.base_ref }} --fast --fail-on=high

Want a full model review that comments on the PR? Add ANTHROPIC_API_KEY to your secrets, give the job pull-requests: write, and swap --fast for --github. Need diffs to stay on your own machines? agentmd review --local judges with Ollama instead.

🆚 Compared with the alternatives

🤝 Contributing

Standards are plain markdown, written once in _canonical/<Category>/<name>.md:

---
name: jwt
category: Security
description: Issuing and validating JSON Web Tokens safely — algorithm pinning, claim validation, key rotation.
license: MIT
author: Agent.md maintainers
last-verified: 2026-09-13
reviewed-by: unreviewed
version: 2.0.0
---

# Purpose
…
# Anti-patterns
…
# Checklist

The bar: imperative, specific, opinionated, short right/wrong code blocks, an anti-patterns table and a checklist, ~200 lines. Match a neighbour in the same category. Open a PR with the canonical file; maintainers generate the eleven family variants.

Most wanted right now: Rust, Vue, Svelte, NestJS and Java. The CLI already detects those stacks and deliberately recommends nothing, because there is no content for them yet. See CONTRIBUTING.md.

🗺 Roadmap

❓ FAQ

Is this a replacement for CLAUDE.md / AGENTS.md / Cursor rules?
No. Those are file formats. Agent.md is the distribution layer that fills them in and keeps them current — link writes into whichever ones your tools already read.

Does it paste 30 standards into my prompt?
No. link writes a short block of links; the agent opens a standard when it needs it. For Cursor it also writes one scoped rule per standard with file globs, attached only while a matching file is open.

What does review --fast actually check?
Deterministic patterns over the added lines of a diff, scoped to the standards you installed. High precision on purpose — a false positive in CI costs more trust than a missed catch. The model-backed review catches the rest.

Why one file per family instead of one file?
Models differ in what they follow. Claude responds to XML-tagged sections; OpenAI models to compact imperative bullets. Writing once and generating per family keeps content identical while the shape fits the reader.

Does anything leave my machine?
init, install, link, review --fast and review --local never contact Anthropic. review, extract and test send the diff / evidence and the installed standards to the Anthropic API under your own key — nothing else. The website and the CLI collect no telemetry.

Is anything paid?
No. All 302 standards, the CLI, the extension and the MCP server are MIT licensed.

License

MIT. Use it anywhere, including commercial projects, no attribution required.