Rulesync: one source of rules for Claude Code, Codex and Cursor

The short answer

Rulesync is a CLI that keeps a repository's rules in a single directory, .rulesync/, and generates from it the native file each AI agent reads. It is for anyone who runs more than one agent on the same project and is tired of keeping CLAUDE.md, AGENTS.md and .cursor/rules saying different things. The promise stated in the official documentation is "Author rules once, generate everywhere", and the generated files keep working even without rulesync installed. The turning point is conceptual: once you adopt it, CLAUDE.md stops being a place where you write and becomes build output, just like a compiled file. That solves the drift and creates a new risk, which is running generate over hand-written rules. The safe path goes through importing what already exists before generating anything.

1. The problem is not having many agents, it is having many sources

People who deliver systems or stores to clients rarely use a single agent. Claude Code in the terminal, Codex CLI in another tab, Cursor to review the diff, OpenCode on a server. Each one reads a different file by default.

Claude Code loads ./CLAUDE.md or ./.claude/CLAUDE.md as project instructions. Cursor reads .cursor/rules in .mdc files, and a .md dropped into that folder is ignored by the rules system, because it has no frontmatter to declare description, globs and alwaysApply. OpenCode reads AGENTS.md at the root and accepts extra files listed in the instructions field of opencode.json. Codex keeps configuration in ~/.codex/config.toml and accepts a per-project override in .codex/config.toml, loaded only in a project marked as trusted.

Four places, four formats. In practice: the stack standard is in CLAUDE.md, the branch convention is in .cursor/rules, the deploy step is in AGENTS.md and the folder nobody may touch is nowhere. When an agent works with half the context, the client's code pays the price.

AGENTS.md reduced part of the confusion: it is an open format, used by more than 60,000 open source projects, and its precedence is simple, the file closest to the edited file wins. But it does not cover .cursor/rules or MCP configuration, hooks and permissions.

2. What rulesync does (and what it is not)

Rulesync reverses the direction: you write in .rulesync/, run a command and it writes each tool's native file. The official README describes a Node.js CLI that generates configuration for several AI tools from unified rule files, covering rules, commands, MCP, subagents and skills. MIT license.

Three things it is not:

• It is not MCP. MCP is the protocol that connects the agent to an external tool, and it already has its own article: MCP in Claude Code and Cursor. Rulesync only writes each tool's MCP configuration file from a single source.
• It is not a runtime. It runs, writes files and exits.
• It is not a guarantee of behavior. What it syncs is context text. Section 8 deals with that.

The advantage shows up the day you change the commit convention: instead of editing four files and forgetting one, you edit one in .rulesync/rules/ and run generate.

3. Install, and run import before any generate

The official documentation lists three routes: global npm, a Homebrew tap or a single binary. npm is the most direct.

npm install -g rulesync
rulesync --version

The Homebrew tap lives inside the repository itself and has no homebrew- prefix, so it requires the two-argument form brew tap <nome> <url>; the shortcut without tapping first does not work. On npm, the package carries a provenance attestation, verifiable with npm audit signatures.

Now the part that saves the repository. If the project already has hand-written CLAUDE.md and .cursorrules, do not run rulesync generate first. generate writes the native files from .rulesync/, and with an empty .rulesync/ what was written by hand may be overwritten. Import first:

rulesync init
rulesync import --targets claudecode
rulesync import --targets cursor

init creates .rulesync/ with sample files and rulesync.jsonc, and the documentation says existing files are never overwritten by it. The generated rulesync.jsonc already comes with targets set to codexcli, claudecode and opencode. import does the reverse of generate: it reads the existing CLAUDE.md, .cursorrules or .github/copilot-instructions.md and writes the content into .rulesync/.

After the import, check what came in before anything else:

git status
git diff --stat

If the import brought in less than you expected, complete it by hand in .rulesync/rules/ before generating.

4. The first rule: Markdown with frontmatter

A rulesync rule is a Markdown file in .rulesync/rules/, with YAML frontmatter. Four keys matter at the start: root, targets, description and globs. The root rule (root: true) becomes each tool's main file; the others become modular files in the place each tool expects.

---
root: true
targets: ["*"]
description: "Convenções do repositório"
globs: ["**/*"]
---

Below the frontmatter goes the body, in plain Markdown. Put in what you would repeat to a new developer on day one:

• Allowed stack and what is frozen (the framework version, the package manager, whether it is pnpm and not npm).
• Commit and branch conventions, written as examples and not as adjectives.
• Forbidden folders: build, vendor, files generated by another process.
• The deploy step and the verification command that runs before it.

The writing advice is consistent across the documentation: specific instructions work better than vague ones. Claude Code recommends fewer than 200 lines per CLAUDE.md, because a long file consumes context and reduces adherence. Cursor recommends keeping a rule under 500 lines and splitting a large rule into composable rules.

For a rule that only applies to part of the code, use globs. A rule with globs: ["src/api/**/*.ts"] is translated by each target into the mechanism it has: paths in Claude Code, globs in Cursor's .mdc, its own frontmatter in others.

The Cursor detail that breaks silently

In Cursor, alwaysApply: true and globs together are a semantic conflict: the official documentation says globs are ignored when the flag is on, and some versions classify the rule by the glob instead of always applying it. Rulesync handles this in translation, but know the behavior: it is a common cause of "the rule is there and the agent ignores it".

5. Generate for several targets at once

The command is generate, and what decides where it writes is --targets. The value is literal: getting the name wrong breaks the run. These are the values checked in the official reference on the day of reading.

Source: Rulesync, Supported Tools and File Formats pages, read on 2026-09-22. The full list exceeds 40 tools and changes often: check the value in the reference before hardcoding it in a script.

rulesync generate --targets claudecode,codexcli,cursor --features rules
rulesync generate --targets "*" --features "*"

The first line generates only the rules, for the three targets. The second generates everything for all configured targets. Start with the first. --features accepts rules, commands, subagents, skills, mcp, hooks, permissions and checks: turn them on one at a time, instead of discovering in the diff that permissions rewrote a hand-tuned .codex/config.toml.

Before writing any file, there is a rehearsal:

rulesync generate --dry-run --targets claudecode --features rules
rulesync generate --check --targets "*" --features "*"

--dry-run shows what would change without touching anything. --check does the same and exits with code 1 when the files are not up to date, which is how you use this in CI.

Target order matters more than it seems

Several tools read the same AGENTS.md: Codex CLI, OpenCode, Antigravity CLI, Grok CLI and Warp, among others. In a generate with several targets, more than one writes to the same path, each with its own semantics. Rulesync only sweeps orphans after all targets have written, so that one does not delete another's freshly written file. Even so: after generating, open AGENTS.md and read it. Do not assume.

6. Check in git diff, and decide whether the generated files go into the repository

After the first generate, the check that counts is the diff.

git diff --stat
git diff CLAUDE.md AGENTS.md
git diff .cursor/rules/

Look for three things: content that disappeared (a paragraph of hand-written CLAUDE.md that was not imported), duplicated content (the same instruction coming from AGENTS.md and from the root rule) and unexpected files, such as a .codex/config.toml that appeared because --features "*" turned on permissions.

Then comes the versioning decision, and it is binary.

Versioning the generated files is the path for teams. Whoever clones gets working rules without installing anything, which matches the documentation's promise. The cost is a noisier diff in every pull request and the obligation to run rulesync generate --check in CI so the generated files do not go stale silently.

Not versioning keeps the repository clean: only .rulesync/ goes into git and generate becomes a setup step. There is a ready-made command:

rulesync gitignore --targets claudecode,cursor

The cost is that whoever clones and does not run the setup works with no rules at all. A documented caveat: shared files such as opencode.json, .claude/settings.json, .codex/config.toml and .vscode/settings.json are deliberately left out of .gitignore, because you also write your own things in them.

For a client project, versioning tends to be the right choice: the repository has to work in the hands of whoever picks it up next, and whoever picks it up next does not read the setup documentation.

7. Update the tool without getting a scare

The current version when the page was read, on 2026-09-22, is 17.0.0, published on 2026-09-21. It brings a breaking change specific to Codex CLI: edit and write rules marked as ask or deny now generate read instead of deny. Codex has no per-path write-approval state, so the two actions that are not allow preserve read without write, with a warning. The release notes ask you to review the regenerated .codex/config.toml if you depended on the old output.

That sums up how it operates: the tool moves fast, with almost daily releases, and tracks what each agent changes on its own side. Two practices cover the risk: pin the version in the project instead of always installing the latest, and run rulesync generate --dry-run after any update.

8. The honest limit: rules align context, they do not force the model

This is the part almost no tutorial mentions, and that the tools' official documentation states plainly.

Claude Code is direct: memory instructions are treated as context, not as enforced configuration, and the content of CLAUDE.md is delivered as a user message after the system prompt, with no guarantee of strict compliance, especially when the instruction is vague or conflicts with another. The page's own recommendation, for what must always hold, is to use a PreToolUse hook, which runs regardless of what the model decides. Cursor makes the equivalent caveat when talking about team rules: AI guidance should not be the only security control.

The operational conclusion splits the work into two layers:

• Context layer: naming conventions, style, architecture, where things live. This lives in rules, and rulesync solves the duplication.
• Enforcement layer: what must never happen. This lives in hooks, in permissions (permissions.deny in Claude Code, sandbox_mode and approval policy in Codex), in tests and in CI rules.

If the instruction is "do not deploy without running the tests", it is not a file rule, it is a hook or a pipeline step. If it is "new endpoints go in src/api/handlers/", then yes, it is a rule, and it gains from living in a single place. Rulesync solves drift between sources. It does not solve, nor promise to solve, model obedience.

Frequently asked questions

Do I need to replace my CLAUDE.md with something else?

No. It still exists and is still read by Claude Code. What changes is who writes to it: you edit .rulesync/rules/ and generate rewrites CLAUDE.md. If someone on the team edits CLAUDE.md directly, the edit disappears on the next generate, so a comment at the top saying it is generated is worth adding.

Can I use it with just one tool?

Yes, and it makes sense as a transition. Running only with --targets claudecode already helps keep a large rule set organized in separate files. But if you use a single agent, the gain is small: the tool was built for several targets.

What about the rules that have been in .cursor/rules for months?

Run rulesync import --targets cursor before the first generate, check in git diff what went into .rulesync/ and only then generate. If the import does not bring everything, complete it by hand first.

Does this replace configuring MCP in each tool?

Partly. With the mcp feature on, it writes each tool's MCP configuration from a single source. What it does not do is the laborious part: choosing the server, handling credentials and diagnosing a server that will not start. That is the subject of MCP in Claude Code and Cursor.

Is it worth it on a VPS where the agent runs alone?

Even more so, because there nobody corrects the agent on the spot. But a file rule is still context: without supervision, what protects you is permissions and hooks, not text. On running an agent on a server: Claude Code 24/7 on a VPS.

Conclusion

Rulesync is a boring tool, and that is the compliment: it does nothing you could not do by hand, it just prevents four files from silently starting to disagree. The gain shows up in a repository that passes through more than one agent and more than one person, and the cost is low, since the tool is MIT and the output keeps working even without it installed. What really changes is the discipline: rules are written in .rulesync/, native files are artifacts, and git diff is the test after every generate. And what must always hold does not go into any rule, it goes into a hook, a permission or a test.

If what you need is the agent reading your ERP, your store or your database, that is a custom integration (MCP, webhook, queue). Describe the system and what you want to automate at oailton.dev/en/contato.