Rulesync (dyoshikawa/rulesync)

Rulesync

https://github.com/dyoshikawa/rulesync
Admin
Rulesync is a Node.js CLI tool that automatically generates configuration files for various AI...

Tokens:15,510
Snippets:120
Trust Score:8.2
Update:5 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Rulesync

Rulesync is a Node.js CLI tool that enables unified AI rules management across multiple AI development tools. It generates configuration files for various AI coding assistants (GitHub Copilot, Cursor, Claude Code, Cline, and 15+ others) from centralized rule files stored in the `.rulesync/` directory. This allows development teams to maintain consistent AI assistant behavior across different tools without vendor lock-in, supporting features like rules, ignore files, MCP servers, commands, subagents, and skills.

The tool addresses the challenge of AI development tool proliferation by providing a single source of truth for AI configurations. Teams can freely switch between AI tools while maintaining consistent coding standards, project guidelines, and assistant behaviors. Rulesync supports both project-level and global (user-scope) configurations, with advanced features including simulated commands/subagents for tools that don't natively support them, and experimental modular MCP for context compression.

## CLI Commands

### Initialize New Project

```bash
# Create .rulesync directory structure with sample files
rulesync init

# Creates:
# - .rulesync/rules/overview.md (sample rule)
# - .rulesync/mcp.json (sample MCP servers)
# - .rulesync/commands/review-pr.md (sample command)
# - .rulesync/subagents/planner.md (sample subagent)
# - .rulesync/.aiignore (sample ignore file)
# - rulesync.jsonc (configuration file)
```

### Generate Configuration Files

```bash
# Generate all features for all supported tools
rulesync generate --targets "*" --features "*"

# Generate for specific tools only
rulesync generate --targets copilot,cursor,claudecode --features rules,mcp

# Generate with cleanup (delete existing files first)
rulesync generate --targets "*" --features "*" --delete

# Generate for multiple base directories (monorepo support)
rulesync generate --base-dir packages/frontend,packages/backend

# Generate simulated commands and subagents for unsupported tools
rulesync generate \
  --targets copilot,cursor \
  --features commands,subagents \
  --simulate-commands \
  --simulate-subagents

# Generate with modular MCP for context compression (experimental)
rulesync generate --targets claudecode --features mcp --modular-mcp

# Verbose output for debugging
rulesync generate --targets "*" --features "*" --verbose
```

### Import Existing Configurations

```bash
# Import from Claude Code
rulesync import --targets claudecode --features rules,mcp,commands,subagents,skills

# Import from Cursor
rulesync import --targets cursor --features rules,ignore

# Import from GitHub Copilot
rulesync import --targets copilot --features rules,mcp

# Import with verbose output
rulesync import --targets claudecode --features "*" --verbose

# Note: Only one tool can be imported at a time
```

### Global Mode Configuration

```bash
# Initialize global configuration directory
mkdir -p ~/.aiglobal
cd ~/.aiglobal
rulesync init

# Edit rulesync.jsonc to enable global mode
# { "global": true, "features": ["rules", "commands"] }

# Generate global rules (applies to all projects)
rulesync generate --global

# Import global rules from existing tool
rulesync import --targets claudecode --features rules --global
```

### Add Generated Files to Gitignore

```bash
# Automatically add AI tool configuration files to .gitignore
rulesync gitignore

# Adds patterns like:
# - .cursorrules
# - CLAUDE.md
# - .github/copilot-instructions.md
# - etc.
```

### Start MCP Server

```bash
# Start Rulesync MCP server for programmatic access
rulesync mcp

# Use in .rulesync/mcp.json:
# {
#   "mcpServers": {
#     "rulesync-mcp": {
#       "type": "stdio",
#       "command": "npx",
#       "args": ["-y", "rulesync", "mcp"],
#       "env": {}
#     }
#   }
# }
```

## Configuration File

### Configuration File Structure

```jsonc
// rulesync.jsonc
{
  "$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",

  // Tools to generate for: agentsmd, amazonqcli, antigravity, augmentcode,
  // copilot, cursor, cline, claudecode, codexcli, opencode, qwencode, roo,
  // geminicli, kiro, junie, warp, windsurf, or "*" for all
  "targets": ["copilot", "cursor", "claudecode", "codexcli"],

  // Features to generate: rules, ignore, mcp, commands, subagents, skills, or "*"
  "features": ["rules", "ignore", "mcp", "commands", "subagents"],

  // Base directories for generation (monorepo support)
  "baseDirs": ["."],

  // Delete existing files before generating
  "delete": true,

  // Verbose logging
  "verbose": false,

  // Generate for global/user scope instead of project scope
  "global": false,

  // Generate simulated commands for tools without native support
  "simulateCommands": false,

  // Generate simulated subagents for tools without native support
  "simulateSubagents": false,

  // Generate simulated skills for tools without native support
  "simulateSkills": false,

  // Enable modular-mcp for context compression (experimental, Claude Code only)
  "modularMcp": false
}
```

### Using Configuration File

```bash
# Configuration file is automatically loaded from rulesync.jsonc
rulesync generate

# Override config file location
rulesync generate --config path/to/custom-config.jsonc

# CLI arguments override configuration file settings
rulesync generate --targets cursor --features rules
```

## Rule Files

### Basic Rule File Format

```markdown
<!-- .rulesync/rules/overview.md -->
---
root: true
targets: ["*"]
description: "Project overview and development guidelines"
globs: ["**/*"]
---

# Project Overview

This project uses TypeScript and follows strict coding standards.

## Guidelines

- Use functional programming patterns
- Prefer immutability
- Write comprehensive tests
- Document public APIs
```

### Advanced Rule File with Tool-Specific Settings

```markdown
<!-- .rulesync/rules/cursor-specific.md -->
---
root: false
targets: ["cursor", "copilot"]
description: "Frontend-specific coding guidelines"
globs: ["src/components/**/*", "src/pages/**/*"]
cursor:
  alwaysApply: true
  description: "React component guidelines"
  globs: ["*.tsx", "*.jsx"]
agentsmd:
  subprojectPath: "packages/frontend"
---

# Frontend Guidelines

- Use React Hooks exclusively
- Implement proper error boundaries
- Follow accessibility guidelines (WCAG 2.1)
```

### Legacy Rule File Format

```markdown
<!-- .rulesync/rules/legacy-format.md -->
---
target: copilot
---

# Legacy Format

Files without explicit targets support legacy format for backward compatibility.
```

## Command Files

### Command File Format

```markdown
<!-- .rulesync/commands/review-pr.md -->
---
description: 'Review a pull request thoroughly'
targets: ["*"]
---

target_pr = $ARGUMENTS

If target_pr is not provided, use the PR of the current branch.

Execute the following in parallel:

1. Analyze code quality and style consistency
2. Check test coverage and test quality
3. Review documentation completeness
4. Identify potential bugs or security issues
5. Check for performance concerns

Provide a detailed summary with:
- Critical issues (must fix)
- Suggestions for improvement
- Positive aspects worth highlighting
```

### Using Commands

```bash
# After generating commands for supported tools:
# In Claude Code: /review-pr 123
# In Cursor: @review-pr 123
# In GitHub Copilot: /review-pr 123

# With simulated commands (for tools without native support):
rulesync generate --targets copilot --features commands --simulate-commands
# Then in Copilot: "s/review-pr 123" (simulated command)
```

## Subagent Files

### Subagent File Format

```markdown
<!-- .rulesync/subagents/planner.md -->
---
name: planner
targets: ["*"]
description: >-
  General-purpose planning agent that analyzes requirements and creates
  detailed implementation plans without writing code
claudecode:
  model: sonnet  # opus, sonnet, haiku, or inherit
---

You are the planner for any tasks.

Based on the user's instruction, create a plan while analyzing related files.
Then report the plan in detail. You can output files to @tmp/ if needed.

Important: You are just the planner. Read files and run analysis commands,
but don't write any code. Only create plans.
```

### Using Subagents

```bash
# After generating subagents:
# In Claude Code: Use Task tool with subagent_type='planner'
# In tools supporting subagents natively

# With simulated subagents (for tools without native support):
rulesync generate --targets cursor --features subagents --simulate-subagents
# Then in Cursor: "Call planner to create implementation plan"
```

## Skill Files

### Skill Directory Structure

```markdown
<!-- .rulesync/skills/example-skill/SKILL.md -->
---
name: example-skill
description: >-
  Demonstrates skill format with step-by-step instructions
targets: ["*"]
claudecode:
  allowed-tools:
    - "Bash"
    - "Read"
    - "Write"
    - "Grep"
---

# Example Skill

This skill demonstrates best practices for creating reusable skill modules.

## Steps

1. Analyze the requirement
2. Search codebase for relevant patterns
3. Implement solution following project standards
4. Test implementation
5. Document changes

Skills can include additional files alongside SKILL.md for reference materials.
```

### Skill Directory with Additional Files

```
.rulesync/skills/api-generator/
├── SKILL.md
├── templates/
│   ├── controller.template.ts
│   └── test.template.ts
└── examples/
    └── sample-api.ts
```

## MCP Configuration

### MCP Configuration File

```json
// .rulesync/mcp.json
{
  "mcpServers": {
    "serena": {
      "description": "Code analysis and semantic search MCP server",
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--context",
        "ide-assistant",
        "--enable-web-dashboard",
        "false",
        "--project",
        "."
      ],
      "env": {}
    },
    "context7": {
      "description": "Library documentation search server",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    }
  }
}
```

### MCP with Modular MCP Support

```json
// .rulesync/mcp.json (with modular-mcp enabled)
{
  "mcpServers": {
    "serena": {
      "description": "Code analysis and semantic search MCP server",
      "exposed": false,  // Only load when explicitly requested
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"],
      "env": {}
    },
    "filesystem": {
      "description": "File system operations",
      "exposed": true,  // Always loaded in initial context
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {}
    }
  }
}
```

```bash
# Generate with modular-mcp (reduces MCP tools context by ~92%)
rulesync generate --targets claudecode --features mcp --modular-mcp
```

## Ignore Files

### Ignore File Format

```
# .rulesync/.aiignore
tmp/
credentials/
.env
*.secret
node_modules/
.git/
dist/
build/
```

### Ignore File Locations

```bash
# Recommended location (preferred)
.rulesync/.aiignore

# Legacy location (supported for backward compatibility)
.rulesyncignore

# Priority: .rulesync/.aiignore takes precedence over .rulesyncignore
```

## Rulesync MCP Server API

### List Rules

```javascript
// List all rule files with frontmatter
const rules = await mcpClient.callTool("listRules", {});

// Returns:
// {
//   "rules": [
//     {
//       "relativePathFromCwd": ".rulesync/rules/overview.md",
//       "frontmatter": {
//         "root": true,
//         "targets": ["*"],
//         "description": "Project overview",
//         "globs": ["**/*"]
//       }
//     }
//   ]
// }
```

### Get Rule Content

```javascript
// Get complete rule file content
const rule = await mcpClient.callTool("getRule", {
  relativePathFromCwd: ".rulesync/rules/overview.md"
});

// Returns:
// {
//   "relativePathFromCwd": ".rulesync/rules/overview.md",
//   "frontmatter": { "root": true, "targets": ["*"], ... },
//   "body": "# Project Overview\n\n..."
// }
```

### Create or Update Rule

```javascript
// Create or update rule (upsert)
const result = await mcpClient.callTool("putRule", {
  relativePathFromCwd: ".rulesync/rules/my-rule.md",
  frontmatter: {
    root: false,
    targets: ["*"],
    description: "Custom rule",
    globs: ["src/**/*"]
  },
  body: "# My Custom Rule\n\nRule content here..."
});

// Returns the created/updated rule
```

### Delete Rule

```javascript
// Delete a rule file
const result = await mcpClient.callTool("deleteRule", {
  relativePathFromCwd: ".rulesync/rules/old-rule.md"
});

// Returns:
// { "relativePathFromCwd": ".rulesync/rules/old-rule.md" }
```

### List Commands

```javascript
// List all command files
const commands = await mcpClient.callTool("listCommands", {});

// Returns:
// {
//   "commands": [
//     {
//       "relativePathFromCwd": ".rulesync/commands/review-pr.md",
//       "frontmatter": {
//         "description": "Review a pull request",
//         "targets": ["*"]
//       }
//     }
//   ]
// }
```

### Manage Subagents

```javascript
// List subagents
const subagents = await mcpClient.callTool("listSubagents", {});

// Get subagent details
const subagent = await mcpClient.callTool("getSubagent", {
  relativePathFromCwd: ".rulesync/subagents/planner.md"
});

// Create/update subagent
await mcpClient.callTool("putSubagent", {
  relativePathFromCwd: ".rulesync/subagents/new-agent.md",
  frontmatter: {
    name: "new-agent",
    targets: ["*"],
    description: "New agent description"
  },
  body: "Agent instructions..."
});

// Delete subagent
await mcpClient.callTool("deleteSubagent", {
  relativePathFromCwd: ".rulesync/subagents/old-agent.md"
});
```

### Manage Skills

```javascript
// List skills
const skills = await mcpClient.callTool("listSkills", {});

// Get skill details (includes SKILL.md and all directory files)
const skill = await mcpClient.callTool("getSkill", {
  relativePathFromCwd: ".rulesync/skills/example-skill"
});

// Returns:
// {
//   "relativePathFromCwd": ".rulesync/skills/example-skill",
//   "frontmatter": { "name": "example-skill", ... },
//   "body": "Skill content...",
//   "additionalFiles": [
//     { "relativePath": "template.ts", "content": "..." }
//   ]
// }

// Create/update skill
await mcpClient.callTool("putSkill", {
  relativePathFromCwd: ".rulesync/skills/new-skill",
  frontmatter: {
    name: "new-skill",
    targets: ["*"],
    description: "New skill"
  },
  body: "Skill instructions...",
  additionalFiles: [
    { relativePath: "template.ts", content: "export const..." }
  ]
});

// Delete skill
await mcpClient.callTool("deleteSkill", {
  relativePathFromCwd: ".rulesync/skills/old-skill"
});
```

### Manage MCP Configuration

```javascript
// Get MCP configuration
const mcpConfig = await mcpClient.callTool("getMcpFile", {});

// Returns:
// {
//   "relativePathFromCwd": ".rulesync/mcp.json",
//   "content": { "mcpServers": { ... } }
// }

// Update MCP configuration
await mcpClient.callTool("putMcpFile", {
  content: {
    mcpServers: {
      "new-server": {
        type: "stdio",
        command: "npx",
        args: ["-y", "some-mcp-server"],
        env: {}
      }
    }
  }
});

// Delete MCP configuration
await mcpClient.callTool("deleteMcpFile", {});
```

### Manage Ignore File

```javascript
// Get ignore file content
const ignoreFile = await mcpClient.callTool("getIgnoreFile", {});

// Returns:
// {
//   "relativePathFromCwd": ".rulesync/.aiignore",
//   "content": "tmp/\ncredentials/\n"
// }

// Update ignore file
await mcpClient.callTool("putIgnoreFile", {
  content: "tmp/\ncredentials/\n.env\n*.secret\n"
});

// Delete ignore file
await mcpClient.callTool("deleteIgnoreFile", {});
```

## Package Manager Installation

### NPM Installation

```bash
# Global installation
npm install -g rulesync

# Check installation
rulesync --version
rulesync --help

# Use without installation (npx)
npx rulesync init
npx rulesync generate --targets "*" --features "*"
```

### Homebrew Installation

```bash
# macOS installation via Homebrew
brew install rulesync

rulesync --version
rulesync --help
```

### Binary Installation

```bash
# Linux x64
curl -L https://github.com/dyoshikawa/rulesync/releases/latest/download/rulesync-linux-x64 -o rulesync
chmod +x rulesync
sudo mv rulesync /usr/local/bin/

# macOS Apple Silicon
curl -L https://github.com/dyoshikawa/rulesync/releases/latest/download/rulesync-darwin-arm64 -o rulesync
chmod +x rulesync
sudo mv rulesync /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/dyoshikawa/rulesync/releases/latest/download/rulesync-windows-x64.exe" -OutFile "rulesync.exe"
Move-Item rulesync.exe C:\Windows\System32\

# Verify checksums
curl -L https://github.com/dyoshikawa/rulesync/releases/latest/download/SHA256SUMS -o SHA256SUMS
sha256sum -c SHA256SUMS  # Linux/macOS
```

Rulesync serves as a centralized AI rules management solution for modern development teams working with multiple AI coding assistants. The primary use cases include maintaining consistent AI assistant behavior across team members using different tools, migrating between AI tools without redefining rules, implementing hybrid workflows with multiple tools simultaneously, and ensuring code quality through unified guidelines. Organizations use Rulesync to avoid vendor lock-in while benefiting from the latest AI development tools, with the ability to switch tools as the ecosystem evolves.

Integration patterns include project-level configurations for team-wide standards, global configurations for individual developer preferences, monorepo support through multiple base directories, and CI/CD integration for automated configuration validation. The MCP server enables programmatic management of rule files, allowing AI agents to dynamically discover, read, and modify rules. Advanced patterns include simulated commands/subagents for extending tools that lack native support, modular MCP for context optimization in large projects, and selective feature generation for different tools based on their capabilities. The tool is actively used by companies like Classmethod Inc. (featured in Anthropic's official customer stories) and Asoview Inc., demonstrating its production-readiness for enterprise environments.