jpcaparas / rulesync
Easily sync all of your favourite AI assistant configuration files
Requires
- php: ^8.1
Requires (Dev)
- laravel-zero/framework: ^11.0|^12.0
- laravel/pint: ^1.22
- mockery/mockery: ^1.6.12
- pestphp/pest: ^3.8.2
README
Easily sync all of your favourite AI assistant configuration files (e.g. .cursorrules
, copilot-instructions.md
, GEMINI.md
, CLAUDE.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, and Junie!
Commands
rulesync rules:list
- Show available AI assistantsrulesync generate
- Generate rule files from rulesync.mdrulesync config
- View current configurationrulesync disable <name>
- Disable specific AI assistantrulesync enable <name>
- Enable specific AI assistantrulesync base <path>
- Set base rules (URL or file path)
Supported AI Assistants
- Claude →
CLAUDE.md
- Cursor →
.cursorrules
- Gemini CLI →
GEMINI.md
- GitHub Copilot →
.github/copilot-instructions.md
- Junie →
.junie/guidelines.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 assistantrulesync 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