DOCSEARCHbyAlgolia
Submit Docs

Ruler

repository·main·Indexed 25 days ago

https://github.com/intellectronica/ruler

A tool for centralizing AI coding assistant instructions. Ruler maintains a single source of truth for rules in a `.ruler/` directory and automatically distributes them to configuration files for agents such as GitHub Copilot, Cursor, and Claude Code. It supports nested rule loading, Model Context Protocol (MCP) server configuration, and the management of specialized knowledge packages called 'skills'.

Tokens
12.6K
Snippets
35
Records
78
Agent score
83%

What's inside @intellectronica/ruler

  1. Understand the `.ruler/` directory structure and precedence

    main

    The .ruler/ directory serves as the central hub for AI agent instructions. Ruler discovers and concatenates .md rule files recursively.

    File Precedence Order:

    1. AGENTS.md at the repository root (highest precedence, prepended).
    2. .ruler/AGENTS.md.
    3. .ruler/instructions.md (legacy fallback, used only if .ruler/AGENTS.md is absent).
    4. All other .md files under .ruler/ and its subdirectories, sorted by name.

    Each file's content is prepended with a traceability marker: <!-- Source: <relative_path_to_md_file> -->.

    Configuration Files:

    • ruler.toml: The master configuration for behavior, agent selection, output paths, and MCP server settings.
    • mcp.json: Legacy/deprecated shared MCP server settings (still supported for backward compatibility).

  2. Install Ruler via npm

    main

    Ruler requires Node.js ^20.19.0 || ^22.12.0 || >=23.

    To use the CLI globally, install the package using npm:

    npm install -g @intellectronica/ruler

    Alternatively, you can run commands without a global installation using npx:

    npx @intellectronica/ruler apply

  3. Initialize a Ruler project

    main

    To set up Ruler in your project, navigate to your project's root directory and run the init command. This scaffolds the necessary directory structure and configuration files.

    Running ruler init creates:

    • .ruler/ directory
    • .ruler/AGENTS.md: The primary Markdown file for your rules.
    • .ruler/ruler.toml: The main configuration file for Ruler.

    If you want to create a global configuration that Ruler will use when no local .ruler/ directory is present, run:

    ruler init --global

    The global configuration is created at $XDG_CONFIG_HOME/ruler (defaulting to ~/.config/ruler).

    ruler init

  4. Configure MCP (Model Context Protocol) Servers

    main

    Ruler manages MCP server configurations to provide context to AI models. You can define servers globally or specifically for an agent.

    Server Types

    • Local/stdio servers: Require a command and args.
    • Remote servers: Require a url (and optional headers).

    Configuration Syntax

    Global Servers: Defined under [mcp_servers.<name>].

    Agent-Specific Servers: Defined under [agents.<agent>.mcp_servers.<name>]. These override global servers with the same name for that specific agent.

    Note on Legacy Format: The .ruler/mcp.json format is deprecated. Use ruler.toml instead.

    # Global MCP server (stdio)
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

# Global MCP server (remote)
[mcp_servers.search]
url = "https://mcp.example.com"
[mcp_servers.search.headers]
Authorization = "Bearer your-token"

# Agent-specific MCP server override
[agents.cursor.mcp_servers.slack]
url = "https://mcp.slack.com/mcp"
auth = { CLIENT_ID = "CURSOR_ID" }

  5. Verify Ruler configuration in GitHub Actions

    main

    To prevent configuration drift in a team environment, use a GitHub Action to verify that the committed agent files (like AGENTS.md, CLAUDE.md, etc.) match the source files in the .ruler/ directory. If they don't match, the CI will fail.

    # .github/workflows/ruler-check.yml
name: Ruler guidance in sync

on: [pull_request, push]

jobs:
  ruler-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 24.15.0
          cache: 'pnpm'
      - name: Verify committed agent files match .ruler/
        run: |
          pnpm dlx @intellectronica/ruler apply --no-gitignore --no-mcp
          DRIFT="$(git status --porcelain -- AGENTS.md CLAUDE.md .claude/skills .codex/skills)"
          if [ -n "$DRIFT" ]; then
            echo "::error::Committed agent files are out of sync with .ruler/. Run 'pnpm dlx @intellectronica/ruler apply --no-gitignore --no-mcp' and commit the result."
            exit 1
          fi

  6. Migrate from legacy instructions.md

    main

    If you are migrating from an older version of Ruler that used instructions.md, rename .ruler/instructions.md to .ruler/AGENTS.md.

    If you keep both files, AGENTS.md will take precedence, and the contents of the legacy file will be concatenated afterward. Using AGENTS.md prevents the deprecation warning.

  7. Initialize and apply Ruler in a project

    main

    To set up Ruler in a new project, initialize the directory structure and then apply the rules to your AI agents.

    1. Initialize: Run ruler init to generate the .ruler/ directory and default configuration files.
    2. Configure: Add your coding guidelines to .ruler/AGENTS.md or create additional .md files in the .ruler/ directory.
    3. Apply: Run ruler apply to propagate these rules to your AI agent configuration files (e.g., CLAUDE.md, .cursor, etc.).
    # Initialize Ruler in your project
cd your-project
ruler init

# Apply rules to all AI agents
ruler apply

  9. Configure Subagents Support (Experimental)

    main

    Ruler can distribute subagents from a single source of truth in .ruler/agents/ to the native locations of supported AI agents. Subagent propagation is disabled by default.

    Supported Agents and Targets

    AgentTarget locationFormat
    Claude Code.claude/agents/<relative-path>.mdMarkdown + YAML frontmatter
    Cursor.cursor/agents/<relative-path>.mdMarkdown + YAML frontmatter
    OpenAI Codex CLI.codex/agents/<relative-path>.tomlTOML
    GitHub Copilot.github/agents/<relative-path>.mdMarkdown + YAML frontmatter

    Enabling Subagents

    You can enable subagents for a single run via CLI or permanently via ruler.toml.

    CLI Flag:

    ruler apply --subagents

    Configuration (.ruler/ruler.toml):

    [agents]
enabled = true

    Note: [agents] enabled controls native subagent propagation. It is independent of [agents.<name>] enabled which controls appending rules to CLAUDE.md or AGENTS.md.

  10. Enable nested rule loading with the `--nested` flag

    main

    Ruler supports nested rule loading, allowing you to define context-specific instructions for different subdirectories (e.g., component-specific rules in src/.ruler/ or test-specific rules in tests/.ruler/).

    Precedence for Nested Mode:

    1. CLI flag: ruler apply --nested or --no-nested (highest priority).
    2. Configuration: nested = true in ruler.toml.
    3. Default: Disabled.

    Note: Nested mode is currently experimental. When enabled, downstream configurations are forced to maintain nested = true to ensure scoped MCP bundles and settings are correctly processed.

    ruler apply --nested

  11. Author a Subagent in `.ruler/agents/`

    main

    Subagents are authored as Markdown files with YAML frontmatter in the .ruler/agents/ directory. The filename stem must match the name field in the frontmatter.

    Required Frontmatter

    • name (string): Must match the filename stem (e.g., code-reviewer.md $\rightarrow$ name: code-reviewer).
    • description (string): Instructions for when the parent agent should delegate to this subagent.

    Optional Frontmatter

    • tools (string[]): Claude uses verbatim; GitHub Copilot maps these to aliases (e.g., Read $\rightarrow$ read).
    • model (string): Used by all targets; Cursor defaults to inherit if omitted.
    • readonly (boolean): Cursor uses verbatim; Codex uses sandbox_mode; Copilot uses disable-model-invocation.
    • is_background (boolean): Used by Cursor only.

    Example Subagent File

    Create .ruler/agents/code-reviewer.md:

    ---
name: code-reviewer
description: Reviews changes against SOLID/DRY/KISS
tools: [Read, Grep, Glob]
readonly: true
---

You review code changes for quality.

  12. Configure nested rule loading

    main

    For large projects with multiple components, you can enable nested rule loading. This allows each subdirectory to maintain its own .ruler/ directory with specific instructions and MCP bundles. When enabled, Ruler loads rules from every .ruler/ directory in the hierarchy.

    To enable this, set nested = true in your .ruler/ruler.toml file or use the --nested flag with the CLI.

    # .ruler/ruler.toml
nested = true
    # Enable via CLI
ruler apply --nested

# Disable via CLI
ruler apply --no-nested