AGENTS.md generator
Describe your project and get an AGENTS.md that Codex, Cursor, GitHub Copilot, Claude Code and other coding agents read, with a CLAUDE.md that imports it if you want one. Every section comes from what you write, and nothing leaves your browser.
Start from an example
Nothing to write yet. Every section comes only from what you fill in, so an empty form gives no file. Fill in a field or start from an example.
What it does
It writes the instruction file a coding agent reads before it works in your repository: AGENTS.md, the open format most agents read, and, if you want, a CLAUDE.md that loads it for Claude Code. You give the facts the agent cannot guess from the code: the commands it should run, the folders, the rules, what it must not touch and how secrets are kept.
How it works
- Fill in only what is true for your project, or start from one of the examples and change it.
- The @anaroq/agents engine writes the file in your browser as you type. A field you leave empty writes no section: no headings without content and no generic advice.
- Values that look like secrets (keys, tokens, passwords in URLs) are masked before they are written.
- Copy or download AGENTS.md (and CLAUDE.md) into the root of your repository and commit it.
Which agents read which file
As each tool's own documentation states it, read on . Tools change these rules, so follow the source before you rely on one.
| Tool | Files | How it reads them | Source |
|---|---|---|---|
| AGENTS.md | AGENTS.md | An open format: a plain Markdown file in the repository root, and more in subfolders of a monorepo. The file closest to the edited file wins; your chat prompt overrides it. | Documentation |
| OpenAI Codex | AGENTS.md, AGENTS.override.md | Reads AGENTS.override.md or AGENTS.md in ~/.codex, then one file per folder from the project root down to the working folder, the closest last. Stops at 32 KiB in total by default (project_doc_max_bytes). | Documentation |
| Claude Code | CLAUDE.md, AGENTS.md | Reads CLAUDE.md. Reads AGENTS.md instead when the project has no CLAUDE.md (Claude Code v2.1.277 or later). With both, a CLAUDE.md with the line @AGENTS.md imports it. | Documentation |
| GitHub Copilot | .github/copilot-instructions.md, AGENTS.md, CLAUDE.md, GEMINI.md | Reads .github/copilot-instructions.md and AGENTS.md files anywhere in the repository, the nearest first; a single CLAUDE.md or GEMINI.md in the root works instead of AGENTS.md. | Documentation |
| Cursor | AGENTS.md, .cursor/rules/*.mdc | Reads AGENTS.md in the root and in subfolders, combined with the parent folders, as a plain alternative to .cursor/rules (.mdc files with metadata). | Documentation |
| Gemini CLI | GEMINI.md | Reads GEMINI.md by default. To read AGENTS.md, add it to context.fileName in settings.json. | Documentation |
What makes the file work
- Commands an agent can run as written: the exact install, build, test and lint lines, so it can check its own work.
- What it cannot see in the code: the paths not to touch and why, the branch and commit rules, where secrets live.
- Short, concrete rules: “run pnpm test before a commit”, not “test your changes”.
- Keeping it current: a stale command sends the agent down the wrong path, so change the file with the command.
What makes it worse: context load
- Length. The file is read in every session and takes room from your code: Claude Code asks for under 200 lines, Codex cuts at 32 KiB by default.
- Generic advice the agent follows anyway (“write clean code”), the README copied in, or a line for every folder.
- Rules that contradict each other, or a CLAUDE.md and an AGENTS.md that drift apart: the agent may follow either one.
- Secrets, tokens or internal addresses: the file is committed and read by every tool you connect.
Example
The Node.js monorepo example, written by the engine when this page was built. It also asks for a CLAUDE.md, whose only line is @AGENTS.md.
# acme-web
A pnpm monorepo: the Next.js site in apps/web and shared TypeScript packages.
## Stack
- Languages: TypeScript
- Frameworks: Next.js, React, Vitest, Playwright
- Package manager: `pnpm`. Install and add dependencies with it only.
## Commands
- Install dependencies: `pnpm install --frozen-lockfile`
- Run locally: `pnpm --filter web dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Type-check: `pnpm typecheck`
## Project structure
- `apps/web`: The Next.js site (App Router).
- `packages/ui`: Shared React components.
- `packages/config`: Shared ESLint and TypeScript settings.
## Code rules
- TypeScript strict mode; no `any` without a comment that says why.
- A package never imports from apps/.
- Add or update a test for every change in behavior.
## Do not change
Do not edit these paths unless the task explicitly asks you to:
- `pnpm-lock.yaml`: change it only through pnpm install.
- `packages/ui/src/tokens.css`: the approved design tokens.
## Git and pull requests
- Branch from main; never push to main directly.
- Conventional Commits: feat(web): …, fix(ui): ….
- Run pnpm lint, pnpm typecheck and pnpm test before you open a pull request.
## Secrets
- Never read, print or commit these files: `.env`, `.env.local`.
- New variables go into .env.example with an empty value.
@AGENTS.md
Limits
- It does not read your repository: every value is what you write. Run the commands in a terminal before you commit the file.
- An instruction file is context, not a permission system: an agent can still run any command its own settings allow. Limit what it may run in the agent's permission settings.
- It writes one AGENTS.md for the repository root. Nested files for subfolders, .cursor/rules and .github/copilot-instructions.md are not written.
- Secret masking finds common formats only. Read the file before you commit it.
- The table of formats is as of the date above; the tools change their rules.
Methodology: how the numbers are worked out
Sources
Related
Next step
A free public tool by ANAROQ, a company building compute infrastructure. What ANAROQ is building