AGENTS.mdx

One source of truth for all your AI coding agents.

Stop copy-pasting guidelines between CLAUDE.md, AGENTS.md, and other agent config files. Write your conventions once in composable MDX components, and let agents-mdx generate the right files for Claude Code, Cursor, Copilot, Codex, and more.

Why agents-mdx?

- 🧩 Composable — Break down conventions into reusable MDX components
- 🔄 Multi-agent — Generate config files for multiple AI agents from a single source
- 🔌 MCP support — Define MCP servers once, generate configs for all agents
- 👥 Team-friendly — Self-serve onboarding lets developers pick the conventions they need
- ⚡ Live reload — Watch mode rebuilds on every change

Install

``bash
npm install agents-mdx
`

Quick Start

$3

Organize your team's guidelines as MDX files in a conventions/ directory:

`
your-project/
├── conventions/
│ ├── code-style.mdx
│ ├── testing.mdx
│ ├── git-workflow.mdx
│ ├── security.mdx
│ └── react-patterns.mdx
├── AGENTS.mdx # ← generated by setup, configurable by each dev on your team
├── CLAUDE.md # ← symlink, auto-generated
└── AGENTS.md # ← symlink, auto-generated
`

Each convention file is a standard MDX file:

`md


Code Style

- Use TypeScript strict mode
- Prefer const over let
- Use early returns to reduce nesting
`

$3

`bash
npx agents-mdx setup
`

This interactive wizard will:

- Ask which AI agents you use (Claude Code, Cursor, Copilot, etc.)
- Let you pick which conventions to include
- Generate an AGENTS.mdx file that imports your conventions
- Create CLAUDE.md / AGENTS.md files
- Add AGENTS.mdx, CLAUDE.md and AGENTS.md to your .gitignore

$3

`bash
npx agents-mdx start
`

This watches your AGENTS.mdx and all imported conventions, regenerating the output files on every save.

CI

For CI environments like claude-code-action, use the non-interactive flags to generate files automatically:

`bash
npx agents-mdx setup --force --agents claude-code --all-conventions
`

All options:

`bash
npx agents-mdx setup [path]
--force # Overwrite existing files without prompting
--agents # Pre-select agents: claude-code, cursor, copilot, codex, open-code
--conventions # Custom conventions directory (default: "conventions")
--all-conventions # Include all conventions without prompting
`

How It Works

The AGENTS.mdx file is git-ignored, so each developer can customize which conventions they want active. Your team commits the shared conventions/ folder, but individuals choose what to include.

Your AGENTS.mdx file imports conventions as components:

`mdx
import { defineConfig } from '@agents-mdx/runtime';
import CodeStyle from './conventions/code-style.mdx';
import Testing from './conventions/testing.mdx';

export const config = defineConfig({
agents: ['claude-code', 'codex', 'copilot'],
});

Project Guidelines



`

Running start compiles this into CLAUDE.md and AGENTS.md — symlinked files that your AI agents read automatically.

MCP Servers

Define MCP servers in your convention files and let agents-mdx generate the right config format for each agent.

Environment variables are automatically transformed to each agent's format (${env:VAR} for Cursor, ${VAR} for Claude Code).

In your convention file (conventions/mcp-tools.mdx):

`mdx
export const mcpServers = {
'supabase-local': {
url: 'http://localhost:54321/mcp'
},
'supabase-staging': {
url: 'https://mcp.supabase.com/mcp?project_ref=${env:SUPABASE_PROJECT_REF}',
headers: {
Authorization: 'Bearer ${env:SUPABASE_ACCESS_TOKEN}'
},
}
};

Database tables

- Always ensure new tables have a created_at, updated_at and deleted_at columns

Database operations

- Always soft deleted entries
`

During setup, you'll be prompted to select which MCP servers to enable. The start command then generates the appropriate config files:

- Cursor → .cursor/mcp.json
- Claude Code → .mcp.json
- VSCode → .vscode/mcp.json

Conditional Instructions

Include or exclude content based on the environment. Import env from the runtime:

`mdx
import { env } from '@agents-mdx/runtime';
`

What's available:

- env.CI — detect GitHub Actions, useful for claude-code-action reviews
- env.hasExecutable('tool') — check if a CLI tool is installed
- env.isClaudeMd / env.isAgentsMd — check which output file is being generated

Example: tool-specific instructions

Only include instructions for ck when it's installed:

`mdx
import { env } from '@agents-mdx/runtime';

{(() => {
if (!env.hasExecutable('ck')) {
throw 'ignore-file';
}
})()}

Semantic Search

Use ck to find related code even without exact keywords:

\\\bash
ck --sem "retry logic"
\\\

``

License

MIT

Copyright (c) 2026–present [StackBlitz][stackblitz]

[stackblitz]: https://stackblitz.com/