`bash


Fetch skills from external repositories

You can configure Rulesync by creating a rulesync.jsonc file in the root of your project.

$3

Rulesync provides a JSON Schema for editor validation and autocompletion. Add the $schema property to your rulesync.jsonc:

`jsonc
// rulesync.jsonc
{
"$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
"targets": ["claudecode"],
"features": ["rules"],
}
`

$3

Example:

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

// List of tools to generate configurations for. You can specify "*" to generate all tools.
"targets": ["cursor", "claudecode", "geminicli", "opencode", "codexcli"],

// Features to generate. You can specify "*" to generate all features.
"features": ["rules", "ignore", "mcp", "commands", "subagents", "hooks"],

// Base directories for generation.
// Basically, you can specify a ["."] only.
// However, for example, if your project is a monorepo and you have to launch the AI agent at each package directory, you can specify multiple base directories.
"baseDirs": ["."],

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

// Verbose output
"verbose": false,

// Silent mode - suppress all output (except errors)
"silent": false,

// Advanced options
"global": false, // Generate for global(user scope) configuration files
"simulateCommands": false, // Generate simulated commands
"simulateSubagents": false, // Generate simulated subagents
"simulateSkills": false, // Generate simulated skills
"modularMcp": false, // Enable modular-mcp for context compression (experimental, Claude Code only)
}
`

$3

Rulesync supports a local configuration file (rulesync.local.jsonc) for machine-specific or developer-specific settings. This file is automatically added to .gitignore by rulesync gitignore and should not be committed to the repository.

Configuration Priority (highest to lowest):

1. CLI options
2. rulesync.local.jsonc
3. rulesync.jsonc
4. Default values

Example usage:

`jsonc
// rulesync.local.jsonc (not committed to git)
{
"$schema": "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
// Override targets for local development
"targets": ["claudecode"],
// Enable verbose output for debugging
"verbose": true,
}
`

$3

When multiple targets write to the same output file, the last target in the array wins. This is the "last-wins" behavior.

For example, both agentsmd and opencode generate AGENTS.md:

`jsonc
{
// opencode wins because it comes last
"targets": ["agentsmd", "opencode"],
"features": ["rules"],
}
`

In this case:

1. agentsmd generates AGENTS.md first
2. opencode generates AGENTS.md second, overwriting the previous file

If you want agentsmd's output instead, reverse the order:

`jsonc
{
// agentsmd wins because it comes last
"targets": ["opencode", "agentsmd"],
"features": ["rules"],
}
`

Each File Format

$3

Example:

`md
---
root: true # true that is less than or equal to one file for overview such as AGENTS.md, false for details such as .agents/memories/*.md
localRoot: false # (optional, default: false) true for project-specific local rules. Claude Code: generates CLAUDE.local.md; Others: appends to root file
targets: [""] # = all, or specific tools
description: "Rulesync project overview and development guidelines for unified AI rules management CLI tool"
globs: ["*/"] # file patterns to match (e.g., [".md", ".txt"])
agentsmd: # agentsmd and codexcli specific parameters
# Support for using nested AGENTS.md files for subprojects in a large monorepo.
# This option is available only if root is false.
# If subprojectPath is provided, the file is located in ${subprojectPath}/AGENTS.md.
# If subprojectPath is not provided and root is false, the file is located in .agents/memories/*.md.
subprojectPath: "path/to/subproject"
cursor: # cursor specific parameters
alwaysApply: true
description: "Rulesync project overview and development guidelines for unified AI rules management CLI tool"
globs: ["*"]
antigravity: # antigravity specific parameters
trigger: "always_on" # always_on, glob, manual, or model_decision
globs: ["*/"] # (optional) file patterns to match when trigger is "glob"
description: "When to apply this rule" # (optional) used with "model_decision" trigger
---

Rulesync Project Overview

This is Rulesync, a Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files. The project enables teams to maintain consistent AI coding assistant rules across multiple tools.

...
`

$3

Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use canonical camelCase in this file; Cursor uses them as-is; Claude Code gets PascalCase in .claude/settings.json.

Event support:

- Shared (Cursor and Claude): sessionStart, sessionEnd, preToolUse, postToolUse, beforeSubmitPrompt, stop, subagentStop, preCompact
- Cursor-only: postToolUseFailure, subagentStart, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, afterAgentResponse, afterAgentThought, beforeTabFileRead, afterTabFileEdit
- Claude-only: permissionRequest, notification, setup

Use optional override keys so tool-specific events and config live in one file without leaking to the other: cursor.hooks for Cursor-only events, claudecode.hooks for Claude-only. Events in shared hooks that a tool does not support are skipped for that tool (and a warning is logged at generate time).

Example:

`json
{
"version": 1,
"hooks": {
"sessionStart": [{ "type": "command", "command": ".rulesync/hooks/session-start.sh" }],
"postToolUse": [{ "matcher": "Write|Edit", "command": ".rulesync/hooks/format.sh" }],
"stop": [{ "command": ".rulesync/hooks/audit.sh" }]
},
"cursor": {
"hooks": {
"afterFileEdit": [{ "command": ".cursor/hooks/format.sh" }]
}
},
"claudecode": {
"hooks": {
"notification": [
{ "matcher": "permission_prompt", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh" }
]
}
}
}
`

$3

Example:

`md
---
description: "Review a pull request" # command description
targets: [""] # = all, or specific tools
copilot: # copilot specific parameters (optional)
description: "Review a pull request"
antigravity: # antigravity specific parameters
trigger: "/review" # Specific trigger for workflow (renames file to review.md)
turbo: true # (Optional, default: true) Append // turbo for auto-execution
---

target_pr = $ARGUMENTS

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

Execute the following in parallel:

...
`

$3

Example:

`md
---
name: planner # subagent name
targets: [""] # = all, or specific tools
description: >- # subagent description
This is the general-purpose planner. The user asks the agent to plan to
suggest a specification, implement a new feature, refactor the codebase, or
fix a bug. This agent can be called by the user explicitly only.
claudecode: # for claudecode-specific parameters
model: inherit # opus, sonnet, haiku or inherit
copilot: # for GitHub Copilot specific parameters
tools:
- web/fetch # agent/runSubagent is always included automatically
opencode: # for OpenCode-specific parameters
mode: subagent # must be set so OpenCode treats the agent as a subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
write: false
edit: false
bash: false
permission:
bash:
"git diff": allow
---

You are the planner for any tasks.

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

Attention, again, you are just the planner, so though you can read any files and run any commands for analysis, please don't write any code.
`

$3

Example:

`md
---
name: example-skill # skill name
description: >- # skill description
A sample skill that demonstrates the skill format
targets: [""] # = all, or specific tools
claudecode: # for claudecode-specific parameters
allowed-tools:
- "Bash"
- "Read"
- "Write"
- "Grep"
codexcli: # for codexcli-specific parameters
short-description: A brief user-facing description
---

This is the skill body content.

You can provide instructions, context, or any information that helps the AI agent understand and execute this skill effectively.

The skill can include:

- Step-by-step instructions
- Code examples
- Best practices
- Any relevant context

Skills are directory-based and can include additional files alongside SKILL.md.
`

$3

Example:

`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": {}
}
}
}
`

$3

Rulesync supports a single ignore list that can live in either location below:

- .rulesync/.aiignore (recommended)
- .rulesyncignore (project root)

Rules and behavior:

- You may use either location.
- When both exist, Rulesync prefers .rulesync/.aiignore (recommended) over .rulesyncignore (legacy) when reading.
- If neither file exists yet, Rulesync defaults to creating .rulesync/.aiignore.

Notes:

- Running rulesync init will create .rulesync/.aiignore if no ignore file is present.

Example:

`ignore
tmp/
credentials/
`

Global Mode

You can use global mode via Rulesync by enabling --global option. It can also be called as user scope mode.

Currently, supports rules and commands generation for Claude Code. Import for global files is supported for rules and commands.

1. Create an any name directory. For example, if you prefer ~/.aiglobal, run the following command.
`bash
mkdir -p ~/.aiglobal
`
2. Initialize files for global files in the directory.
`bash
cd ~/.aiglobal
rulesync init
`
3. Edit ~/.aiglobal/rulesync.jsonc to enable global mode.
`jsonc
{
"global": true,
}
`
4. Edit ~/.aiglobal/.rulesync/rules/overview.md to your preferences.

`md
---
root: true
---

# The Project Overview

...
`

5. Generate rules for global settings.
`bash
# Run in the ~/.aiglobal directory
rulesync generate
`

> [!NOTE]
> Currently, when in the directory enabled global mode:
>
> - rulesync.jsonc only supports global, features, delete and verbose. Features can be set "rules" and "commands". Other parameters are ignored.
> - rules/*.md only supports single file has root: true, and frontmatter parameters without root are ignored.
> - Only Claude Code is supported for global mode commands.

Simulate Commands, Subagents and Skills

Simulated commands, subagents and skills allow you to generate simulated features for cursor, codexcli and etc. This is useful for shortening your prompts.

1. Prepare .rulesync/commands/.md, .rulesync/subagents/.md and .rulesync/skills/*/SKILL.md for your purposes.
2. Generate simulated commands, subagents and skills for specific tools that are included in cursor, codexcli and etc.
`bash
rulesync generate \
--targets copilot,cursor,codexcli \
--features commands,subagents,skills \
--simulate-commands \
--simulate-subagents \
--simulate-skills
`
3. Use simulated commands, subagents and skills in your prompts.
- Prompt examples:

`txt
# Execute simulated commands. By the way, s/ stands for simulate/.
s/your-command

# Execute simulated subagents
Call your-subagent to achieve something.

# Use simulated skills
Use the skill your-skill to achieve something.
`

Modular MCP (Deprecated)

Rulesync supports compressing tokens consumed by MCP servers d-kimuson/modular-mcp for context saving. When enabled with --modular-mcp, it additionally generates modular-mcp.json.

`bash


Enable modular-mcp via CLI

When enabling modular-mcp, each MCP server must have a description field. Example:

`diff
// .rulesync/mcp.json
{
"mcpServers": {
"context7": {
+ "description": "Up-to-date documentation and code examples for libraries",
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@upstash/context7-mcp"
],
"env": {}
}
}
`

You can also configure exposed to exclude specific MCP servers from modular-mcp. It is optional and default to false. If you specify exposed: true, the MCP server is always loaded in the initial context.

`diff
// .rulesync/mcp.json
{
"mcpServers": {
"context7": {
+ "exposed": true,
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@upstash/context7-mcp"
],
"env": {}
}
}
`

To demonstrate the effect of modular-mcp, please see the following example:

Official Skills

Rulesync provides official skills that you can install using the fetch command:

`bash
rulesync fetch dyoshikawa/rulesync --features skills
`

This will install the Rulesync documentation skill to your project.

Rulesync MCP Server

Rulesync provides an MCP (Model Context Protocol) server that enables AI agents to manage your Rulesync files. This allows AI agents to discover, read, create, update, and delete files dynamically.

> [!NOTE]
> The MCP server exposes the only one tool to minimize your agent's token usage. Approximately less than 1k tokens for the tool definition.

$3

#### Starting the MCP Server

`bash
rulesync mcp
`

This starts an MCP server using stdio transport that AI agents can communicate with.

#### Configuration

Add the Rulesync MCP server to your .rulesync/mcp.json:

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

FAQ

$3

You can try adding the following to .claude/settings.json or .claude/settings.local.json:

`diff
{
+ "enableAllProjectMcpServers": true
}
``

According to the documentation, this means:

> Automatically approve all MCP servers defined in project .mcp.json files

License

MIT License