ruler

What it is

Ruler is a tool to centralize AI agent instructions and automatically distribute them to configuration files for multiple AI agents (e.g., GitHub Copilot, Claude Code, Windsurf, Aider). It uses a central .ruler/ directory with Markdown rule files and a ruler.toml master configuration to manage agent-specific output paths and MCP server settings. It supports nested rule loading to handle complex project structures.

How it works

• The rules are stored under a .ruler/ directory (and can be loaded from a repository root AGENTS.md if present).
• Rule files (*.md) are discovered recursively and concatenated in a defined order, with a trace marker <!-- Source: <path> --> prepended to each.
• ruler.toml provides master configuration for behavior, agent selection, output paths, and MCP server settings; mcp.json is legacy and deprecated but still supported.
• Nested rule loading allows per-directory rules to be applied, with precedence rules for enabling/disabling nested mode.
• The tool can apply rules to the configuration files of supported AI agents and can manage MCP server propagation, as well as automatic .gitignore updates.

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: repository root AGENTS.md, then .ruler/AGENTS.md, then legacy files, then other .md files under .ruler/
• Rule Files (*.md): Discovered recursively and concatenated in order
• 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

Nested Rule Loading

Ruler supports nested rule loading via the --nested flag, enabling context-specific instructions for different parts of your project. It discovers all .ruler/ directories, loads files in order, and applies precedence rules to determine whether nested mode is enabled. When nested, downstream configs are forced to nested = true, and a warning is emitted if a child config attempts to disable it.

Nested mode is experimental and may change in future releases.

Usage: The apply Command

ruler apply [options]

The apply command searches upward from --project-root (default: current directory) for the nearest .ruler/ directory. If none is found, it falls back to $XDG_CONFIG_HOME/ruler.

Options

| Option | Description | | --project-root <path> | Project root path (default: current directory). | | --agents <agent1,agent2,...> | Comma-separated agent names to target. | | --config <path> | Custom ruler.toml path. | | --mcp / --with-mcp | Enable applying MCP server configurations (default: true). | | --no-mcp | Disable applying MCP server configurations. | | --mcp-overwrite | Overwrite native MCP config instead of merging. | | --gitignore | Enable automatic .gitignore updates (default: true). | | --no-gitignore | Disable automatic .gitignore updates. | | --gitignore-local | Write managed ignore entries to .git/info/exclude instead. | | --nested | Enable nested rule loading (default: inherit from config or disabled). | | --no-nested | Disable nested rule loading even if nested = true in config. | | --backup | Enable creation of .bak backup files (default: from config or enabled). |

Releases

Latest releases include v0.3.44 (2026-06-30) with fixes for skipping symlinked skill entries and dist cleanup before builds, followed by v0.3.43 (2026-06-20) and earlier. See the full changelog for details.

Traction

2835 stars, 153 forks, 8 open issues. Language: TypeScript. License: MIT. Created: 2025-05-20. Last push: 2026-07-29.

Behind the repo

GitHub repository: intellectronica/ruler. Topics include agents, ai, aider, claude-code, codex, cursor, github-copilot, vibe-coding, windsurf.

Caveats

License: MIT. Created: 2025-05-20. Last push: 2026-07-29. Open issues: 8. Release notes mention deprecated mcp.json as legacy but still supported.