agent-rules-sync

Write your AI agent rules once. Sync everywhere.

Manage rules for Claude, Cursor, Windsurf, Copilot, Gemini, Codex, and OpenCode from a single source of truth.

agent-rules/rules/*.md  -->  CLAUDE.md (or .claude/rules/)
                         -->  .cursorrules (or .cursor/rules/)
                         -->  .windsurfrules (or .windsurf/rules/)
                         -->  .github/copilot-instructions.md (or .github/instructions/)
                         -->  GEMINI.md
                         -->  AGENTS.md (Codex / OpenCode)

Quick Start

# Initialize in your project
npx agent-rules-sync init

# Edit your rules
# (opens agent-rules/rules/*.md)

# Generate all agent files
npx agent-rules-sync sync

How It Works

1. npx agent-rules-sync init sets up an agent-rules/ directory with a config file and rules folder
2. You write rules as markdown files in agent-rules/rules/
3. npx agent-rules-sync sync reads your rules and generates the correct file format for each AI agent

That's it. One source of truth, every agent stays in sync.

Supported Agents

| Agent | Default Output | Split Mode Output | Notes | |-------|---------------|-------------------|-------| | Claude Code | CLAUDE.md | .claude/rules/*.md | Append mode preserves manual content above marker. Split mode adds paths frontmatter from globs | | Cursor | .cursorrules | .cursor/rules/*.mdc | Split mode generates .mdc files with description, globs, alwaysApply frontmatter | | Windsurf | .windsurfrules | .windsurf/rules/*.md | 12KB size limit in single mode (auto-summarizes). Split mode has no limit | | GitHub Copilot | .github/copilot-instructions.md | .github/instructions/*.instructions.md | Split mode adds applyTo frontmatter from globs | | Gemini CLI | GEMINI.md | — | Single file only | | Codex CLI | AGENTS.md | — | 32KB size limit (auto-summarizes) | | OpenCode | AGENTS.md | — | Same format as Codex |

Note: Codex and OpenCode both default to AGENTS.md. If you enable both, set different output paths to avoid conflicts.

Writing Rules

Rules are markdown files with optional YAML frontmatter:

---
title: Coding Style
description: Core coding conventions
priority: 1
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
---

# Coding Style

## Functions

- Use arrow functions for all declarations
- Never use classes or enums

## Summary

Arrow functions only. No classes or enums.

Frontmatter Fields

| Field | Type | Default | Description | |-------|------|---------|-------------| | title | string | filename | Display name for the rule | | description | string | title | Short description | | priority | number | 999 | Sort order (lower = first) | | globs | string[] | [] | File patterns this rule applies to | | alwaysApply | boolean | auto | Whether the rule always applies. Defaults to true if no globs, false if globs are set |

How Frontmatter Maps to Each Agent

| Rule Field | Claude (paths) | Cursor (globs) | Copilot (applyTo) | Others | |-----------|-----------------|-------------------|---------------------|--------| | globs | paths: frontmatter | globs: frontmatter (YAML list) | applyTo: frontmatter (comma-separated) | Ignored | | alwaysApply | — | alwaysApply: frontmatter | applyTo: "**" when no globs | — | | description | — | description: frontmatter | — | — |

Summary Section

Add a ## Summary section to your rules. Agents with size limits (Windsurf at 12KB, Codex at 32KB) will use the summary when the full content is too large.

Single Mode vs Split Mode

Single mode (default): All rules are merged into one file.

agents:
  cursor:
    output: ".cursorrules"  # single file

Split mode: Each rule becomes its own file in a directory. Enable by adding a trailing / to the output path.

agents:
  cursor:
    output: ".cursor/rules/"  # split into .cursor/rules/*.mdc
  claude:
    output: ".claude/rules/"  # split into .claude/rules/*.md
  windsurf:
    output: ".windsurf/rules/"  # split into .windsurf/rules/*.md
  copilot:
    output: ".github/instructions/"  # split into .github/instructions/*.instructions.md

Split mode is useful when:

• You have many rules and want per-file scoping
• Your agent supports file-level glob/path matching (Claude, Cursor, Copilot)
• You want to avoid size limits (Windsurf)

Configuration

agent-rules/agent-rules.config.yaml:

agents:
  claude:
    enabled: true
    output: "CLAUDE.md"
    mode: append
    marker: "<!-- GENERATED BY agent-rules - DO NOT EDIT BELOW THIS LINE -->"

  cursor:
    enabled: true
    output: ".cursorrules"    # or ".cursor/rules/" for split mode

  windsurf:
    enabled: true
    output: ".windsurfrules"  # or ".windsurf/rules/" for split mode
    max_size: 12000           # bytes, auto-summarizes when exceeded (single mode only)

  copilot:
    enabled: false
    output: ".github/copilot-instructions.md"  # or ".github/instructions/" for split mode

  gemini:
    enabled: false
    output: "GEMINI.md"

  codex:
    enabled: false
    output: "AGENTS.md"

  opencode:
    enabled: false
    output: "AGENTS.md"

build:
  rules_dir: "./rules"
  clean: true                 # remove old generated files before sync
  preserve: []                # files to never overwrite

CLI Reference

agent-rules-sync init

Interactive setup wizard. Detects existing agent files and offers to import them.

agent-rules-sync sync

Build agent files from your rules.

agent-rules-sync sync              # build all enabled agents
agent-rules-sync sync --dry-run    # preview without writing files
agent-rules-sync sync --agent cursor  # build for one agent only
agent-rules-sync sync --verbose    # show detailed output
agent-rules-sync sync --config ./path/to/config.yaml

agent-rules-sync import

Import existing agent files into your rules directory.

agent-rules-sync import            # interactive file selection

Supports importing from:

• CLAUDE.md, .claude/rules/*.md
• .cursorrules, .cursor/rules/*.mdc
• .windsurfrules, .windsurf/rules/*.md
• .github/copilot-instructions.md, .github/instructions/*.instructions.md
• GEMINI.md
• AGENTS.md

CLAUDE.md Marker Mode

For CLAUDE.md, agent-rules uses a marker-based approach to preserve your manual content:

# My Project                    <-- your manual content (preserved)

Some notes you wrote by hand.

<!-- GENERATED BY agent-rules - DO NOT EDIT BELOW THIS LINE -->

# Coding Style                  <-- auto-generated from rules
...

Everything above the marker is untouched. Everything below is regenerated on each sync.

Size-Aware Generation

Some agents have file size limits. agent-rules handles this automatically:

1. Try full content
2. If too large, use ## Summary sections instead of full body
3. If still too large, strip code blocks
4. If still too large, truncate with a notice

| Agent | Size Limit | Applies To | |-------|-----------|------------| | Windsurf | 12KB | Single mode only (split mode has no limit) | | Codex | 32KB | Single mode only |

Project Structure

your-project/
  agent-rules/
    agent-rules.config.yaml    # config
    rules/
      coding-style.md          # your rules (edit these)
      error-handling.md
      api-patterns.md
  .cursorrules                 # auto-generated
  CLAUDE.md                    # auto-generated (below marker)
  .windsurfrules               # auto-generated
  GEMINI.md                    # auto-generated
  AGENTS.md                    # auto-generated

License

MIT