Ruler: Centralise Your AI Coding Assistant Instructions

# 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="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                         |
| ---------------- | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------- |
| AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)  | -                                                 |
| GitHub Copilot   | `AGENTS.md`                                      | `.vscode/mcp.json`                               | `.claude/skills/`                                 |
| Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                      | `.claude/skills/`                                 |
| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                             | `.codex/skills/`                                  |
| Pi Coding Agent  | `AGENTS.md`                                      | -                                                | `.pi/skills/`                                     |
| Jules            | `AGENTS.md`                                      | -                                                | -                                                 |
| Cursor           | `AGENTS.md`                                      | `.cursor/mcp.json`                               | `.cursor/skills/`                                 |
| Windsurf         | `AGENTS.md`                                      | `.windsurf/mcp_config.json`                      | -                                                 |
| Cline            | `.clinerules`                                    | -                                                | -                                                 |
| Crush            |

... (truncated)