Ruler: Centralise Your AI Coding Assistant Instructions

GitHub: intellectronica/ruler NPM: @intellectronica/ruler Animation by Isaac Flath of Elite AI-Assisted Coding ➡︎

---

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	-	-
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:

4. .ruler/ directory

5. .ruler/AGENTS.md: The primary starter Markdown file for your rules
6. .ruler/ruler.toml: The main configuration file for Ruler (now contains sample MCP server sections; legacy .ruler/mcp.json no longer scaffolded)
7. (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:
• A repository root AGENTS.md (outside .ruler/) if present (highest precedence, prepended)
• .ruler/AGENTS.md (new default starter file)
• Legacy .ruler/instructions.md (only if .ruler/AGENTS.md absent; no longer emits a deprecation warning)
• Remaining discovered .md files under .ruler/ (and subdirectories) in sorted order
• 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 `` 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
├── src/
│   └── .ruler/       # Component-specific rules
│       └── api_guidelines.md
├── tests/
│   └── .ruler/       # Test-specific rules
│       └── testing_conventions.md
└── docs/
    └── .ruler/       # Documentation rules
        └── writing_style.md

How it works:

• Discover all .ruler/ directories in the project hierarchy
• Load and concatenate rules from each directory in order
• Decide whether nested mode is enabled using the following precedence:
• ruler apply --nested (or --no-nested) takes top priority
• nested = true in ruler.toml
• Default to disabled when neither option is provided
• When a run is nested, downstream configs are forced to keep nested = true. If a child config attempts to disable it, Ruler keeps nested processing active and emits a warning in the logs.
• Nested processing carries forward each directory's own MCP bundle and configuration settings so that generated files remain scoped to their source directories while being normalized back to the project root.

[!CAUTION] Nested mode is experimental and may change in future releases. The CLI logs this warning the first time a nested run is detected so you know the behavior may evolve.

Perfect for:

• Monorepos with multiple services
• Projects with distinct components (frontend/backend)
• Teams needing different instructions for different areas
• Complex codebases with varying standards

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):

```markdown

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
• B