← cd ../blog

Ruler: write coding assistant rules once, use them everywhere

In one sentence

Ruler is a tool that you use with text commands. It keeps the instructions for coding assistants in one place. It helps you copy them automatically into each assistant’s files.

What it is and what it’s for

A coding assistant is an artificial intelligence (AI) program. It reads and changes the code of a project for you. It often also reads an instruction file inside the project. There it finds the rules to follow, for example the style of the code.

The problem starts when you use more than one assistant on the same project. Each one wants its own file. Claude Code, for example, reads CLAUDE.md in the main folder of the project. Without help, you have to copy the same rules by hand into several files.

Hand-made copies, however, drift apart over time. You change a rule in one file and forget the other. So the assistants follow different instructions, and the work becomes inconsistent.

Ruler solves this problem with a single source of rules. The rules live in the .ruler/ folder, in a Markdown file. Markdown is a simple text format, with titles and lists written with a few symbols. From there, Ruler distributes the rules to each assistant’s file.

Ruler can also update the .gitignore file. This is the list of files that git must not track, meaning it must not save them in the history. This way, generated files do not end up in your saved versions by mistake.

The project is still in testing, called beta. Use it with care, especially on important projects.

A concrete example

Imagine you are working on a project with Claude Code and GitHub Copilot. You want both to follow the same rules about code style. You write the rules once, then run a command that copies them into the two files. Here is the real result from the demo that we checked:

<!-- Source: .ruler/AGENTS.md -->
# AGENTS.md

The excerpt is in English: each line says what Ruler has just done.

Who it’s for (and who it isn’t)

Project card

What you need to try it, and what you DON’T need

You need a terminal, meaning the program where you write text commands one at a time. You need git, to download the project. You need Node.js with its package manager npm: the required version is written in the package.json file of the project, which you will find after the download.

Python is not needed for this path, even if you already know it.

You do not need any key. The path does not require accounts or API keys. An API key is a secret string that an online service uses to recognize you: you will not use any here.

Let’s try it step by step

Open the terminal in an empty folder, for example your personal folder. Then copy the commands one at a time, in the order they appear.

First step: installation. We download Ruler from GitHub, the online platform where the code lives. The commands select a precise version, meaning a commit, the one we tested. Then they install the dependencies and prepare the program with a build. Do not skip this step: without it, the demo cannot start.

git clone https://github.com/intellectronica/ruler ruler
cd ruler
git checkout b905f192d84e340d6c9723ff8eadfa6dbc9be8b6
npm ci
cd ..
mkdir ruler-demo
cd ruler-demo
Cloning into 'ruler'...



What you will see: The output is shortened by the program itself; here it appears in English. You only see the first lines: git announces the download, then npm warns that it is preparing the project with a build. The rest of the output is normal: they are progress messages and a final summary. A warning about possible vulnerabilities, meaning security holes in the packages, does not block the installation.

How to tell it went well: the final summary reports no errors, and the terminal is ready again for a new command.

Second step: the demo. We create a test folder and give it the starting rules with Ruler. Then we distribute those rules to Claude Code and GitHub Copilot. We do this to see the program at work on a test project, without touching your real files.

node ../ruler/dist/cli/index.js init
node ../ruler/dist/cli/index.js apply --local-only --agents claude,copilot
head -n 6 CLAUDE.md
[ruler] Created /work/ruler-demo/.ruler/AGENTS.md
[ruler] Created /work/ruler-demo/.ruler/ruler.toml


[ruler] Applying rules for GitHub Copilot...
[ruler] Applying rules for Claude Code...
[ruler] Updated .gitignore with 4 unique path(s) in the Ruler block.
Ruler apply completed successfully.




<!-- Source: .ruler/AGENTS.md -->

# AGENTS.md

What you will see: You will see lines that say it created .ruler/AGENTS.md and .ruler/ruler.toml, and that it applied the rules to the two assistants. A message about the .gitignore file also appears. The output is in English and shows the full path of the folder: on your computer it will be different.

How to tell it went well: the last line says that Ruler finished the job successfully, and no error messages appear.

What happened behind the scenes

The init command created the .ruler/ folder. Inside are two files: AGENTS.md, where you write the rules, and ruler.toml, the configuration file of Ruler. A configuration file contains the settings of a program.

The apply command read the rules from .ruler/. The --local-only option tells it to use only the files of the project. This way it ignores global configurations, meaning the ones saved for all the projects on your computer.

Then apply wrote one file for each chosen assistant. With --agents claude,copilot you named Claude Code and GitHub Copilot. Each file starts with a hidden comment, which shows which file the rule comes from. This comment helps keep track of where the rule came from.

Finally, apply updated .gitignore. It added the generated files in a block that Ruler manages by itself. This way, git does not treat them as files to save.

If you change a rule in .ruler/AGENTS.md and run apply again, the assistants’ files are updated. It is better to leave those files as they are and edit only .ruler/AGENTS.md.

Things to keep in mind

Where to start reading the code

The first file to open is src/cli/commands.ts. It lists the commands of the program, such as init and apply. You will immediately recognize the ones you used in the demo.

Glossary

A note on the test

The path was tested on Debian 12 in WSL2, meaning Linux running inside Windows. Native Windows and macOS were not tested.