Ruler: One .ruler Directory for Every AI Coding Agent

The duplication problem Ruler was built to remove

If your team uses more than one AI coding tool, the same project conventions end up written several times. Claude Code reads CLAUDE.md, Cline reads .clinerules, Crush reads CRUSH.md, Amazon Q CLI reads .amazonq/rules/ruler_q_rules.md, and a long list of others read AGENTS.md. The README frames the cost plainly: inconsistent guidance across tools, duplicated effort maintaining multiple config files, context drift as requirements change, and onboarding friction each time a new agent appears. Ruler's answer is a single source of truth in a .ruler/ directory of Markdown files, from which the CLI writes the per-agent files. The audience is teams, not solo users: the pain only exists once two or more agents are in play, or once a repository is large enough that different components need different instructions. The README also mentions nested rule loading for complex project structures, which is the feature aimed at monorepos rather than single-package projects.

How the .ruler directory turns into per-agent config files

The mechanism is generation, not a runtime shim. You author Markdown under .ruler/, Ruler reads it, and it writes the files listed in its support table. Some targets are plain Markdown (AGENTS.md, CLAUDE.md, CRUSH.md); others are tool-specific paths such as .agent/rules/ruler.md for Antigravity, .idx/airules.md for Firebase Studio, or .openhands/microagents/repo.md for Open Hands. A pseudo-agent named AGENTS.md exists purely to ensure a root AGENTS.md is present. Beyond rules, Ruler propagates MCP server settings into files like .mcp.json, .cursor/mcp.json, .codex/config.toml and .gemini/settings.json, and it can place skills and subagents into directories such as .claude/skills/, .claude/agents/, .github/agents/ and .codex/agents/. Because output paths differ per tool, ruler.toml is where you narrow which agents are affected and where their files land. The repository layout matches that design: a .ruler/ directory at the root, a src/ tree, and separate tests/ and test-qa/ directories, with Jest configured for unit and integration runs.

Installing Ruler and generating your first agent files

Ruler publishes to npm as @intellectronica/ruler, and the README points to that package as the distribution channel. The package exposes a CLI whose entry point is dist/cli/index.js, built by tsc and marked executable in a postbuild step. Install it globally so the command is on your PATH:

npm install -g @intellectronica/ruler

Then initialise the project. The README describes a simple CLI for initialising and applying configurations, so the first command creates the .ruler/ directory and the follow-up applies it to your agents:

ruler init
ruler apply

After init, put your instructions in Markdown files under .ruler/. After apply, expect generated files to appear at the paths in the support table, for example CLAUDE.md, .clinerules or .cursor/mcp.json depending on which agents you enabled. Ruler also automates .gitignore so the generated files stay out of version control. If you would rather not install globally, the package can be consumed as a library: package.json declares dist/lib.js as main and dist/lib.d.ts as types, so the same logic is importable from TypeScript. The README does not spell out the exact flags for either command, so check the CLI help in your installed version rather than assuming flag names.

Where Ruler stops being the right tool

The README opens with a Beta Research Preview notice and asks readers to test the version carefully in their own environment and report issues on GitHub. That is a real constraint, not a formality: a tool whose job is writing config files into your repository is a tool that can write the wrong thing. Nothing in the README documents a rollback command, a dry-run mode, or a way to preview what apply will change before it changes it, so if a generated file is overwritten with content you did not want, recovery depends on your own version control. The .gitignore automation compounds this. Keeping generated files out of version control is the correct default for a generator, but it also means the diff you would normally review is invisible, and anyone who clones the repository has to run the CLI before their agent sees any rules at all. There is also a lossy-translation risk in the other direction: a single rules document is written into formats as different as Markdown, YAML (Aider's .aider.conf.yml) and TOML (Open Hands' config.toml, Codex's .codex/config.toml), and the README does not describe how content that does not map cleanly is handled. If you use exactly one agent, Ruler adds a directory and a build step to solve a problem you do not have.

Ruler against hand-maintained AGENTS.md files

The obvious alternative is not another tool but the manual approach: keep one AGENTS.md and copy or symlink it to CLAUDE.md, CRUSH.md and the rest. The difference is in what happens when the set changes. With manual copies, adding a new agent means remembering that it exists and where it reads from; with Ruler, the target list is encoded in the tool and in ruler.toml, so support for a new agent arrives as a release rather than as a task on someone's list. The manual approach also handles MCP configuration poorly, because .mcp.json, .cursor/mcp.json, .windsurf/mcp_config.json and .codex/config.toml are different files with different shapes, and Ruler's stated purpose includes propagating MCP server settings to all of them. The trade-off runs the other way too: a hand-written CLAUDE.md can say things a shared rules file cannot, and a symlink never rewrites your files. Ruler is the better fit when the number of agents is growing and the rules are genuinely shared; manual files are the better fit when each agent needs bespoke instructions that diverge on purpose.

Maintenance cost, release cadence and the MIT licence

The repository is not archived, and the last push was on 2026-09-09, so it is being worked on. Release tags tell a similar story: v0.3.42 on 2026-05-30, v0.3.43 on 2026-06-20, v0.3.44 on 2026-06-30. The version numbers stay in 0.3.x, which is consistent with the beta preview notice in the README. For an adopter, that cadence means two costs. First, agent vendors change their config formats, and Ruler's value depends on tracking those changes, so you are subscribing to a moving target; pinning the version you install is the practical response. Second, the project is TypeScript with a build step (npm run build runs tsc after cleaning dist/), so if you consume it as a library rather than a CLI you inherit that toolchain. The licence is MIT, which permits commercial use and modification; the LICENSE file is present at the repository root. That is a permissive arrangement, but it says nothing about whether the project will keep adding agents, and nothing here should be read as legal advice about your own distribution obligations.

Editorial conclusion

Adopt Ruler if you already run two or more of the agents in its support table and you are willing to keep the generated files out of version control, because that is exactly the duplication it removes. Skip it if you use a single agent, or if your instructions live somewhere the tool cannot read, such as a hosted rules UI. Before rolling it out to a team, check three things in your own checkout: that the .gitignore automation covers every path your agents read, that the same AGENTS.md content is acceptable to each tool you enable, and how you would recover if a write goes wrong, since the README does not document rollback. Then pin the version you install and treat the .ruler/ directory as the artifact under review.

Frequently asked questions

Official sources

1. intellectronica/ruler on GitHub
2. License: MIT
3. Project website
4. README
5. Releases