**One source of truth for all your AI coding agents.**
npm install @agents-mdx/cliOne 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.
- 🧩 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
``bash`
npm install agents-mdx
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:
`mdCode Style
- Use TypeScript strict mode
- Prefer const over let
- Use early returns to reduce nesting
`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 conventionsCLAUDE.md
- Create / AGENTS.md filesAGENTS.mdx
- Add , CLAUDE.md and AGENTS.md to your .gitignore
`bash`
npx agents-mdx start
This watches your AGENTS.mdx and all imported conventions, regenerating the output files on every save.
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
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'],
});
`
Running start compiles this into CLAUDE.md and AGENTS.md — symlinked files that your AI agents read automatically.
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}'
},
}
};
- Always ensure new tables have a created_at, updated_at and deleted_at columns
- 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 →
- VSCode →
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 reviewsenv.hasExecutable('tool')
- — check if a CLI tool is installedenv.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';
}
})()}
Use ck to find related code even without exact keywords:
\\\bash
ck --sem "retry logic"
\\\
``
MIT
Copyright (c) 2026–present [StackBlitz][stackblitz]
[stackblitz]: https://stackblitz.com/