Ruler
Ruler — apply the same rules to all coding agents
Last verified:
What is Ruler?
Ruler is a CLI tool that centralizes instructions for AI coding assistants in one place. Instead of maintaining separate configuration files for tools like GitHub Copilot, Claude, Cursor, Aider, and others, it stores all rules in a single .ruler/ directory using Markdown files and distributes them automatically to each agent's specific configuration location. This reduces duplication, avoids inconsistent outputs, and keeps guidance aligned as projects evolve.
Key features include centralized rule management with Markdown files in .ruler/, automatic distribution to 17+ supported AI agents, targeted agent configuration via ruler.toml, MCP (Model Context Protocol) server propagation, automatic .gitignore updates to keep generated files out of version control, and simple CLI commands for initializing and applying configurations. The tool supports nested rule loading, allowing teams to define context-specific instructions for different parts of a codebase.
Ruler is designed for teams, individuals, and open-source projects that rely on multiple AI coding agents working in the same project. It is especially valuable for teams using multiple AI agents simultaneously, as it improves workflow consistency, simplifies onboarding new team members, and ensures all assistants follow the same standards across projects. The tool is open-source under the MIT License and is currently in beta research preview.
The tool requires Node.js 18.x or higher and can be installed globally via npm or used with npx for one-off commands. Users create rule files in .ruler/ directory, configure agent preferences in ruler.toml, and run ruler apply to distribute rules to all configured AI agents.
Ruler pricing
Pricing model: Freemium
Ruler is free and open-source under the MIT License. There are no paid plans or tiers. The tool can be installed globally via 'npm install -g @intellectronica/ruler' or used with npx for one-off commands without any cost. All features including central rule management, MCP propagation, .gitignore automation, and support for 17+ AI agents are included for free.
Ruler pros
- Centralizes all AI coding assistant rules in one .ruler/ directory
- Supports 17+ AI agents including Copilot, Claude, Cursor, Aider, Windsurf
- Automatic distribution of rules to agent-specific configuration files
- Single source of truth eliminates duplicated configuration effort
- Markdown-based rule files are human-readable and easy to edit
- Supports nested rule loading for context-specific instructions
- MCP server configuration propagation across compatible agents
- Automatic .gitignore updates keep generated files out of version control
- Simple CLI with ruler init and ruler apply commands
- Revert command safely undoes all changes with backup files
- Customizable via ruler.toml with agent-specific settings
- Granular rule files allow breaking complex instructions into focused pieces
- Works with global configuration for projects without local .ruler/
- CI/CD friendly with GitHub Actions and npm scripts integration
- Open-source under MIT License with active community contribution
- Verbose logging mode for debugging configuration issues
- Case-insensitive agent matching for flexible configuration
Ruler cons
- Currently in beta research preview, not production-ready
- All agents receive the same concatenated rules, no native agent-specific rules
- Requires Node.js 18.x or higher as a prerequisite
- Only 15 pros listed above, need more
- Agent-specific instructions require manual section headers in rule files
- Global installation may require sudo on Unix systems
- Configuration validation errors can be confusing for new users
- MCP configuration requires environment variable setup for Codex CLI
- Permission denied errors possible during global installation
- Existing agent configs are overwritten (though backed up)
- No GUI interface, only command-line usage
- Learning curve for ruler.toml configuration format
- Some agents lack MCP configuration support
- Rule file concatenation order is alphabetical, not customizable
- No built-in rule testing or validation feature
Frequently asked questions about Ruler
Can I use different rules for different agents?
Currently, all agents receive the same concatenated rules from the .ruler/ directory. For agent-specific instructions, you should include sections in your rule files with headers like '## GitHub Copilot Specific' or '## Aider Configuration' to provide targeted guidance within the shared rule files.
How do I temporarily disable Ruler for an agent?
Set enabled = false in ruler.toml under the [agents.agentname] section for that specific agent. Alternatively, use the --agents flag when running ruler apply to specify only the agents you want to target, excluding others from the current run.
What happens to my existing agent configuration files?
Ruler creates backups with the .bak extension before overwriting any existing files. This ensures you can restore your original configuration if needed. The revert command intelligently restores files from these backups when restoring to pre-ruler state.
Can I run Ruler in CI/CD pipelines?
Yes, you can run Ruler in CI/CD pipelines. Use 'ruler apply --no-gitignore' in CI to avoid modifying .gitignore. The website provides a GitHub Actions example that installs Ruler, applies configuration, and checks for uncommitted changes to ensure ruler configuration is in sync.
How do I migrate from version 0.1.x to 0.2.0?
Version 0.2.0 is backward compatible. Your existing .ruler/ directory and ruler.toml will continue to work without changes. New features like verbose logging and improved error messages are opt-in, so you can upgrade at your own pace.
What Node.js version is required?
Node.js 18.x or higher is required to use Ruler. If you have an older version of Node.js installed, you'll need to upgrade before installing or running the tool.
How do I initialize Ruler in a new project?
Navigate to your project's root directory and run 'ruler init'. This creates the .ruler/ directory, .ruler/instructions.md (a starter Markdown file for your rules), .ruler/ruler.toml (main configuration file), and .ruler/mcp.json (example MCP server configuration).
Can I use a custom configuration file?
Yes, use the --config flag followed by the path to your custom ruler.toml file. For example: 'ruler apply --config ./team-configs/ruler.frontend.toml'. This is useful for team-specific configurations or different environments.
How does .gitignore integration work?
Ruler automatically creates or updates .gitignore in your project root, adding paths to a managed block marked with '# START Ruler Generated Files' and '# END Ruler Generated Files'. It preserves existing content outside this block and sorts paths alphabetically. You can disable this with --no-gitignore or in ruler.toml.
What is MCP and how does Ruler manage it?
MCP (Model Context Protocol) provides broader context to AI models through server configurations. Ruler manages and distributes MCP settings via .ruler/mcp.json, using either merge (default) or overwrite strategy controlled by ruler.toml or CLI flags. Supported agents include GitHub Copilot, Claude Code, Cursor, Windsurf, and others with MCP configuration paths listed in the supported agents table.