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

Add agent-specific rules when you want files that should not be part of the common build:

agentRules:
  claude:
    - agents/claude/*.md
  cursor:
    - agents/cursor/*.md

agentRules patterns are relative to source. Any file matched here is excluded from the common rule set and injected only into that agent's build.

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

1. Create a .rules/ directory in your project:

mkdir .rules

2. 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

3. Build rules for your agents:

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

4. Your agents will automatically use the generated files!

Example

Project Structure

my-project/
├── .rules/
│   ├── 01-coding-style.md
│   ├── 02-architecture.md
│   ├── 03-testing.md
│   └── agents/
│       ├── claude/
│       │   └── 99-claude.md
│       └── cursor/
│           └── 99-cursor.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

agentRules:
  claude:
    - agents/claude/*.md
  cursor:
    - agents/cursor/*.md

Agent-specific rules

Use a subdirectory under .rules/ for agent-only files. This keeps the scope visible in the filesystem and avoids mixing reserved files into the default rule set.

Example:

.rules/
  01-coding-style.md
  02-testing.md
  agents/
    claude/
      99-claude.md

source: .rules

agents:
  - claude

agentRules:
  claude:
    - agents/claude/*.md

With this layout:

• top-level files in .rules/ are common rules
• files matched by agentRules are excluded from the common build
• matched files are appended only to the targeted agent build

For agents that materialize one output file per rule, nested rule paths are encoded into the output filename to avoid collisions. For example, agents/codex/01-style.md becomes agents--codex--01-style.md (or .mdc / .instructions.md depending on the agent).

You can also predeclare future agent IDs such as codex; the files will stay out of the common build until that agent is added to the registry.

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