ai-sync
Cross-platform AI agent synchronization. When you switch between AI coding tools (Claude Code, Cursor, Codex, Aider, Cline, Windsurf, Copilo
Open source Repository Open in the app JSON README (API)
About
Cross-platform AI agent synchronization. When you switch between AI coding tools (Claude Code, Cursor, Codex, Aider, Cline, Windsurf, Copilot), ai-sync maintains a shared .ai-sync/ directory so the next agent picks up exactly where the last one left off — with full context of what was done, what's next, blockers, and build status. Features conflict detection, auto-progress tracking, session audit trails, and adapter files for 9 tools.
Details
- Kind
- Plugins
- Topic
- Files & documents
- Publisher
- oreolion
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 4
- Last push
- 2026-03-31T08:18:32Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
oreolion/ai-sync-plugin/ai-sync
README
# ai-sync
**Stop losing context when you switch AI coding tools.**
[](https://www.npmjs.com/package/@oreolion/ai-sync)
[](LICENSE)
[](https://claude.ai/code)
Every AI coding tool (Claude Code, Cursor, Codex, Aider, Cline, Windsurf, Copilot) keeps its own context. When you switch — because of rate limits, context exhaustion, or wanting a different model — all context is lost. The new agent doesn't know what was built, what's next, or whether the build is clean.
**ai-sync** fixes this. It creates a shared `.ai-sync/` directory in your project that any AI agent can read and write. One agent saves state, the next picks up exactly where it left off.
---
## Quick Start (2 minutes)
### Option A: CLI (works with any AI tool)
```bash
# Install globally
npm install -g @oreolion/ai-sync
# Go to your project
cd your-project
# Initialize — creates .ai-sync/ and adapter files for all tools
ai-sync init
# ... do work with any AI tool ...
# Save state before switching
ai-sync handoff
# Switch to a different tool — it reads .ai-sync/ automatically
# Check status anytime
ai-sync status
```
### Option B: Claude Code Plugin (adds /slash commands)
The plugin gives you `/slash commands` inside Claude Code sessions — auto-loading context on start, reminders to save on stop, and interactive handoff.
**How to load the plugin:**
```bash
# Option 1: Per-session (load from local clone)
git clone https://github.com/oreolion/ai-sync-plugin.git
claude --plugin-dir /path/to/ai-sync-plugin
# Option 2: Per-session (load from npm global install location)
npm install -g @oreolion/ai-sync
claude --plugin-dir "$(npm root -g)/@oreolion/ai-sync"
# Option 3: Permanent install (when available in a marketplace)
# claude plugin install ai-sync@<marketplace-name>
```
Once loaded, you get slash commands inside Claude Code:
```
/sync-init — bootstrap .ai-sync/
/handoff — save state before switching
/sync-resume — load context and continue
/sync-status — view progress
/sync-diff — show changes since last handoff
/sync-adapter — generate adapter for a specific tool
```
> **Note:** `--plugin-dir` loads the plugin for that session only. You need to include it each time you start Claude Code, or create a shell alias (see below).
### Option C: Use both (recommended)
Install the CLI globally **and** load the Claude Code plugin. Use `/slash commands` when inside Claude Code, use `ai-sync` from the terminal when working with other tools.
```bash
npm install -g @oreolion/ai-sync # CLI for any tool
claude --plugin-dir /path/to/ai-sync-plugin # Plugin for Claude Code
```
**Pro tip — create a shell alias so you don't have to type the path every time:**
```bash
# Add to your ~/.bashrc, ~/.zshrc, or ~/.bash_profile:
alias claude-sync='claude --plugin-dir /path/to/ai-sync-plugin'
# Now just run:
claude-sync
```
---
## Important: CLI vs Plugin
These are **two separate things** that work together:
| | CLI (`@oreolion/ai-sync`) | Claude Code Plugin |
|---|---|---|
| **Install** | `npm install -g @oreolion/ai-sync` | `claude --plugin-dir /path/to/ai-sync-plugin` |
| **How to use** | `ai-sync init`, `ai-sync handoff` | `/sync-init`, `/handoff` |
| **Works with** | Any AI tool, any terminal | Claude Code only |
| **Auto-loads context** | No | Yes (on session start) |
| **Reminds you to save** | No | Yes (on session stop) |
| **Slash commands** | No | Yes |
**Common questions:**
**"I ran `npm install -g @oreolion/ai-sync` but I don't see any commands in Claude Code."**
That's expected. The npm package installs a **terminal CLI** (`ai-sync`). Claude Code doesn't scan your global npm packages for plugins. To get slash commands inside Claude Code, you need to load the plugin with `claude --plugin-dir`.
**"Do I have to pass `--plugin-dir` every time?"**
Yes, for now. The `--plugin-dir` flag loads the plugin for that session only. Create a shell alias (see above) to make it painless. Once ai-sync is accepted into a Claude Code plugin marketplace, you'll be able to install it permanently with `claude plugin install`.
---
## What Gets Created
When you run `ai-sync init` (or `/sync-init`), your project gets:
```
your-project/
├── .ai-sync/
│ ├── HANDOFF.md # Current state — what was done, what's next, blockers
│ ├── PLAN.md # Implementation plan (linked or created)
│ ├── PROGRESS.md # Task checklist: [x] done, [ ] pending
│ └── sessions/ # One log file per agent session
├── AGENTS.md # Adapter for Codex, OpenCode, Continue.dev
├── .cursorrules # Adapter for Cursor
├── .clinerules # Adapter for Cline
├── .windsurfrules # Adapter for Windsurf
├── .aider.conf.yml # Adapter for Aider
├── .continuerules # Adapter for Continue.dev
└── .github/
└── copilot-instructions.md # Adapter for GitHub Copilot
```
**Adapter files** are thin pointers. Each one simply tells its AI tool: "Read `.ai-sync/HANDOFF.md` for context before starting work." This is how every tool automatically picks up where the last one left off — no manual copy-paste needed.
---
## Workflow Examples
### Example 1: Claude Code hits rate limit, switch to Cursor
```
# In Claude Code:
You: /handoff
# Claude saves: what it built, what's next, build status, files changed
# Open same project in Cursor
# Cursor reads .cursorrules → reads .ai-sync/HANDOFF.md → knows everything
# Cursor continues the work
# When done in Cursor, run from terminal:
ai-sync handoff
# Back in Claude Code:
You: /sync-resume
# Claude loads the full context and continues from where Cursor stopped
```
### Example 2: Split work across Codex and Claude Code
```bash
# Terminal — initialize sync in your project
ai-sync init
# Work with Codex (reads AGENTS.md automatically)
codex "implement the auth module per the plan"
# Codex finishes or you want to switch
ai-sync handoff
# Continue in Claude Code
claude
> /sync-resume # loads everything Codex did
> (continue work)
> /handoff # save before stopping
```
### Example 3: Just checking where things stand
```bash
ai-sync status
# Shows: current phase, completion %, what's done, what's next, last agent, blockers
```
---
## All Commands
### CLI Commands (terminal)
| Command | Description |
|---------|-------------|
| `ai-sync init` | Create `.ai-sync/` + adapter files for all supported tools |
| `ai-sync handoff` | Save state before switching agents (conflict detection + auto-progress) |
| `ai-sync status` | Show progress with completion bar |
| `ai-sync resume [tool]` | Generate resume prompt for the target tool |
| `ai-sync diff` | Show changes since last handoff |
| `ai-sync adapter <tool>` | Generate adapter file for a specific tool |
| `ai-sync transfer` | Import session context via `continues` |
| `ai-sync hooks install` | Install git hooks for auto-save on commit |
| `ai-sync hooks remove` | Remove git hooks |
### Plugin Commands (inside Claude Code)
| Command | Description |
|---------|-------------|
| `/sync-init` | Bootstrap `.ai-sync/` in the current project |
| `/handoff` | Save state before switching agents (with conflict detection) |
| `/sync-status` | Show current progress, next steps, session history |
| `/sync-resume` | Load full context from last handoff and continue |
| `/sync-diff` | Show all changes since last handoff |
| `/sync-adapter <tool>` | Generate adapter file for a specific tool |
| `/sync-transfer` | Import session context from another tool |
| `/sync-hooks install\|remove` | Install/remove git hooks |
---
## How It Works Under the Hood
### When an agent starts work
1. Reads `.ai-sync/HANDOFF.md` — knows what happened and what's next
2. Reads `.ai-sync/PROGRESS.md` — knows which tasks are done vs pending
3. Reads `.ai-sync/PLAN.md` — follows the implementation plan
### While working
- Checks off completed tasks in `PROGRESS.md`
- Documents blockers in `HANDOFF.md` immediately
### When stopping
1. **Conflict detection** — checks if another agent modified `HANDOFF.md` during the session
2. **Auto-progress** — cross-references changed files against plan tasks and auto-checks `PROGRESS.md`
3. **State capture** — writes `HANDOFF.md` with completed work, specific next steps, and build status
4. **Session log** — creates a timestamped log in `.ai-sync/sessions/`
### The five rules all agents follow
1. **Follow the plan** — No unplanned features or refactors
2. **Don't repeat work** — Check `PROGRESS.md` before starting anything
3. **Be specific in handoffs** — "Create `api/auth.ts` with OAuth flow" not "Continue auth work"
4. **Run verification** — Build and typecheck before stopping
5. **Document decisions** — The next agent has zero context about why you made choices
---
## Supported Tools
| Tool | Adapter | How it picks up context |
|------|---------|------------------------|
| **Claude Code** | Plugin + CLAUDE.md | Full integration: slash commands, auto-load on start, reminder on stop |
| **Cursor** | `.cursorrules` | Reads `.ai-sync/HANDOFF.md` via rules file |
| **OpenAI Codex** | `AGENTS.md` | Reads `.ai-sync/HANDOFF.md` via agents file |
| **Cline** | `.clinerules` | Reads `.ai-sync/HANDOFF.md` via rules file |
| **Windsurf** | `.windsurfrules` | Reads `.ai-sync/HANDOFF.md` via rules file |
| **Aider** | `.aider.conf.yml` | Reads `.ai-sync/HANDOFF.md` via config |
| **OpenCode** | `AGENTS.md` | Reads `.ai-sync/HANDOFF.md` via agents file |
| **Continue.dev** | `.continuerules` | Reads `.ai-sync/HANDOFF.md` via rules file |
| **GitHub Copilot** | `.github/copilot-instructions.md` | Reads `.ai-sync/HANDOFF.md` via instructions |
---
## Key Features
- **Conflict detection** — Warns if another agent modified `HANDOFF.md` while you were working
- **Auto-progress tracking** — Automatically checks off tasks when their output files are modified
- **Build-state awareness** — Records whether the last agent left a clean or broken build
- **Session audit trail** — Every agent session is logged with timestamps and decisions
- **Zero lock-in** — Pure Markdown + YAML protocol. No proprietary format, no vendor lock-in
---
## Also Available As
| Package | Description | Install |
|---------|-------------|---------|
| [`@oreolion/ai-sync`](https://www.npmjs.com/package/@oreolion/ai-sync) | CLI (this package) | `npm install -g @oreolion/ai-sync` |
| `@oreolion/ai-sync-mcp` | MCP server for MCP-native tools | See [`packages/mcp-server/`](packages/mcp-server/) |
| `ai-sync` (VS Code) | VS Code extension with sidebar UI | See [`packages/vscode-extension/`](packages/vscode-extension/) |
| `ai-sync-action` | GitHub Action for CI/CD | See [`packages/github-action/`](packages/github-action/) |
| `@oreolion/ai-sync-remote` | Cloudflare Workers API for teams | See [`packages/remote-sync/`](packages/remote-sync/) |
| `@oreolion/ai-sync-dashboard` | Next.js analytics dashboard | See [`packages/dashboard/`](packages/dashboard/) |
---
## Plugin Structure (for contributors)
```
ai-sync-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── commands/ # Slash command definitions
│ ├── sync-init.md
│ ├── handoff.md
│ ├── sync-status.md
│ ├── sync-resume.md
│ ├── sync-diff.md
│ ├── sync-adapter.md
│ ├── sync-transfer.md
│ └── sync-hooks.md
├── skills/
│ └── ai-sync-protocol/
│ └── SKILL.md # Protocol spec (auto-loaded when .ai-sync/ exists)
├── hooks/
│ └── hooks.json # Session start/stop hooks
├── packages/ # Standalone packages (CLI, MCP, VS Code, etc.)
├── tests/
│ └── validate-plugin.sh
├── CONTRIBUTING.md
├── ROADMAP.md
└── LICENSE
```
## Protocol Specification
The full protocol spec is in [`skills/ai-sync-protocol/SKILL.md`](skills/ai-sync-protocol/SKILL.md). This defines the exact format of `HANDOFF.md` (YAML frontmatter + sections), `PROGRESS.md` (phase headers + checklists), and session logs.
## Testing
```bash
bash tests/validate-plugin.sh
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Roadmap
See [ROADMAP.md](ROADMAP.md).
## License
[MIT](LICENSE)