Ruler: Centralise Your AI Coding Assistant Instructions

<table style="width:100%"> <tr> <td style="vertical-align: top;"> <p> <a href="https://github.com/intellectronica/ruler/actions/workflows/ci.yml"><img src="https://github.com/intellectronica/ruler/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://www.npmjs.com/package/@intellectronica/ruler"><img src="https://badge.fury.io/js/%40intellectronica%2Fruler.svg" alt="npm version"></a> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"> </p> <ul> <li><strong>GitHub</strong>: <a href="https://github.com/intellectronica/ruler">intellectronica/ruler</a></li> <li><strong>NPM</strong>: <a href="https://www.npmjs.com/package/@intellectronica/ruler">@intellectronica/ruler</a></li> </ul> <hr /> <p> <em>Animation by <a href="https://isaacflath.com/">Isaac Flath</a> of <strong><a href="https://elite-ai-assisted-coding.dev/">Elite AI-Assisted Coding</a></strong></em> ➡︎ </p> </td> <td style="vertical-align: top; width:33%;"> <img src="https://raw.githubusercontent.com/intellectronica/ruler/main/img/ruler-short.gif" alt="Ruler demo" style="width:300px; height:auto; display:block;" /> </td> </tr> </table>

---

Beta Research Preview

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

Why Ruler?

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
• Complex project structures requiring context-specific instructions for different components

Ruler solves this by providing a single source of truth for all your AI agent instructions, automatically distributing them to the right configuration files. With support for nested rule loading, Ruler can handle complex project structures with context-specific instructions for different components.

Core Features

• Centralised Rule Management: Store all AI instructions in a dedicated .ruler/ directory using Markdown files
• Nested Rule Loading: Support complex project structures with multiple .ruler/ directories for context-specific instructions
• 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

Supported AI Agents

| Agent | Rules File(s) | MCP Configuration / Notes | Skills Support / Location | Subagents Support / Location | | ---------------------- | ---------------------------------------------- | ------------------------------------------------ | ------------------------- | ---------------------------- | | AGENTS.md | AGENTS.md | (pseudo-agent ensuring root AGENTS.md exists) | - | - | | GitHub Copilot | AGENTS.md | .mcp.json | .claude/skills/ | .github/agents/ | | Claude Code | CLAUDE.md | .mcp.json | .claude/skills/ | .claude/agents/ | | OpenAI Codex CLI | AGENTS.md | .codex/config.toml | .agents/skills/ | .codex/agents/ (.toml) | | Pi Coding Agent | AGENTS.md | - | .pi/skills/ | - | | Jules | AGENTS.md | - | - | - | | Cursor | AGENTS.md | .cursor/mcp.json | .cursor/skills/ | .cursor/agents/ | | Windsurf | AGENTS.md | .windsurf/mcp_config.json | .windsurf/skills/ | - | | Cline | .clinerules | - | - | - | | Crush | CRUSH.md | .crush.json | - | - | | Amp | AGENTS.md | - | .agents/skills/ | - | | Antigravity | .agent/rules/ruler.md | - | .agent/skills/ | - | | Amazon Q CLI | .amazonq/rules/ruler_q_rules.md | .amazonq/mcp.json | - | - | | Aider | AGENTS.md, .aider.conf.yml | .mcp.json | - | - | | Firebase Studio | .idx/airules.md | .idx/mcp.json | - | - | | Open Hands | .openhands/microagents/repo.md | config.toml | - | - | | Gemini CLI | AGENTS.md | .gemini/settings.json | .gemini/skills/ | - | | Junie | .junie/guidelines.md | .junie/mcp/mcp.json | .junie/skills/ | - | | AugmentCode | .augment/rules/ruler_augment_instructions.md | - | - | - | | Kilo Code | AGENTS.md | .kilocode/mcp.json | .claude/skills/ | - | | OpenCode | AGENTS.md | opencode.json | .opencode/skills/ | - | | Goose | .goosehints | - | .agents/skills/ | - | | Qwen Code | AGENTS.md | .qwen/settings.json | - | - | | RooCode | AGENTS.md | .roo/mcp.json | .roo/skills/ | - | | Zed | AGENTS.md | .zed/settings.json (project root, never $HOME) | .agents/skills/ | - | | Trae AI | .trae/rules/project_rules.md | - | - | - | | Warp | WARP.md | - | - | - | | Kiro | .kiro/steering/ruler_kiro_instructions.md | .kiro/settings/mcp.json | .kiro/skills/ | - | | Firebender | firebender.json | firebender.json (rules and MCP in same file) | - | - | | Factory Droid | AGENTS.md | .factory/mcp.json | .factory/skills/ | - | | Mistral Vibe | AGENTS.md | .vibe/config.toml | .vibe/skills/ | - | | JetBrains AI Assistant | .aiassistant/rules/AGENTS.md | - | - | - |

Getting Started

Installation

Requires Node.js ^20.19.0 || ^22.12.0 || >=23.

Global Installation (Recommended for CLI use):

npm install -g @intellectronica/ruler

Using npx (for one-off commands):

npx @intellectronica/ruler apply

Project Initialisation

1. Navigate to your project's root directory
2. Run ruler init
3. This creates:

• .ruler/ directory
• .ruler/AGENTS.md: The primary starter Markdown file for your rules
• .ruler/ruler.toml: The main configuration file for Ruler (now contains sample MCP server sections; legacy .ruler/mcp.json no longer scaffolded)
• (Optional legacy fallback) If you previously used .ruler/instructions.md, it is still respected when AGENTS.md is absent. (The prior runtime warning was removed.)

Additionally, you can create a global configuration to use when no local .ruler/ directory is found:

ruler init --global

The global configuration will be created to $XDG_CONFIG_HOME/ruler (default: ~/.config/ruler).

Core Concepts

The .ruler/ Directory

This is your central hub for all AI agent instructions:

• Primary File Order & Precedence:
  1. A repository root AGENTS.md (outside .ruler/) if present (highest precedence, prepended)
  2. .ruler/AGENTS.md (new default starter file)
  3. Legacy .ruler/instructions.md (used as the primary file only if .ruler/AGENTS.md is absent; no longer emits a deprecation warning)
  4. Remaining discovered .md files under .ruler/ (and subdirectories) in sorted order, including instructions.md when both top-level files exist
• Rule Files (*.md): Discovered recursively from .ruler/ or $XDG_CONFIG_HOME/ruler and concatenated in the order above
• 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, output paths, and MCP server settings
• mcp.json: (Legacy, deprecated) Shared MCP server settings - no longer scaffolded but still supported for backward compatibility

This ordering lets you keep a short, high-impact root AGENTS.md (e.g. executive project summary) while housing detailed guidance inside .ruler/.

Nested Rule Loading

Ruler now supports nested rule loading with the --nested flag, enabling context-specific instructions for different parts of your project:

project/
├── .ruler/           # Global project rules
│   ├── AGENTS.md
│   └── coding_style.md
├─