aimapper

Universal build tool for managing coding agent rules across multiple AI-powered development tools. Support Claude Code, Cursor, Windsurf, GitHub Copilot, Amazon Q, and more.

Installation

npm install -g aimapper

Or use directly with npx:

npx aimapper build  # Uses aimapper package, runs 'aimap build'
# or after global install:
aimap build

Usage

Build rules for default agent (Claude)

aimap build  # Generates CLAUDE.md only

Build for specific agents

aimap build --agents claude,cursor

Clean generated files

aimap clean           # Clean all generated files
aimap clean --all     # Also remove build hash

Configuration

Create .aimap.yml in your project root:

# Source directory for rule files
source: .rules

# Agents to build for
agents:
  - claude
  - cursor
  - copilot
  - amazonq

# Custom output paths (optional)
outputs:
  claude: CUSTOM_CLAUDE.md

Options

Build command

-s, --source <dir> - Source directory for rules [default: .rules]
-a, --agents <list> - Comma-separated list of agents [default: all]
-v, --verbose - Verbose output
--dry - Dry run (show what would be built)
-c, --config <file> - Path to config file [default: .aimap.yml]

Clean command

--all - Remove all generated files including build hash
-v, --verbose - Verbose output
-c, --config <file> - Path to config file [default: .aimap.yml]

Supported Coding Agents (2025)

Agent	ID	Output Files	Notes
Universal Agents	`agents`	`AGENTS.md`	Combined rules for any agent
Claude Code	`claude`	`CLAUDE.md`	Writes a bullet list of `@` references; supports `CLAUDE.tempalte.md` with `@@RULES@@` placeholder
Cursor IDE	`cursor`	`.cursor/rules/*.mdc`	MDC format (v0.52+)
GitHub Copilot	`copilot`	`.github/instructions/*.instructions.md`	Granular instructions
Amazon Q	`amazonq`	`.amazonq/rules/*.md`	32KB file limit
Aider	`aider`	`.aider.conf.yml`	Updates read array
Cline	`cline`	`.clinerules/*.md`	Individual files
RooCode	`roocode`	`.roo/rules/*.md`	Individual files
Windsurf	`windsurf`	`.windsurfrules`	6KB hard limit
JetBrains AI	`jetbrains`	`.aiassistant/rules/*.md`	Individual files
Gemini CLI	`gemini`	`GEMINI.md`	Combined rules

Quick Start

Create a .rules/ directory in your project:

mkdir .rules

Add your coding rules as markdown files:

echo "# Code Style\n\nUse TypeScript" > .rules/01-style.md
echo "# Testing\n\nWrite unit tests" > .rules/02-testing.md

Build rules for your agents:

npx aimapper build --agents claude,cursor,windsurf
# or with global install:
aimap build --agents claude,cursor,windsurf

Your agents will automatically use the generated files!

Example

Project Structure

my-project/
├── .rules/
│   ├── 01-coding-style.md
│   ├── 02-architecture.md
│   └── 03-testing.md
├── .aimap.yml              # Optional config
└── ... (generated files after build)

Generated `CLAUDE.md`

When building for Claude, the file contains a list of rule references:

- @.rules/01-coding-style.md
- @.rules/02-architecture.md
- @.rules/03-testing.md

If a CLAUDE.tempalte.md file exists in the project root, @@RULES@@ will be replaced with this list in the template content.

Sample Config (.aimap.yml)

# Source directory for rule files
source: .rules

# Agents to build for
agents:
  - claude
  - cursor
  - copilot
  - windsurf

Sample Rule File (.rules/01-coding-style.md)

# Coding Style Guidelines

- Use TypeScript for all new code
- Follow ESLint configuration  
- Write comprehensive tests
- Use meaningful variable names

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development with watch mode
npm run test:watch

License

MIT

nacyot/aimap