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

npm install agents-mdx

Quick Start

1. Create your conventions

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:

# Code Style

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

2. Run setup

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. Watch for changes

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:

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

All options:

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:

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

<CodeStyle config={config} />
<Testing config={config} />

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):

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:

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:

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