{"id":28561397,"url":"https://github.com/intellectronica/ruler","last_synced_at":"2026-01-12T10:04:06.387Z","repository":{"id":294687035,"uuid":"986861312","full_name":"intellectronica/ruler","owner":"intellectronica","description":"Ruler — apply the same rules to all coding agents","archived":false,"fork":false,"pushed_at":"2025-12-31T17:03:29.000Z","size":71682,"stargazers_count":2277,"open_issues_count":20,"forks_count":121,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-01-07T10:48:04.446Z","etag":null,"topics":["agents","ai","aider","claude-code","codex","cursor","github-copilot","vibe-coding","windsurf"],"latest_commit_sha":null,"homepage":"https://okigu.com/ruler","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intellectronica.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-20T08:22:59.000Z","updated_at":"2026-01-07T06:35:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"96ad7694-e838-422c-be4c-635440b5c42b","html_url":"https://github.com/intellectronica/ruler","commit_stats":null,"previous_names":["intellectronica/ruler"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/intellectronica/ruler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intellectronica%2Fruler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intellectronica%2Fruler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intellectronica%2Fruler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intellectronica%2Fruler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intellectronica","download_url":"https://codeload.github.com/intellectronica/ruler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intellectronica%2Fruler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","aider","claude-code","codex","cursor","github-copilot","vibe-coding","windsurf"],"created_at":"2025-06-10T11:01:06.231Z","updated_at":"2026-01-12T10:04:06.379Z","avatar_url":"https://github.com/intellectronica.png","language":"TypeScript","readme":"# Ruler: Centralise Your AI Coding Assistant Instructions\n\n\u003ctable style=\"width:100%\"\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"vertical-align: top;\"\u003e\n      \u003cp\u003e\n        \u003ca href=\"https://github.com/intellectronica/ruler/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/intellectronica/ruler/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n        \u003ca href=\"https://www.npmjs.com/package/@intellectronica/ruler\"\u003e\u003cimg src=\"https://badge.fury.io/js/%40intellectronica%2Fruler.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\n      \u003c/p\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003cstrong\u003eGitHub\u003c/strong\u003e: \u003ca href=\"https://github.com/intellectronica/ruler\"\u003eintellectronica/ruler\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003cstrong\u003eNPM\u003c/strong\u003e: \u003ca href=\"https://www.npmjs.com/package/@intellectronica/ruler\"\u003e@intellectronica/ruler\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \u003chr /\u003e\n      \u003cp\u003e\n        \u003cem\u003eAnimation by \u003ca href=\"https://isaacflath.com/\"\u003eIsaac Flath\u003c/a\u003e of \u003cstrong\u003e\u003ca href=\"https://elite-ai-assisted-coding.dev/\"\u003eElite AI-Assisted Coding\u003c/a\u003e\u003c/strong\u003e\u003c/em\u003e ➡︎\n      \u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"vertical-align: top; width:33%;\"\u003e\n      \u003cimg src=\"img/ruler-short.gif\" alt=\"Ruler demo\" style=\"width:300px; height:auto; display:block;\" /\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n\u003e **Beta Research Preview**\n\u003e\n\u003e - Please test this version carefully in your environment\n\u003e - Report issues at https://github.com/intellectronica/ruler/issues\n\n## Why Ruler?\n\nManaging 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:\n\n- **Inconsistent guidance** across AI tools\n- **Duplicated effort** maintaining multiple config files\n- **Context drift** as project requirements evolve\n- **Onboarding friction** for new AI tools\n- **Complex project structures** requiring context-specific instructions for different components\n\nRuler 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.\n\n## Core Features\n\n- **Centralised Rule Management**: Store all AI instructions in a dedicated `.ruler/` directory using Markdown files\n- **Nested Rule Loading**: Support complex project structures with multiple `.ruler/` directories for context-specific instructions\n- **Automatic Distribution**: Ruler applies these rules to configuration files of supported AI agents\n- **Targeted Agent Configuration**: Fine-tune which agents are affected and their specific output paths via `ruler.toml`\n- **MCP Server Propagation**: Manage and distribute Model Context Protocol (MCP) server settings\n- **`.gitignore` Automation**: Keeps generated agent config files out of version control automatically\n- **Simple CLI**: Easy-to-use commands for initialising and applying configurations\n\n## Supported AI Agents\n\n| Agent            | Rules File(s)                                    | MCP Configuration / Notes                        |\n| ---------------- | ------------------------------------------------ | ------------------------------------------------ |\n| AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)  |\n| GitHub Copilot   | `AGENTS.md`                                      | `.vscode/mcp.json`                               |\n| Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                      |\n| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                             |\n| Pi Coding Agent  | `AGENTS.md`                                      | -                                                |\n| Jules            | `AGENTS.md`                                      | -                                                |\n| Cursor           | `AGENTS.md`                                      | `.cursor/mcp.json`                               |\n| Windsurf         | `AGENTS.md`                                      | `.windsurf/mcp_config.json`                      |\n| Cline            | `.clinerules`                                    | -                                                |\n| Crush            | `CRUSH.md`                                       | `.crush.json`                                    |\n| Amp              | `AGENTS.md`                                      | -                                                |\n| Antigravity      | `.agent/rules/ruler.md`                          | -                                                |\n| Amazon Q CLI     | `.amazonq/rules/ruler_q_rules.md`                | `.amazonq/mcp.json`                              |\n| Aider            | `AGENTS.md`, `.aider.conf.yml`                   | `.mcp.json`                                      |\n| Firebase Studio  | `.idx/airules.md`                                | `.idx/mcp.json`                                  |\n| Open Hands       | `.openhands/microagents/repo.md`                 | `config.toml`                                    |\n| Gemini CLI       | `AGENTS.md`                                      | `.gemini/settings.json`                          |\n| Junie            | `.junie/guidelines.md`                           | -                                                |\n| AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | -                                                |\n| Kilo Code        | `.kilocode/rules/ruler_kilocode_instructions.md` | `.kilocode/mcp.json`                             |\n| OpenCode         | `AGENTS.md`                                      | `opencode.json`                                  |\n| Goose            | `.goosehints`                                    | -                                                |\n| Qwen Code        | `AGENTS.md`                                      | `.qwen/settings.json`                            |\n| RooCode          | `AGENTS.md`                                      | `.roo/mcp.json`                                  |\n| Zed              | `AGENTS.md`                                      | `.zed/settings.json` (project root, never $HOME) |\n| Trae AI          | `.trae/rules/project_rules.md`                   | -                                                |\n| Warp             | `WARP.md`                                        | -                                                |\n| Kiro             | `.kiro/steering/ruler_kiro_instructions.md`      | `.kiro/settings/mcp.json`                        |\n| Firebender       | `firebender.json`                                | `firebender.json` (rules and MCP in same file)   |\n| Mistral Vibe     | `AGENTS.md`                                      | `.vibe/config.toml`                              |\n\n## Getting Started\n\n### Installation\n\n**Global Installation (Recommended for CLI use):**\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\n**Using `npx` (for one-off commands):**\n\n```bash\nnpx @intellectronica/ruler apply\n```\n\n### Project Initialisation\n\n1. Navigate to your project's root directory\n2. Run `ruler init`\n3. This creates:\n\n- `.ruler/` directory\n- `.ruler/AGENTS.md`: The primary starter Markdown file for your rules\n- `.ruler/ruler.toml`: The main configuration file for Ruler (now contains sample MCP server sections; legacy `.ruler/mcp.json` no longer scaffolded)\n- (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.)\n\nAdditionally, you can create a global configuration to use when no local `.ruler/` directory is found:\n\n```bash\nruler init --global\n```\n\nThe global configuration will be created to `$XDG_CONFIG_HOME/ruler` (default: `~/.config/ruler`).\n\n## Core Concepts\n\n### The `.ruler/` Directory\n\nThis is your central hub for all AI agent instructions:\n\n- **Primary File Order \u0026 Precedence**:\n  1. A repository root `AGENTS.md` (outside `.ruler/`) if present (highest precedence, prepended)\n  2. `.ruler/AGENTS.md` (new default starter file)\n  3. Legacy `.ruler/instructions.md` (only if `.ruler/AGENTS.md` absent; no longer emits a deprecation warning)\n  4. Remaining discovered `.md` files under `.ruler/` (and subdirectories) in sorted order\n- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` or `$XDG_CONFIG_HOME/ruler` and concatenated in the order above\n- **Concatenation Marker**: Each file's content is prepended with `\u003c!-- Source: \u003crelative_path_to_md_file\u003e --\u003e` for traceability\n- **`ruler.toml`**: Master configuration for Ruler's behavior, agent selection, and output paths\n- **`mcp.json`**: Shared MCP server settings\n\nThis ordering lets you keep a short, high-impact root `AGENTS.md` (e.g. executive project summary) while housing detailed guidance inside `.ruler/`.\n\n### Nested Rule Loading\n\nRuler now supports **nested rule loading** with the `--nested` flag, enabling context-specific instructions for different parts of your project:\n\n```\nproject/\n├── .ruler/           # Global project rules\n│   ├── AGENTS.md\n│   └── coding_style.md\n├── src/\n│   └── .ruler/       # Component-specific rules\n│       └── api_guidelines.md\n├── tests/\n│   └── .ruler/       # Test-specific rules\n│       └── testing_conventions.md\n└── docs/\n    └── .ruler/       # Documentation rules\n        └── writing_style.md\n```\n\n**How it works:**\n\n- Discover all `.ruler/` directories in the project hierarchy\n- Load and concatenate rules from each directory in order\n- Decide whether nested mode is enabled using the following precedence:\n  1. `ruler apply --nested` (or `--no-nested`) takes top priority\n  2. `nested = true` in `ruler.toml`\n  3. Default to disabled when neither option is provided\n- 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.\n- 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.\n\n\u003e [!CAUTION]\n\u003e 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.\n\n**Perfect for:**\n\n- Monorepos with multiple services\n- Projects with distinct components (frontend/backend)\n- Teams needing different instructions for different areas\n- Complex codebases with varying standards\n\n### Best Practices for Rule Files\n\n**Granularity**: Break down complex instructions into focused `.md` files:\n\n- `coding_style.md`\n- `api_conventions.md`\n- `project_architecture.md`\n- `security_guidelines.md`\n\n**Example rule file (`.ruler/python_guidelines.md`):**\n\n```markdown\n# Python Project Guidelines\n\n## General Style\n\n- Follow PEP 8 for all Python code\n- Use type hints for all function signatures and complex variables\n- Keep functions short and focused on a single task\n\n## Error Handling\n\n- Use specific exception types rather than generic `Exception`\n- Log errors effectively with context\n\n## Security\n\n- Always validate and sanitize user input\n- Be mindful of potential injection vulnerabilities\n```\n\n## Usage: The `apply` Command\n\n### Primary Command\n\n```bash\nruler apply [options]\n```\n\nThe `apply` command looks for `.ruler/` in the current directory tree, reading the first match. If no such directory is found, it will look for a global configuration in `$XDG_CONFIG_HOME/ruler`.\n\n### Options\n\n| Option                         | Description                                                            |\n| ------------------------------ | ---------------------------------------------------------------------- |\n| `--project-root \u003cpath\u003e`        | Project root path (default: current directory).                        |\n| `--agents \u003cagent1,agent2,...\u003e` | Comma-separated agent names to target (see supported list below).      |\n| `--config \u003cpath\u003e`              | Custom `ruler.toml` path.                                              |\n| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true).             |\n| `--no-mcp`                     | Disable applying MCP server configurations.                            |\n| `--mcp-overwrite`              | Overwrite native MCP config instead of merging.                        |\n| `--gitignore`                  | Enable automatic .gitignore updates (default: true).                   |\n| `--no-gitignore`               | Disable automatic .gitignore updates.                                  |\n| `--nested`                     | Enable nested rule loading (default: inherit from config or disabled). |\n| `--no-nested`                  | Disable nested rule loading even if `nested = true` in config.         |\n| `--backup`                     | Toggle creation of `.bak` backup files (default: enabled).             |\n| `--dry-run`                    | Preview changes without writing files.                                 |\n| `--local-only`                 | Skip `$XDG_CONFIG_HOME` when looking for configuration.                |\n| `--verbose` / `-v`             | Display detailed output during execution.                              |\n\n### Common Examples\n\n**Apply rules to all configured agents:**\n\n```bash\nruler apply\n```\n\n**Apply rules only to GitHub Copilot and Claude:**\n\n```bash\nruler apply --agents copilot,claude\n```\n\n**Apply rules only to Firebase Studio:**\n\n```bash\nruler apply --agents firebase\n```\n\n**Apply rules only to Warp:**\n\n```bash\nruler apply --agents warp\n```\n\n**Apply rules only to Trae AI:**\n\n```bash\nruler apply --agents trae\n```\n\n**Apply rules only to RooCode:**\n\n```bash\nruler apply --agents roo\n```\n\n**Use a specific configuration file:**\n\n```bash\nruler apply --config ./team-configs/ruler.frontend.toml\n```\n\n**Apply rules with verbose output:**\n\n```bash\nruler apply --verbose\n```\n\n**Apply rules but skip MCP and .gitignore updates:**\n\n```bash\nruler apply --no-mcp --no-gitignore\n```\n\n## Usage: The `revert` Command\n\nThe `revert` command safely undoes all changes made by `ruler apply`, restoring your project to its pre-ruler state. It intelligently restores files from backups (`.bak` files) when available, or removes generated files that didn't exist before.\n\n### Why Revert is Needed\n\nWhen experimenting with different rule configurations or switching between projects, you may want to:\n\n- **Clean slate**: Remove all ruler-generated files to start fresh\n- **Restore originals**: Revert modified files back to their original state\n- **Selective cleanup**: Remove configurations for specific agents only\n- **Safe experimentation**: Try ruler without fear of permanent changes\n\n### Primary Command\n\n```bash\nruler revert [options]\n```\n\n### Options\n\n| Option                         | Description                                                                                                                                                                                                                                                                                         |\n| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--project-root \u003cpath\u003e`        | Path to your project's root (default: current directory)                                                                                                                                                                                                                                            |\n| `--agents \u003cagent1,agent2,...\u003e` | Comma-separated list of agent names to revert (agentsmd, aider, amazonqcli, amp, antigravity, augmentcode, claude, cline, codex, copilot, crush, cursor, firebase, firebender, gemini-cli, goose, jules, junie, kilocode, kiro, mistral, opencode, openhands, pi, qwen, roo, trae, warp, windsurf, zed) |\n| `--config \u003cpath\u003e`              | Path to a custom `ruler.toml` configuration file                                                                                                                                                                                                                                                    |\n| `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                                                                                                                                                                         |\n| `--dry-run`                    | Preview changes without actually reverting files                                                                                                                                                                                                                                                    |\n| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                                                                                                                                            |\n| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                                                                                                                                                                      |\n\n### Common Examples\n\n**Revert all ruler changes:**\n\n```bash\nruler revert\n```\n\n**Preview what would be reverted (dry-run):**\n\n```bash\nruler revert --dry-run\n```\n\n**Revert only specific agents:**\n\n```bash\nruler revert --agents claude,copilot\n```\n\n**Revert with detailed output:**\n\n```bash\nruler revert --verbose\n```\n\n**Keep backup files after reverting:**\n\n```bash\nruler revert --keep-backups\n```\n\n## Configuration (`ruler.toml`) in Detail\n\n### Location\n\nDefaults to `.ruler/ruler.toml` in the project root. Override with `--config` CLI option.\n\n### Complete Example\n\n```toml\n# Default agents to run when --agents is not specified\n# Uses case-insensitive substring matching\ndefault_agents = [\"copilot\", \"claude\", \"aider\"]\n\n# --- Global MCP Server Configuration ---\n[mcp]\n# Enable/disable MCP propagation globally (default: true)\nenabled = true\n# Global merge strategy: 'merge' or 'overwrite' (default: 'merge')\nmerge_strategy = \"merge\"\n\n# --- MCP Server Definitions ---\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/project\"]\n\n[mcp_servers.git]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-git\", \"--repository\", \".\"]\n\n[mcp_servers.remote_api]\nurl = \"https://api.example.com\"\n\n[mcp_servers.remote_api.headers]\nAuthorization = \"Bearer your-token\"\n\n# --- Global .gitignore Configuration ---\n[gitignore]\n# Enable/disable automatic .gitignore updates (default: true)\nenabled = true\n\n# --- Agent-Specific Configurations ---\n[agents.copilot]\nenabled = true\n\n[agents.claude]\nenabled = true\noutput_path = \"CLAUDE.md\"\n\n[agents.aider]\nenabled = true\noutput_path_instructions = \"AGENTS.md\"\noutput_path_config = \".aider.conf.yml\"\n\n# OpenAI Codex CLI agent and MCP config\n[agents.codex]\nenabled = true\noutput_path = \"AGENTS.md\"\noutput_path_config = \".codex/config.toml\"\n\n# Agent-specific MCP configuration for Codex CLI\n[agents.codex.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n[agents.firebase]\nenabled = true\noutput_path = \".idx/airules.md\"\n\n[agents.gemini-cli]\nenabled = true\n\n[agents.jules]\nenabled = true\n\n[agents.junie]\nenabled = true\noutput_path = \".junie/guidelines.md\"\n\n# Agent-specific MCP configuration\n[agents.cursor.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n# Disable specific agents\n[agents.windsurf]\nenabled = false\n\n[agents.kilocode]\nenabled = true\noutput_path = \".kilocode/rules/ruler_kilocode_instructions.md\"\n\n[agents.warp]\nenabled = true\noutput_path = \"WARP.md\"\n```\n\n### Configuration Precedence\n\n1. **CLI flags** (e.g., `--agents`, `--no-mcp`, `--mcp-overwrite`, `--no-gitignore`)\n2. **Settings in `ruler.toml`** (`default_agents`, specific agent settings, global sections)\n3. **Ruler's built-in defaults** (all agents enabled, standard output paths, MCP enabled with 'merge')\n\n## MCP (Model Context Protocol) Server Configuration\n\nMCP provides broader context to AI models through server configurations. Ruler can manage and distribute these settings across compatible agents.\n\n### TOML Configuration (Recommended)\n\nYou can now define MCP servers directly in `ruler.toml` using the `[mcp_servers.\u003cname\u003e]` syntax:\n\n```toml\n# Global MCP behavior\n[mcp]\nenabled = true\nmerge_strategy = \"merge\"  # or \"overwrite\"\n\n# Local (stdio) server\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/project\"]\n\n[mcp_servers.filesystem.env]\nAPI_KEY = \"your-api-key\"\n\n# Remote server\n[mcp_servers.search]\nurl = \"https://mcp.example.com\"\n\n[mcp_servers.search.headers]\nAuthorization = \"Bearer your-token\"\n\"X-API-Version\" = \"v1\"\n```\n\n### Legacy `.ruler/mcp.json` (Deprecated)\n\nFor backward compatibility, you can still use the JSON format; a warning is issued encouraging migration to TOML. The file is no longer created during `ruler init`.\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/path/to/project\"\n      ]\n    },\n    \"git\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-git\", \"--repository\", \".\"]\n    }\n  }\n}\n```\n\n### Configuration Precedence\n\nWhen both TOML and JSON configurations are present:\n\n1. **TOML servers take precedence** over JSON servers with the same name\n2. **Servers are merged** from both sources (unless using overwrite strategy)\n3. **Deprecation warning** is shown encouraging migration to TOML (warning shown once per run)\n\n### Server Types\n\n**Local/stdio servers** require a `command` field:\n\n```toml\n[mcp_servers.local_server]\ncommand = \"node\"\nargs = [\"server.js\"]\n\n[mcp_servers.local_server.env]\nDEBUG = \"1\"\n```\n\n**Remote servers** require a `url` field (headers optional; bearer Authorization token auto-extracted for OpenHands when possible):\n\n```toml\n[mcp_servers.remote_server]\nurl = \"https://api.example.com\"\n\n[mcp_servers.remote_server.headers]\nAuthorization = \"Bearer token\"\n```\n\nRuler uses this configuration with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.\n\n**Home Directory Safety:** Ruler never writes MCP configuration files outside your project root. Any historical references to user home directories (e.g. `~/.codeium/windsurf/mcp_config.json` or `~/.zed/settings.json`) have been removed; only project-local paths are targeted.\n\n**Note for OpenAI Codex CLI:** To apply the local Codex CLI MCP configuration, set the `CODEX_HOME` environment variable to your project’s `.codex` directory:\n\n```bash\nexport CODEX_HOME=\"$(pwd)/.codex\"\n```\n\n## Skills Support (Experimental)\n\n**⚠️ Experimental Feature**: Skills support is currently experimental and requires `uv` (the Python package manager) to be installed on your system for MCP-based agent integration (agents without native skills support).\n\nRuler can manage and propagate skills to supported AI agents. Skills are stored in `.ruler/skills/` and are automatically distributed to compatible agents when you run `ruler apply`.\n\n### How It Works\n\nSkills are specialized knowledge packages that extend AI agent capabilities with domain-specific expertise, workflows, or tool integrations. Ruler discovers skills in your `.ruler/skills/` directory and propagates them to compatible agents:\n\n- **Agents with native skills support**: Skills are copied directly to each agent's native skills directory:\n  - **Claude Code**: `.claude/skills/`\n  - **GitHub Copilot**: `.claude/skills/` (shared with Claude Code)\n  - **Kilo Code**: `.claude/skills/` (shared with Claude Code)\n  - **OpenAI Codex CLI**: `.codex/skills/`\n  - **OpenCode**: `.opencode/skill/`\n  - **Pi Coding Agent**: `.pi/skills/`\n  - **Goose**: `.agents/skills/`\n  - **Amp**: `.agents/skills/` (shared with Goose)\n  - **Mistral Vibe**: `.vibe/skills/`\n  - **Roo Code**: `.roo/skills/`\n  - **Gemini CLI**: `.gemini/skills/`\n  - **Cursor**: `.cursor/skills/`\n- **Other MCP-compatible agents**: Skills are copied to `.skillz/` and a Skillz MCP server is automatically configured via `uvx`\n\n### Skills Directory Structure\n\nSkills can be organized flat or nested:\n\n```\n.ruler/skills/\n├── my-skill/\n│   ├── SKILL.md           # Required: skill instructions/knowledge\n│   ├── helper.py          # Optional: additional resources (scripts)\n│   └── reference.md       # Optional: additional resources (docs)\n└── another-skill/\n    └── SKILL.md\n```\n\nEach skill must contain:\n\n- `SKILL.md` - Primary skill file with instructions or knowledge base\n\nSkills can optionally include additional resources like:\n\n- Markdown files with supplementary documentation\n- Python, JavaScript, or other scripts\n- Configuration files or data\n\n### Configuration\n\nSkills support is **enabled by default** but can be controlled via:\n\n**CLI flags:**\n\n```bash\n# Enable skills (default)\nruler apply --skills\n\n# Disable skills\nruler apply --no-skills\n```\n\n**Configuration in `ruler.toml`:**\n\n```toml\n[skills]\nenabled = true  # or false to disable\n```\n\n### Skillz MCP Server\n\nFor agents that support MCP but don't have native skills support, Ruler automatically:\n\n1. Copies skills to `.skillz/` directory\n2. Configures a Skillz MCP server in the agent's configuration\n3. Uses `uvx` to launch the server with the absolute path to `.skillz`\n\nAgents using native skills support (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Mistral Vibe, Roo Code, Gemini CLI, and Cursor) **do not** use the Skillz MCP server and instead use their own native skills directories.\n\nExample auto-generated MCP server configuration:\n\n```toml\n[mcp_servers.skillz]\ncommand = \"uvx\"\nargs = [\"skillz@latest\", \"/absolute/path/to/project/.skillz\"]\n```\n\n### `.gitignore` Integration\n\nWhen skills support is enabled and gitignore integration is active, Ruler automatically adds:\n\n- `.claude/skills/` (for Claude Code, GitHub Copilot, and Kilo Code)\n- `.codex/skills/` (for OpenAI Codex CLI)\n- `.opencode/skill/` (for OpenCode)\n- `.pi/skills/` (for Pi Coding Agent)\n- `.agents/skills/` (for Goose and Amp)\n- `.vibe/skills/` (for Mistral Vibe)\n- `.roo/skills/` (for Roo Code)\n- `.gemini/skills/` (for Gemini CLI)\n- `.cursor/skills/` (for Cursor)\n- `.skillz/` (for other MCP-based agents)\n\nto your `.gitignore` file within the managed Ruler block.\n\n### Requirements\n\n- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Mistral Vibe, Roo Code, Gemini CLI, Cursor): No additional requirements\n- **For other MCP agents**: `uv` must be installed and available in your PATH\n  ```bash\n  # Install uv if needed\n  curl -LsSf https://astral.sh/uv/install.sh | sh\n  ```\n\n### Validation\n\nRuler validates discovered skills and issues warnings for:\n\n- Missing required file (`SKILL.md`)\n- Invalid directory structures (directories without `SKILL.md` and no sub-skills)\n\nWarnings don't prevent propagation but help identify potential issues.\n\n### Dry-Run Mode\n\nTest skills propagation without making changes:\n\n```bash\nruler apply --dry-run\n```\n\nThis shows which skills would be copied and which MCP servers would be configured.\n\n### Example Workflow\n\n```bash\n# 1. Add a skill to your project\nmkdir -p .ruler/skills/my-skill\ncat \u003e .ruler/skills/my-skill/SKILL.md \u003c\u003c 'EOF'\n# My Custom Skill\n\nThis skill provides specialized knowledge for...\n\n## Usage\n\nWhen working on this project, always follow these guidelines:\n- Use TypeScript for all new code\n- Write tests for all features\n- Follow the existing code style\nEOF\n\n# 2. Apply to all agents (skills enabled by default)\nruler apply\n\n# 3. Skills are now available to compatible agents:\n#    - Claude Code, GitHub Copilot \u0026 Kilo Code: .claude/skills/my-skill/\n#    - OpenAI Codex CLI: .codex/skills/my-skill/\n#    - OpenCode: .opencode/skill/my-skill/\n#    - Pi Coding Agent: .pi/skills/my-skill/\n#    - Goose \u0026 Amp: .agents/skills/my-skill/\n#    - Mistral Vibe: .vibe/skills/my-skill/\n#    - Roo Code: .roo/skills/my-skill/\n#    - Gemini CLI: .gemini/skills/my-skill/\n#    - Cursor: .cursor/skills/my-skill/\n#    - Other MCP agents: .skillz/my-skill/ + Skillz MCP server configured\n```\n\n## `.gitignore` Integration\n\nRuler automatically manages your `.gitignore` file to keep generated agent configuration files out of version control.\n\n### How it Works\n\n- Creates or updates `.gitignore` in your project root\n- Adds paths to a managed block marked with `# START Ruler Generated Files` and `# END Ruler Generated Files`\n- Preserves existing content outside this block\n- Sorts paths alphabetically and uses relative POSIX-style paths\n\n### Example `.gitignore` Section (sample - actual list depends on enabled agents)\n\n```gitignore\n# Your existing rules\nnode_modules/\n*.log\n\n# START Ruler Generated Files\n.aider.conf.yml\n.clinerules\nAGENTS.md\nCLAUDE.md\n# END Ruler Generated Files\n\ndist/\n```\n\n### Control Options\n\n- **CLI flags**: `--gitignore` or `--no-gitignore`\n- **Configuration**: `[gitignore].enabled` in `ruler.toml`\n- **Default**: enabled\n\n## Practical Usage Scenarios\n\n### Scenario 1: Getting Started Quickly\n\n```bash\n# Initialize Ruler in your project\ncd your-project\nruler init\n\n# Edit the generated files\n# - Add your coding guidelines to .ruler/AGENTS.md (or keep adding additional .md files)\n# - Customize .ruler/ruler.toml if needed\n\n# Apply rules to all AI agents\nruler apply\n```\n\n### Scenario 2: Complex Projects with Nested Rules\n\nFor large projects with multiple components or services, enable nested rule loading so each directory keeps its own rules and MCP bundle:\n\n```bash\n# Set up nested .ruler directories\nmkdir -p src/.ruler tests/.ruler docs/.ruler\n\n# Add component-specific instructions\necho \"# API Design Guidelines\" \u003e src/.ruler/api_rules.md\necho \"# Testing Best Practices\" \u003e tests/.ruler/test_rules.md\necho \"# Documentation Standards\" \u003e docs/.ruler/docs_rules.md\n```\n\n```toml\n# .ruler/ruler.toml\nnested = true\n```\n\n```bash\n# The CLI inherits nested mode from ruler.toml\nruler apply --verbose\n\n# Override from the CLI at any time\nruler apply --no-nested\n```\n\nThis creates context-specific instructions for different parts of your project while maintaining global rules in the root `.ruler/` directory. Nested runs automatically keep every nested config enabled even if a child tries to disable it.\n\n\u003e [!NOTE]\n\u003e The CLI prints \"Nested mode is experimental and may change in future releases.\" the first time nested processing runs. Expect refinements in future versions.\n\n### Scenario 3: Team Standardization\n\n1. Create `.ruler/coding_standards.md`, `.ruler/api_usage.md`\n2. Commit the `.ruler` directory to your repository\n3. Team members pull changes and run `ruler apply` to update their local AI agent configurations\n\n### Scenario 4: Project-Specific Context for AI\n\n1. Detail your project's architecture in `.ruler/project_overview.md`\n2. Describe primary data structures in `.ruler/data_models.md`\n3. Run `ruler apply` to help AI tools provide more relevant suggestions\n\n### Integration with NPM Scripts\n\n```json\n{\n  \"scripts\": {\n    \"ruler:apply\": \"ruler apply\",\n    \"dev\": \"npm run ruler:apply \u0026\u0026 your_dev_command\",\n    \"precommit\": \"npm run ruler:apply\"\n  }\n}\n```\n\n### Integration with GitHub Actions\n\n```yaml\n# .github/workflows/ruler-check.yml\nname: Check Ruler Configuration\non:\n  pull_request:\n    paths: ['.ruler/**']\n\njobs:\n  check-ruler:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '18'\n          cache: 'npm'\n\n      - name: Install Ruler\n        run: npm install -g @intellectronica/ruler\n\n      - name: Apply Ruler configuration\n        run: ruler apply --no-gitignore\n\n      - name: Check for uncommitted changes\n        run: |\n          if [[ -n $(git status --porcelain) ]]; then\n            echo \"::error::Ruler configuration is out of sync!\"\n            echo \"Please run 'ruler apply' locally and commit the changes.\"\n            exit 1\n          fi\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Cannot find module\" errors:**\n\n- Ensure Ruler is installed globally: `npm install -g @intellectronica/ruler`\n- Or use `npx @intellectronica/ruler`\n\n**Permission denied errors:**\n\n- On Unix systems, you may need `sudo` for global installation\n\n**Agent files not updating:**\n\n- Check if the agent is enabled in `ruler.toml`\n- Verify agent isn't excluded by `--agents` flag\n- Use `--verbose` to see detailed execution logs\n\n**Configuration validation errors:**\n\n- Ruler now validates `ruler.toml` format and will show specific error details\n- Check that all configuration values match the expected types and formats\n\n### Debug Mode\n\nUse `--verbose` flag to see detailed execution logs:\n\n```bash\nruler apply --verbose\n```\n\nThis shows:\n\n- Configuration loading details\n- Agent selection logic\n- File processing information\n- MCP configuration steps\n\n## FAQ\n\n**Q: Can I use different rules for different agents?**\nA: Currently, all agents receive the same concatenated rules. For agent-specific instructions, include sections in your rule files like \"## GitHub Copilot Specific\" or \"## Aider Configuration\".\n\n**Q: How do I set up different instructions for different parts of my project?**\nA: Enable nested mode either by setting `nested = true` in `ruler.toml` or by passing `ruler apply --nested`. The CLI inherits the config setting by default, but `--no-nested` always wins if you need to opt out for a run. Nested mode keeps loading rules (and MCP settings) from every `.ruler/` directory in the hierarchy, forces child configs to remain nested, and logs \"Nested mode is experimental and may change in future releases.\" if any nested processing occurs.\n\n**Q: How do I temporarily disable Ruler for an agent?**\nA: Set `enabled = false` in `ruler.toml` under `[agents.agentname]`, or use `--agents` flag to specify only the agents you want.\n\n**Q: What happens to my existing agent configuration files?**\nA: Ruler creates backups with `.bak` extension before overwriting any existing files.\n\n**Q: Can I run Ruler in CI/CD pipelines?**\nA: Yes! Use `ruler apply --no-gitignore` in CI to avoid modifying `.gitignore`. See the GitHub Actions example above.\n\n**Q: How do I migrate from older versions using `instructions.md`?**\nA: Simply rename `.ruler/instructions.md` to `.ruler/AGENTS.md` (recommended). If you keep the legacy file and omit `AGENTS.md`, Ruler will still use it (without emitting the old deprecation warning). Having both causes `AGENTS.md` to take precedence; the legacy file is still concatenated afterward.\n\n**Q: How does OpenHands MCP propagation classify servers?**\nA: Local stdio servers become `stdio_servers`. Remote URLs containing `/sse` are classified as `sse_servers`; others become `shttp_servers`. Bearer tokens in an `Authorization` header are extracted into `api_key` where possible.\n\n**Q: Where is Zed configuration written now?**\nA: Ruler writes a `settings.json` in the project root (not the user home dir) and transforms MCP server definitions to Zed's `context_servers` format including `source: \"custom\"`.\n\n**Q: What changed about MCP initialization?**\nA: `ruler init` now only adds example MCP server sections to `ruler.toml` instead of creating `.ruler/mcp.json`. The JSON file is still consumed if present, but TOML servers win on name conflicts.\n\n**Q: Is Kiro supported?**\nA: Yes. Kiro receives concatenated rules at `.kiro/steering/ruler_kiro_instructions.md`.\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/intellectronica/ruler.git\ncd ruler\nnpm install\nnpm run build\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n### Code Quality\n\n```bash\n# Run linting\nnpm run lint\n\n# Run formatting\nnpm run format\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\nFor bugs and feature requests, please [open an issue](https://github.com/intellectronica/ruler/issues).\n\n## License\n\nMIT\n\n---\n\n© Eleanor Berger  \n[ai.intellectronica.net](https://ai.intellectronica.net/)\n","funding_links":[],"categories":["TypeScript","HarmonyOS","Learning Resources","AI Agent Frameworks \u0026 SDKs","Configuration \u0026 Rules","Tools"],"sub_categories":["Windows Manager","Copilot Extensions \u0026 Alternatives","Multi-Agent Collaboration Systems","Development Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintellectronica%2Fruler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintellectronica%2Fruler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintellectronica%2Fruler/lists"}