Ruler – apply the same rules to all coding agents (Cursor, Claude, Codex, etc.)

1 week ago 3

A CLI tool to manage custom rules and configs across different AI coding agents.

Centralise AI agent instructions in a single .ruler/ directory
Distribute rules to supported agents (GitHub Copilot, Claude Code, OpenAI Codex CLI, Cursor, Windsurf, Cline, Aider)
Extensible architecture: add new agent adapters easily

Install globally:

npm install -g @intellectronica/ruler

Or use npx:

npx @intellectronica/ruler apply

Create a .ruler/ directory at your project root and add Markdown files defining your rules:

.ruler/ ├── coding_guidelines.md └── style_guide.md

Run the apply command:

ruler apply [--project-root <path>] [--agents <agent1,agent2,...>] [--config <path>]

Run the init command to scaffold a basic .ruler/ setup:

ruler init [--project-root <path>]

Use --agents to specify a comma-separated list of agent names (case-insensitive substrings) to limit which agents the rules are applied to.

The command will read all .md files under .ruler/, concatenate their contents, and generate/update configuration files for the following agents:

Agent File(s) Created/Updated

GitHub Copilot	.github/copilot-instructions.md
Claude Code	CLAUDE.md
OpenAI Codex CLI	AGENTS.md
Cursor	.cursor/rules/ruler_cursor_instructions.md
Windsurf	.windsurf/rules/ruler_windsurf_instructions.md
Cline	.clinerules
Aider	ruler_aider_instructions.md and updates .aider.conf.yml

Ruler uses a TOML configuration file located at .ruler/ruler.toml by default. You can override its location with the --config <path> option in the apply command.

# Run only these agents by default (omit to use all agents) # default_agents = ["GitHub Copilot", "Claude Code", "Aider"] [agents.Copilot] enabled = true output_path = ".github/copilot-instructions.md" [agents.Claude] enabled = true # output_path = "CLAUDE.md" [agents.Aider] enabled = false # output_path_instructions = "ruler_aider_instructions.md" # output_path_config = ".aider.conf.yml"

default_agents: array of agent names (case-insensitive substrings) to run by default.
[agents.<AgentName>]: per-agent settings:
- enabled (boolean): enable or disable this agent.
- output_path (string): custom path for agents that produce a single file.
- output_path_instructions/output_path_config: custom paths for Aider's instruction and config files.

CLI --agents option (substring filters)
Config file default_agents and [agents] overrides
Built-in defaults (all agents enabled, standard output paths)

Ruler can propagate a project-level .ruler/mcp.json file to native MCP configurations of supported agents, merging (or overwriting) each agent’s existing MCP server settings.

Place your MCP servers config in a file at .ruler/mcp.json:

{ "mcpServers": { "example": { "url": "https://mcp.example.com" } } }

Flag Effect

--with-mcp	Enable writing MCP configs for all agents (default)
--no-mcp	Disable writing MCP configs
--mcp-overwrite	Overwrite native MCP configs instead of merging

Configuration (ruler.toml)

Configure default behavior in your ruler.toml:

[mcp] enabled = true merge_strategy = "merge" # or "overwrite" [agents.Cursor.mcp] enabled = false merge_strategy = "overwrite"

Clone the repository and install dependencies:

git clone https://github.com/intellectronica/ruler.git cd ruler npm install npm run build

Run linting and formatting checks:

npm run lint npm run format

Run tests:

End-to-end tests (run build before tests):

npm run build && npm test

[ ] Support for MCP servers config
[ ] Support for transforming and rewriting the rules using AI
[ ] Support "harmonisation" (reading existing rules of specific agents and combining them with the master config)
[ ] Support for additional agents
[ ] Support for agent-specific features (for example: apply rules in copilot)

Contributions are welcome! Please open issues or pull requests on GitHub.

MIT

ai.intellectronica.net

Read Entire Article