AI Rules Sync

# AI Rules Sync

[![Npm](https://badgen.net/npm/v/ai-rules-sync)](https://www.npmjs.com/package/ai-rules-sync)
[![License](https://img.shields.io/github/license/lbb00/ai-rules-sync.svg)](https://github.com/lbb00/ai-rules-sync/blob/master/LICENSE)
[![Npm download](https://img.shields.io/npm/dw/ai-rules-sync.svg)](https://www.npmjs.com/package/ai-rules-sync)

[English](./README.md) | [中文](./README_ZH.md)

**AI Rules Sync (AIS)** - Synchronize, manage, and share your AI agent rules across projects and teams.

Stop copying `.mdc` files around. Manage your rules in Git repositories and sync them via symbolic links.

**Supports:** Cursor (rules, commands, skills, subagents), GitHub Copilot (instructions, prompts, skills, agents), Claude Code (rules, skills, subagents), Trae (rules, skills), OpenCode (commands, skills, agents, tools), Codex (rules, skills), Gemini CLI (commands, skills, agents), Warp (rules via AGENTS.md, skills), and universal AGENTS.md.

---

## Table of Contents

- [Why AIS?](#why-ais)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Supported Tools](#supported-tools)
- [Core Concepts](#core-concepts)
- [Basic Usage](#basic-usage)
- [Tool-Specific Guides](#tool-specific-guides)
- [Advanced Features](#advanced-features)
- [Configuration Reference](#configuration-reference)
- [Architecture](#architecture)

---

## Why AIS?

- **🧩 Multi-Repository**: Mix rules from company standards, team protocols, and open-source collections
- **🔄 Sync Once, Update Everywhere**: One source of truth, automatic updates across all projects
- **🤝 Team Alignment**: Share coding standards instantly, onboard new members with one command
- **🔒 Privacy First**: Keep sensitive rules local with `ai-rules-sync.local.json`
- **🛠️ Git Integration**: Manage repositories directly through CLI (`ais git`)
- **🔌 Extensible**: Plugin architecture for adding new AI tools

---

## Quick Start

### Scenario 1: Use Existing Rules

**You have a rules repository and want to use its rules in your project.**

```bash
# 1. Install AIS
npm install -g ai-rules-sync

# 2. Go to your project
cd your-project

# 3. Add a rule (IMPORTANT: specify repository URL the first time)
ais cursor add react -t https://github.com/your-org/rules-repo.git

# Done! The rule is now linked to your project
```

**What just happened?**
- AIS cloned the repository to `~/.config/ai-rules-sync/repos/`
- Set it as your current repository
- Created a symlink: `rules-repo/.cursor/rules/react` → `your-project/.cursor/rules/react`
- Saved the configuration to `ai-rules-sync.json`

**Next time**, you can omit the `-t` flag:
```bash
ais cursor add vue
ais cursor add testing
```

### Scenario 2: Share Your Existing Rules

**You have rules in your project and want to share them via a repository.**

```bash
# 1. Install AIS
npm install -g ai-rules-sync

# 2. Create a rules repository (or use existing one)
# Option A: Create new repository
git init ~/my-rules-repo
ais use ~/my-rules-repo

# Option B: Use existing repository
ais use https://github.com/your-org/rules-repo.git

# 3. Import your existing rule
cd your-project
ais cursor rules import my-custom-rule

# Done! Your rule is now in the repository and linked to your project
```

**What just happened?**
- AIS copied `your-project/.cursor/rules/my-custom-rule` to the repository
- Created a git commit
- Replaced the original with a symlink
- Saved the configuration to `ai-rules-sync.json`

**Optional: Push to remote**
```bash
ais cursor rules import my-rule --push
# or manually:
ais git push
```

---

## Installation

```bash
npm install -g ai-rules-sync
```

**Verify installation:**
```bash
ais --version
```

**Optional: Enable tab completion**
```bash
ais completion install
```

---

## Supported Tools

| Tool | Type | Mode | Default Source Directory | File Suffixes | Documentation |
|------|------|------|--------------------------|---------------|---------------|
| Cursor | Rules | hybrid | `.cursor/rules/` | `.mdc`, `.md` | [Docs](https://cursor.com/docs/context/rules) |
| Cursor | Commands | file | `.cursor/commands/` | `.md` | [Docs](https://cursor.com/docs/context/commands) |
| Cursor | Skills | directory | `.cursor/skills/` | - | [Docs](https://cursor.com/docs/context/skills) |
| Cursor | Subagents | directory | `.cursor/agents/` | - | [Docs](https://cursor.com/docs/context/subagents) |
| GitHub Copilot | Instructions | file | `.github/instructions/` | `.instructions.md`, `.md` | [Docs](https://docs.github.com/copilot) |
| GitHub Copilot | Prompts | file | `.github/prompts/` | `.prompt.md`, `.md` | [Docs](https://docs.github.com/copilot) |
| GitHub Copilot | Skills | directory | `.github/skills/` | - | [Docs](https://docs.github.com/en/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat) |
| GitHub Copilot | Agents | file | `.github/agents/` | `.agent.md`, `.md` | [Docs](https://docs.github.com/copilot) |
| Claude Code | Rules | file | `.claude/rules/` | `.m

... (truncated)