aicm

🗂️ aicm

AI Configuration Manager

A CLI tool for managing Agentic configurations across projects

Why

Modern AI-powered IDEs like Cursor and Agents like Codex enable developers to write custom instructions to maintain context across coding sessions. They also support MCPs for enhanced functionality. However, sharing these configurations across multiple projects is a challenge.

aicm solves this by enabling you to create reusable presets that bundle rules and MCP configurations together. With multi-target support, you can write your rules once and deploy them consistently across different AI tools and IDEs.

How it works

aicm accepts Cursor's .mdc format as it provides the most comprehensive feature set. For other AI tools and IDEs, aicm automatically generates compatible formats:

• Cursor: Native .mdc files with full feature support
• Windsurf: Generates .windsurfrules file
• Codex: Generates AGENTS.md file
• Claude: Generates CLAUDE.md file

This approach ensures you write your rules once in the richest format available, while maintaining compatibility across different AI development environments.

Getting Started

The easiest way to get started with aicm is by using presets - npm packages containing rules and MCP configurations that you can install in any project.

Using a preset

• Install a preset npm package:

npm install --save-dev @team/ai-preset

• Create an aicm.json file in your project root:

{ "presets": ["@team/ai-preset"] }

• Add a prepare script to your package.json to install all preset rules and MCPs:

{
  "scripts": {
    "prepare": "npx aicm  -y install"
  }
}

The rules are now installed in .cursor/rules/aicm/ and any MCP servers are configured in .cursor/mcp.json.

Creating a Preset

• Create an npm package with the following structure:

@team/ai-preset
├── package.json
├── aicm.json
└── rules/
    ├── typescript.mdc
    └── react.mdc

• Configure the preset's aicm.json:

{
  "rulesDir": "rules",
  "mcpServers": {
    "my-mcp": { "url": "https://example.com/sse" }
  }
}

• Publish the package and use it in your project's aicm.json:

{ "presets": ["@team/ai-preset"] }

Note: This is syntactic sugar for @team/ai-preset/aicm.json.

Using Local Rules

For project-specific rules, you can specify rulesDir in your aicm.json config. This approach allows you to write rules once and automatically generate them for all configured targets.

{
  "rulesDir": "path/to/rules/dir"
}

Notes

• Generated rules are always placed in a subdirectory for deterministic cleanup and easy gitignore.
• Users may add .cursor/rules/aicm/ and .aicm/ (for Windsurf/Codex) to .gitignore if they do not want to track generated rules.

Overrides

You can disable or replace specific rules provided by presets using the overrides field:

{
  "presets": ["@company/ai-rules"],
  "overrides": {
    "rule-from-preset-a": "./rules/override-rule.mdc",
    "rule-from-preset-b": false
  }
}

Demo

We'll install an npm package containing a simple preset to demonstrate how aicm works.

• Install the demo preset package:

npm install --save-dev pirate-coding

• Create an aicm.json file in your project:

echo '{ "presets": ["pirate-coding"] }' > aicm.json

• Install all rules & MCPs from your configuration:

npx aicm install

This command installs all configured rules and MCPs to their IDE-specific locations.

After installation, open Cursor and ask it to do something. Your AI assistant will respond with pirate-themed coding advice. You can also ask it about the aicm library which uses https://gitmcp.io/ to give you advice based on the latest documentation.

Security Note

To prevent prompt-injection, use only packages from trusted sources.

Workspaces Support

aicm supports workspaces by automatically discovering and installing configurations across multiple packages in your repository.

You can enable workspaces mode by setting the workspaces property to true in your root aicm.json:

{
  "workspaces": true
}

aicm automatically detects workspaces if your package.json contains a workspaces configuration:

How It Works

• Discover packages: Automatically find all directories containing aicm.json files in your repository
• Install per package: Install rules and MCPs for each package individually in their respective directories
• Merge MCP servers: Write a merged .cursor/mcp.json at the repository root containing all MCP servers from every package

How It Works

Each directory containing an aicm.json file is treated as a separate package with its own configuration.

For example, in a workspace structure like:

├── aicm.json (with "workspaces": true)
├── packages/
│   ├── frontend/
│   │   └── aicm.json
│   └── backend/
│       └── aicm.json
└── services/
    └── api/
        └── aicm.json

Running npx aicm install will install rules for each package in their respective directories:

• packages/frontend/.cursor/rules/aicm/
• packages/backend/.cursor/rules/aicm/
• services/api/.cursor/rules/aicm/

Preset Packages in Workspaces

When you have a preset package within your workspace (a package that provides rules to be consumed by others), you can prevent aicm from installing rules into it by setting skipInstall: true:

{
  "skipInstall": true,
  "rulesDir": "./rules",
  "targets": ["cursor"]
}

This is useful when your workspace contains both consumer packages (that need rules installed) and provider packages (that only export rules).

Configuration

Create an aicm.json file in your project root, or an aicm key in your project's package.json.

{
  "rulesDir": "./rules",
  "targets": ["cursor"],
  "presets": [],
  "overrides": {},
  "mcpServers": {},
  "skipInstall": false
}

• rulesDir: Directory containing all rule files.
• targets: IDEs/Agent targets where rules should be installed. Defaults to ["cursor"].
• presets: List of preset packages or paths to include.
• overrides: Map of rule names to false (disable) or a replacement file path.
• mcpServers: MCP server configurations.
• workspaces: Set to true to enable workspace mode. If not specified, aicm will automatically detect workspaces from your package.json.
• skipInstall: Set to true to skip rule installation for this package. Useful for preset packages that provide rules but shouldn't have rules installed into them.

MCP Server Installation

• Cursor: MCP server configs are written to .cursor/mcp.json.

Supported Targets

• Cursor: Rules are installed as individual .mdc files in the Cursor rules directory (.cursor/rules/aicm/), mcp servers are installed to .cursor/mcp.json
• Windsurf: Rules are installed in the .aicm directory which should be added to your .gitignore file. Our approach for Windsurf is to create links from the .windsurfrules file to the respective rules in the .aicm directory. There is no support for local mcp servers at the moment.
• Codex: Rules are installed in the .aicm directory and referenced from AGENTS.md.

Commands

Global Options

These options are available for all commands:

• --help, -h: Show help information
• --version, -v: Show version information

init

Initializes a new configuration file in your current directory.

npx aicm init

Edit this file to add your rules, presets, or other settings.

install

Installs all rules and MCPs configured in your aicm.json.

npx aicm install

Options:

• --ci: run in CI environments (default: false)
• --verbose: show detailed output and stack traces for debugging
• --dry-run: simulate installation without writing files, useful for validating presets in CI

Node.js API

In addition to the CLI, aicm can be used programmatically in Node.js applications:

const { install, Config } = require("aicm");

install().then((result) => {
  if (result.success) {
    console.log(`Successfully installed ${result.installedRuleCount} rules`);
  } else {
    console.error(`Error: ${result.error}`);
  }
});

// Install with custom options
const customConfig = {
  targets: ["cursor"],
  rulesDir: "rules",
  presets: ["@team/ai-preset"],
};

install({
  config: customConfig,
  cwd: "/path/to/project",
}).then((result) => {
  // Handle result
});

API Reference

install(options?: InstallOptions): Promise<InstallResult>

Installs rules and MCP servers based on configuration.

Options:

• cwd: Base directory to use instead of process.cwd()
• config: Custom config object to use instead of loading from file
• installOnCI: Run installation on CI environments (default: false)
• verbose: Show verbose output and stack traces for debugging (default: false)
• dryRun: Simulate installation without writing files, useful for preset validation in CI (default: false)

Returns:

A Promise that resolves to an object with:

• success: Whether the operation was successful
• error: Error object if the operation failed
• installedRuleCount: Number of rules installed

Contributing

Contributions are welcome! Please feel free to open an issue or submit a Pull Request.

Development

Testing

pnpm test

Publishing

npm run release