README

Easily sync all of your favourite AI instruction files (e.g. .cursorrules, copilot-instructions.md, GEMINI.md, CLAUDE.md, AGENTS.md, .clinerules/project.md).

demo.mp4

Installation

Requirements: PHP 8.2+ is required for all installation options.

Choose the method that works best for your workflow:

Option 1: Standalone Executable (Recommended)

Download the pre-built executable - no Composer required!

# Download from GitHub releases
curl -L -o rulesync https://github.com/jpcaparas/rulesync/releases/latest/download/rulesync
chmod +x rulesync
./rulesync --help

# Optional: Add to PATH for global access
sudo mv rulesync /usr/local/bin/
rulesync --help

Option 2: Global Composer Binary

Install globally via Composer (adds to your $PATH automatically):

composer global require jpcaparas/rulesync
rulesync --help

Option 3: Development Dependency

Add to your project's development dependencies:

composer require --dev jpcaparas/rulesync
./vendor/bin/rulesync --help

Quick Start

Create a rulesync.md file with your rules
Run rulesync generate to create all AI assistant rule files
Your rules are now synced across Claude, Cursor, Windsurf, Gemini CLI, GitHub Copilot, OpenAI Codex, Cline, and Junie!

Commands

rulesync rules:list - Show available AI assistants
rulesync generate - Generate rule files from rulesync.md
rulesync gitignore:generate - Add AI assistant rule files to .gitignore
rulesync config - View current configuration
rulesync disable <name> - Disable specific AI assistant
rulesync enable <name> - Enable specific AI assistant
rulesync base <path> - Set base rules (URL or file path)

Supported AI Assistants

Claude → CLAUDE.md
Cline → .clinerules/project.md
Cursor → .cursorrules
Gemini CLI → GEMINI.md
GitHub Copilot → .github/copilot-instructions.md
Junie → .junie/guidelines.md
OpenAI Codex → AGENTS.md
Windsurf → .windsurfrules

FAQ

Rule Augmentation

Q: How does local and global rule augmentation work?

A: Rulesync automatically detects whether you're in a local project (with composer.json) or global context. When both local (./rulesync.md) and global (~/.config/rulesync/rulesync.md) rule files exist, the system prompts you to:

Combine both files: Local rules first, then global rules separated by ---
Use local only: Ignore global rules entirely

Your preference is saved for future generate calls, but can be changed anytime.

Q: Can I disable certain AI assistants?

A: Yes! Use these commands:

rulesync disable <name> - Disable specific AI assistant (e.g., rulesync disable claude)
rulesync enable <name> - Re-enable a disabled assistant
rulesync rules:list - View all assistants and their enabled/disabled status

Disabled assistants won't have their rule files generated during rulesync generate.

Q: How does overwrite protection work?

A: By default, Rulesync protects existing rule files by:

Comparing content using MD5 hashing
Prompting for confirmation when files exist and differ
Skipping files that already have identical content

You can override this behaviour with:

--overwrite - Force overwrite existing files
--force - Skip all prompts and force generation

Q: Can I use base rules from external sources?

A: Yes! The base rules system allows you to:

Set base rules from URLs: rulesync base https://example.com/rules.md
Set base rules from local files: rulesync base ./shared-rules.md
Disable base rules: rulesync base --disable
View current base rules: rulesync base

Base rules are appended to your final rule files after local/global augmentation.

Building Standalone Executable

You can build Rulesync as a standalone PHAR executable that doesn't require Composer on the target system (PHP 8.2+ is still required).

Prerequisites

Install Box globally:

composer global require humbug/box

Build Commands

Basic build:

php rulesync build

Build with specific version:

php rulesync build 1.0.0

Create full release (with tests):

php rulesync release 1.0.0

Build with verbose output (for debugging):

php rulesync build 1.0.0 --verbose

Output

The standalone executable is created at builds/rulesync and includes all dependencies. You can distribute this single file without requiring users to install Composer or manage dependencies (PHP 8.2+ is still required).

Test the build:

./builds/rulesync --version
./builds/rulesync --help

Notes

The version argument updates the version in config/app.php before building
Use --verbose flag to see detailed Box compilation output for debugging
The build process includes all dependencies (including dev dependencies) in the final PHAR
The release command runs tests, builds the PHAR, but no longer creates a tarball

License

MIT

jpcaparas / rulesync

Maintainers

Details