ruler

Unified AI agent configuration propagation across 18+ coding assistants.

Repository: https://github.com/intellectronica/ruler Documentation: https://deepwiki.com/intellectronica/ruler

---

Overview

Ruler centralizes AI agent instructions in .ruler/ and distributes them to all configured agents via ruler apply. Supports Model Context Protocol (MCP) propagation with merge/overwrite strategies.

.ruler/
├── *.md           # Rules (concatenated alphabetically)
├── ruler.toml     # Agent config + MCP settings
└── mcp.json       # Shared MCP servers

---

Installation

npm install -g ruler
# or
npx ruler init

---

Commands

ruler init

Creates .ruler/ directory with default files:

ruler init           # Local project
ruler init --global  # ~/.config/ruler/

Creates:

• instructions.md - Central AI instructions
• ruler.toml - Configuration file
• mcp.json - MCP server definitions

ruler apply

Propagates rules to all configured agents:

ruler apply                          # All default agents
ruler apply --agents claude,codex    # Specific agents
ruler apply --no-mcp                 # Skip MCP propagation
ruler apply --mcp-overwrite          # Replace native MCP configs
ruler apply --no-gitignore           # Skip .gitignore updates

ruler revert

Restores files from backups:

ruler revert                  # Restore all, delete backups
ruler revert --keep-backups   # Restore but keep .bak files

---

Supported Agents (18)

| Agent | Identifier | Instructions Output | MCP Config | |-------|------------|---------------------|------------| | GitHub Copilot | copilot | .github/copilot-instructions.md | .vscode/mcp.json | | Claude Code | claude | CLAUDE.md | .mcp.json | | OpenAI Codex CLI | codex | AGENTS.md | .codex/config.toml | | Jules | jules | AGENTS.md | - | | Cursor | cursor | .cursor/rules/ruler_cursor_instructions.mdc | .cursor/mcp.json | | Windsurf | windsurf | .windsurf/rules/ruler_windsurf_instructions.md | ~/.codeium/windsurf/mcp_config.json | | Cline | cline | .clinerules | - | | Amp | amp | AGENT.md | - | | Aider | aider | ruler_aider_instructions.md + .aider.conf.yml | .mcp.json | | Firebase Studio | firebase | .idx/airules.md | - | | Open Hands | openhands | .openhands/microagents/repo.md | .openhands/config.toml | | Gemini CLI | gemini-cli | GEMINI.md | .gemini/settings.json | | Junie | junie | .junie/guidelines.md | - | | AugmentCode | augmentcode | .augment/rules/ruler_augment_instructions.md | .vscode/settings.json | | Kilo Code | kilocode | .kilocode/rules/ruler_kilocode_instructions.md | .kilocode/mcp.json | | OpenCode | opencode | AGENTS.md | opencode.json | | Goose | goose | .goosehints | - | | Crush | crush | CRUSH.md | .crush.json |

---

Configuration: ruler.toml

Complete configuration reference:

# ═══════════════════════════════════════════════════════════════════
# DEFAULT AGENTS
# ═══════════════════════════════════════════════════════════════════

# Agents to run when --agents flag is not specified
# If omitted, all agents are active
default_agents = ["copilot", "claude", "codex", "cursor", "amp"]

# ═══════════════════════════════════════════════════════════════════
# GLOBAL MCP CONFIGURATION
# ═══════════════════════════════════════════════════════════════════

[mcp]
# Enable/disable MCP propagation globally (default: true)
enabled = true

# How to combine with native configs: "merge" or "overwrite"
# merge: Union of servers, incoming takes precedence on conflicts
# overwrite: Replace native config entirely
merge_strategy = "merge"

# ═══════════════════════════════════════════════════════════════════
# GITIGNORE CONFIGURATION
# ═══════════════════════════════════════════════════════════════════

[gitignore]
# Auto-add generated files to .gitignore (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.codex]
enabled = true
output_path = "AGENTS.md"
output_path_config = ".codex/config.toml"

# Agent-specific MCP override
[agents.codex.mcp]
enabled = true
merge_strategy = "merge"

[agents.cursor]
enabled = true
output_path = ".cursor/rules/ruler_cursor_instructions.mdc"

[agents.amp]
enabled = true
output_path = "AGENT.md"

[agents.aider]
enabled = true
output_path_instructions = "ruler_aider_instructions.md"
output_path_config = ".aider.conf.yml"

[agents.windsurf]
enabled = false  # Disable specific agent

[agents.opencode]
enabled = true
output_path = "AGENTS.md"

[agents.gemini-cli]
enabled = true

---

Configuration: mcp.json

Define shared MCP servers:

{
  "mcpServers": {
    "gay": {
      "type": "stdio",
      "command": "julia",
      "args": ["--project=@gay", "-e", "using Gay; Gay.serve_mcp()"],
      "env": {
        "GAY_SEED": "1069"
      }
    },
    "firecrawl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}"
      }
    },
    "exa": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "${EXA_API_KEY}"
      }
    },
    "tree-sitter": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-tree-sitter"]
    }
  }
}

---

Architecture

IAgent Interface

All agents implement:

interface IAgent {
  getIdentifier(): string;        // e.g., "copilot", "claude"
  getName(): string;              // Human-readable name
  getDefaultOutputPath(): string | Record<string, string>;
  getMcpServerKey?(): string;     // e.g., "servers" for Copilot
  applyRulerConfig(
    concatenatedRules: string,
    projectRoot: string,
    rulerMcpJson: object,
    agentConfig?: AgentConfig
  ): Promise<void>;
}

MCP Server Keys by Agent

| Agent | MCP Server Key | |-------|----------------| | Copilot | servers | | Claude | mcpServers | | OpenCode | mcp | | Others | mcpServers |

Orchestration Flow (src/lib.ts)

1. Load ruler.toml configuration
2. Find .ruler/ directory (local or global)
3. Concatenate all *.md files alphabetically
4. Load and validate mcp.json
5. For each selected agent:
   a. Determine output paths (with overrides)
   b. Backup existing files (.bak)
   c. Call agent.applyRulerConfig()
   d. If MCP enabled:
      - Read native MCP config
      - Merge with ruler mcp.json
      - Write merged config
6. Update .gitignore with generated paths

---

MCP Merge Strategies

Merge (default)

Combines servers from both configs, incoming takes precedence:

// base (native)
{ "mcpServers": { "a": {...}, "b": {...} } }

// incoming (ruler)
{ "mcpServers": { "b": {...}, "c": {...} } }

// result
{ "mcpServers": { "a": {...}, "b": {...from ruler}, "c": {...} } }

Overwrite

Replaces native config entirely:

// result = incoming config only
{ "mcpServers": { "b": {...}, "c": {...} } }

---

Backup Strategy

1. Before overwriting, create file.bak
2. On revert: restore from .bak, then delete .bak
3. With --keep-backups: restore but keep .bak files
4. Generated files (no backup) are simply deleted on revert

---

Special Agent Handling

OpenHands

• MCP config in .openhands/config.toml
• Uses stdio_servers key (TOML format)

AugmentCode

• MCP embedded in .vscode/settings.json
• Custom propagation function

OpenCode

• MCP in opencode.json
• Uses mcp key instead of mcpServers

Cursor

• Adds YAML front-matter to rules
• .mdc extension for instructions

Aider

• Two output files: instructions + config
• Config is .aider.conf.yml

---

Configuration Precedence

CLI flags (highest)
    ↓
ruler.toml settings
    ↓
Built-in defaults (lowest)

Examples:

• --no-gitignore overrides [gitignore] enabled = true
• --agents claude overrides default_agents
• Agent-specific [agents.X.mcp] overrides global [mcp]

---

Example Workflow

# 1. Initialize
ruler init

# 2. Add rules
cat > .ruler/01-style.md << 'EOF'
# Code Style
- Use TypeScript
- Prefer functional programming
- Maximum line length: 100
EOF

cat > .ruler/02-security.md << 'EOF'
# Security
- Never log secrets
- Use parameterized queries
- Validate all inputs
EOF

# 3. Configure MCP
cat > .ruler/mcp.json << 'EOF'
{
  "mcpServers": {
    "gay": {
      "command": "julia",
      "args": ["--project=@gay", "-e", "using Gay; Gay.serve_mcp()"]
    }
  }
}
EOF

# 4. Configure agents
cat > .ruler/ruler.toml << 'EOF'
default_agents = ["claude", "codex", "amp"]

[mcp]
enabled = true
merge_strategy = "merge"

[agents.claude]
enabled = true

[agents.codex]
enabled = true

[agents.amp]
enabled = true
EOF

# 5. Apply
ruler apply

# 6. Verify
cat CLAUDE.md
cat AGENTS.md
cat AGENT.md

# 7. Iterate and refine
vim .ruler/01-style.md
ruler apply

# 8. Revert if needed
ruler revert

---

Integration with Music-Topos

The .ruler/ directory in music-topos extends the standard ruler with:

GF(3) Bisimulation

[bisimulation]
enabled = true
polarity_rotation = true

[bisimulation.agents]
claude = "PLUS"      # +1
codex = "ERGODIC"    # 0
cursor = "MINUS"     # -1
# Sum = 0 mod 3 ✓

propagate.clj (Babashka)

(def AGENTS
  {:codex   {:trit 0   :skills-path ".codex/skills"}
   :claude  {:trit -1  :skills-path ".claude/skills"}
   :amp     {:trit 0   :skills-path ".ruler/skills"}
   :cursor  {:trit -1  :skills-path ".cursor/skills"}
   :copilot {:trit 1   :skills-path ".vscode/skills"}
   :aider   {:trit 1   :skills-path ".skillz"}})

;; Propagate with GF(3) conservation check
(propagate-all!)

---

References

• GitHub: https://github.com/intellectronica/ruler
• DeepWiki: https://deepwiki.com/intellectronica/ruler
• Author: intellectronica (Eran Kampf)