Ruler – apply the same rules and MCP to all coding agents

6 hours ago 2

GitHub: intellectronica/ruler
NPM: @intellectronica/ruler

Beta Research Preview

Please test this version carefully in your environment
Report issues at https://github.com/intellectronica/ruler/issues

Managing instructions across multiple AI coding tools becomes complex as your team grows. Different agents (GitHub Copilot, Claude, Cursor, Aider, etc.) require their own configuration files, leading to:

Inconsistent guidance across AI tools
Duplicated effort maintaining multiple config files
Context drift as project requirements evolve
Onboarding friction for new AI tools

Ruler solves this by providing a single source of truth for all your AI agent instructions, automatically distributing them to the right configuration files.

Centralised Rule Management: Store all AI instructions in a dedicated .ruler/ directory using Markdown files
Automatic Distribution: Ruler applies these rules to configuration files of supported AI agents
Targeted Agent Configuration: Fine-tune which agents are affected and their specific output paths via ruler.toml
MCP Server Propagation: Manage and distribute Model Context Protocol (MCP) server settings
.gitignore Automation: Keeps generated agent config files out of version control automatically
Simple CLI: Easy-to-use commands for initialising and applying configurations

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.mdc
Windsurf	.windsurf/rules/ruler_windsurf_instructions.md
Cline	.clinerules
Aider	ruler_aider_instructions.md and .aider.conf.yml
Firebase Studio	.idx/airules.md
Open Hands	.openhands/microagents/repo.md and .openhands/config.toml
Gemini CLI	GEMINI.md and .gemini/settings.json

Node.js 18.x or higher is required.

Global Installation (Recommended for CLI use):

npm install -g @intellectronica/ruler

Using npx (for one-off commands):

npx @intellectronica/ruler apply

Navigate to your project's root directory
Run ruler init
This creates:
- .ruler/ directory
- .ruler/instructions.md: A starter Markdown file for your rules
- .ruler/ruler.toml: The main configuration file for Ruler
- .ruler/mcp.json: An example MCP server configuration

This is your central hub for all AI agent instructions:

Rule Files (*.md): Discovered recursively from .ruler/ and alphabetically concatenated
Concatenation Marker: Each file's content is prepended with --- Source: <relative_path_to_md_file> --- for traceability
ruler.toml: Master configuration for Ruler's behavior, agent selection, and output paths
mcp.json: Shared MCP server settings

Best Practices for Rule Files

Granularity: Break down complex instructions into focused .md files:

coding_style.md
api_conventions.md
project_architecture.md
security_guidelines.md

Example rule file (.ruler/python_guidelines.md):

# Python Project Guidelines ## General Style - Follow PEP 8 for all Python code - Use type hints for all function signatures and complex variables - Keep functions short and focused on a single task ## Error Handling - Use specific exception types rather than generic `Exception` - Log errors effectively with context ## Security - Always validate and sanitize user input - Be mindful of potential injection vulnerabilities

Option Description

--project-root <path>	Path to your project's root (default: current directory)
--agents <agent1,agent2,...>	Comma-separated list of agent names to target
--config <path>	Path to a custom ruler.toml configuration file
--mcp / --with-mcp	Enable applying MCP server configurations (default: true)
--no-mcp	Disable applying MCP server configurations
--mcp-overwrite	Overwrite native MCP config entirely instead of merging
--gitignore	Enable automatic .gitignore updates (default: true)
--no-gitignore	Disable automatic .gitignore updates
--verbose / -v	Display detailed output during execution

Apply rules to all configured agents:

Apply rules only to GitHub Copilot and Claude:

ruler apply --agents copilot,claude

Apply rules only to Firebase Studio:

ruler apply --agents firebase

Use a specific configuration file:

ruler apply --config ./team-configs/ruler.frontend.toml

Apply rules with verbose output:

Apply rules but skip MCP and .gitignore updates:

ruler apply --no-mcp --no-gitignore

Configuration (ruler.toml) in Detail

Defaults to .ruler/ruler.toml in the project root. Override with --config CLI option.

# Default agents to run when --agents is not specified # Uses case-insensitive substring matching default_agents = ["copilot", "claude", "aider"] # --- Global MCP Server Configuration --- [mcp] # Enable/disable MCP propagation globally (default: true) enabled = true # Global merge strategy: 'merge' or 'overwrite' (default: 'merge') merge_strategy = "merge" # --- Global .gitignore Configuration --- [gitignore] # Enable/disable automatic .gitignore updates (default: true) enabled = true # --- Agent-Specific Configurations --- [agents.copilot] enabled = true output_path = ".github/copilot-instructions.md" [agents.claude] enabled = true output_path = "CLAUDE.md" [agents.aider] enabled = true output_path_instructions = "ruler_aider_instructions.md" output_path_config = ".aider.conf.yml" [agents.firebase] enabled = true output_path = ".idx/airules.md" [agents.gemini-cli] enabled = true # Agent-specific MCP configuration [agents.cursor.mcp] enabled = true merge_strategy = "merge" # Disable specific agents [agents.windsurf] enabled = false

CLI flags (e.g., --agents, --no-mcp, --mcp-overwrite, --no-gitignore)
Settings in ruler.toml (default_agents, specific agent settings, global sections)
Ruler's built-in defaults (all agents enabled, standard output paths, MCP enabled with 'merge')

MCP (Model Context Protocol) Server Configuration

MCP provides broader context to AI models through server configurations. Ruler can manage and distribute these settings across compatible agents.

Define your project's MCP servers:

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/path/to/project" ] }, "git": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."] } } }

Ruler uses this file with the merge (default) or overwrite strategy, controlled by ruler.toml or CLI flags.

Ruler automatically manages your .gitignore file to keep generated agent configuration files out of version control.

Creates or updates .gitignore in your project root
Adds paths to a managed block marked with # START Ruler Generated Files and # END Ruler Generated Files
Preserves existing content outside this block
Sorts paths alphabetically and uses relative POSIX-style paths

Example .gitignore Section

# Your existing rules node_modules/ *.log # START Ruler Generated Files .aider.conf.yml .clinerules .cursor/rules/ruler_cursor_instructions.mdc .github/copilot-instructions.md .windsurf/rules/ruler_windsurf_instructions.md AGENTS.md CLAUDE.md ruler_aider_instructions.md # END Ruler Generated Files dist/

CLI flags: --gitignore or --no-gitignore
Configuration: [gitignore].enabled in ruler.toml
Default: enabled

Practical Usage Scenarios

Scenario 1: Getting Started Quickly

# Initialize Ruler in your project cd your-project ruler init # Edit the generated files # - Add your coding guidelines to .ruler/instructions.md # - Customize .ruler/ruler.toml if needed # Apply rules to all AI agents ruler apply

Scenario 2: Team Standardization

Create .ruler/coding_standards.md, .ruler/api_usage.md
Commit the .ruler directory to your repository
Team members pull changes and run ruler apply to update their local AI agent configurations

Scenario 3: Project-Specific Context for AI

Detail your project's architecture in .ruler/project_overview.md
Describe primary data structures in .ruler/data_models.md
Run ruler apply to help AI tools provide more relevant suggestions

Integration with NPM Scripts

{ "scripts": { "ruler:apply": "ruler apply", "dev": "npm run ruler:apply && your_dev_command", "precommit": "npm run ruler:apply" } }

Integration with GitHub Actions

# .github/workflows/ruler-check.yml name: Check Ruler Configuration on: pull_request: paths: ['.ruler/**'] jobs: check-ruler: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '18' cache: 'npm' - name: Install Ruler run: npm install -g @intellectronica/ruler - name: Apply Ruler configuration run: ruler apply --no-gitignore - name: Check for uncommitted changes run: | if [[ -n $(git status --porcelain) ]]; then echo "::error::Ruler configuration is out of sync!" echo "Please run 'ruler apply' locally and commit the changes." exit 1 fi

"Cannot find module" errors:

Ensure Ruler is installed globally: npm install -g @intellectronica/ruler
Or use npx @intellectronica/ruler

Permission denied errors:

On Unix systems, you may need sudo for global installation

Agent files not updating:

Check if the agent is enabled in ruler.toml
Verify agent isn't excluded by --agents flag
Use --verbose to see detailed execution logs

Configuration validation errors:

Ruler now validates ruler.toml format and will show specific error details
Check that all configuration values match the expected types and formats

Use --verbose flag to see detailed execution logs:

This shows:

Configuration loading details
Agent selection logic
File processing information
MCP configuration steps

Q: Can I use different rules for different agents? A: Currently, all agents receive the same concatenated rules. For agent-specific instructions, include sections in your rule files like "## GitHub Copilot Specific" or "## Aider Configuration".

Q: How do I temporarily disable Ruler for an agent? A: Set enabled = false in ruler.toml under [agents.agentname], or use --agents flag to specify only the agents you want.

Q: What happens to my existing agent configuration files? A: Ruler creates backups with .bak extension before overwriting any existing files.

Q: Can I run Ruler in CI/CD pipelines? A: Yes! Use ruler apply --no-gitignore in CI to avoid modifying .gitignore. See the GitHub Actions example above.

Q: How do I migrate from version 0.1.x to 0.2.0? A: Version 0.2.0 is backward compatible. Your existing .ruler/ directory and ruler.toml will continue to work. New features like verbose logging and improved error messages are opt-in.

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

# Run all tests npm test # Run tests with coverage npm run test:coverage # Run tests in watch mode npm run test:watch

# Run linting npm run lint # Run formatting npm run format

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

For bugs and feature requests, please open an issue.

MIT

Read Entire Article