{
  "markdown": "# ai-sync\n\n**Stop losing context when you switch AI coding tools.**\n\n[![npm](https://img.shields.io/npm/v/@oreolion/ai-sync)](https://www.npmjs.com/package/@oreolion/ai-sync)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Plugin: Claude Code](https://img.shields.io/badge/Plugin-Claude%20Code-blueviolet)](https://claude.ai/code)\n\nEvery 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.\n\n**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.\n\n---\n\n## Quick Start (2 minutes)\n\n### Option A: CLI (works with any AI tool)\n\n```bash\n# Install globally\nnpm install -g @oreolion/ai-sync\n\n# Go to your project\ncd your-project\n\n# Initialize — creates .ai-sync/ and adapter files for all tools\nai-sync init\n\n# ... do work with any AI tool ...\n\n# Save state before switching\nai-sync handoff\n\n# Switch to a different tool — it reads .ai-sync/ automatically\n\n# Check status anytime\nai-sync status\n```\n\n### Option B: Claude Code Plugin (adds /slash commands)\n\nThe plugin gives you `/slash commands` inside Claude Code sessions — auto-loading context on start, reminders to save on stop, and interactive handoff.\n\n**How to load the plugin:**\n\n```bash\n# Option 1: Per-session (load from local clone)\ngit clone https://github.com/oreolion/ai-sync-plugin.git\nclaude --plugin-dir /path/to/ai-sync-plugin\n\n# Option 2: Per-session (load from npm global install location)\nnpm install -g @oreolion/ai-sync\nclaude --plugin-dir \"$(npm root -g)/@oreolion/ai-sync\"\n\n# Option 3: Permanent install (when available in a marketplace)\n# claude plugin install ai-sync@<marketplace-name>\n```\n\nOnce loaded, you get slash commands inside Claude Code:\n```\n/sync-init    — bootstrap .ai-sync/\n/handoff      — save state before switching\n/sync-resume  — load context and continue\n/sync-status  — view progress\n/sync-diff    — show changes since last handoff\n/sync-adapter — generate adapter for a specific tool\n```\n\n> **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).\n\n### Option C: Use both (recommended)\n\nInstall 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.\n\n```bash\nnpm install -g @oreolion/ai-sync          # CLI for any tool\nclaude --plugin-dir /path/to/ai-sync-plugin  # Plugin for Claude Code\n```\n\n**Pro tip — create a shell alias so you don't have to type the path every time:**\n\n```bash\n# Add to your ~/.bashrc, ~/.zshrc, or ~/.bash_profile:\nalias claude-sync='claude --plugin-dir /path/to/ai-sync-plugin'\n\n# Now just run:\nclaude-sync\n```\n\n---\n\n## Important: CLI vs Plugin\n\nThese are **two separate things** that work together:\n\n| | CLI (`@oreolion/ai-sync`) | Claude Code Plugin |\n|---|---|---|\n| **Install** | `npm install -g @oreolion/ai-sync` | `claude --plugin-dir /path/to/ai-sync-plugin` |\n| **How to use** | `ai-sync init`, `ai-sync handoff` | `/sync-init`, `/handoff` |\n| **Works with** | Any AI tool, any terminal | Claude Code only |\n| **Auto-loads context** | No | Yes (on session start) |\n| **Reminds you to save** | No | Yes (on session stop) |\n| **Slash commands** | No | Yes |\n\n**Common questions:**\n\n**\"I ran `npm install -g @oreolion/ai-sync` but I don't see any commands in Claude Code.\"**\nThat'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`.\n\n**\"Do I have to pass `--plugin-dir` every time?\"**\nYes, 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`.\n\n---\n\n## What Gets Created\n\nWhen you run `ai-sync init` (or `/sync-init`), your project gets:\n\n```\nyour-project/\n├── .ai-sync/\n│   ├── HANDOFF.md      # Current state — what was done, what's next, blockers\n│   ├── PLAN.md         # Implementation plan (linked or created)\n│   ├── PROGRESS.md     # Task checklist: [x] done, [ ] pending\n│   └── sessions/       # One log file per agent session\n├── AGENTS.md           # Adapter for Codex, OpenCode, Continue.dev\n├── .cursorrules        # Adapter for Cursor\n├── .clinerules         # Adapter for Cline\n├── .windsurfrules      # Adapter for Windsurf\n├── .aider.conf.yml     # Adapter for Aider\n├── .continuerules      # Adapter for Continue.dev\n└── .github/\n    └── copilot-instructions.md  # Adapter for GitHub Copilot\n```\n\n**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.\n\n---\n\n## Workflow Examples\n\n### Example 1: Claude Code hits rate limit, switch to Cursor\n\n```\n# In Claude Code:\nYou: /handoff\n# Claude saves: what it built, what's next, build status, files changed\n\n# Open same project in Cursor\n# Cursor reads .cursorrules → reads .ai-sync/HANDOFF.md → knows everything\n# Cursor continues the work\n\n# When done in Cursor, run from terminal:\nai-sync handoff\n\n# Back in Claude Code:\nYou: /sync-resume\n# Claude loads the full context and continues from where Cursor stopped\n```\n\n### Example 2: Split work across Codex and Claude Code\n\n```bash\n# Terminal — initialize sync in your project\nai-sync init\n\n# Work with Codex (reads AGENTS.md automatically)\ncodex \"implement the auth module per the plan\"\n\n# Codex finishes or you want to switch\nai-sync handoff\n\n# Continue in Claude Code\nclaude\n> /sync-resume     # loads everything Codex did\n> (continue work)\n> /handoff         # save before stopping\n```\n\n### Example 3: Just checking where things stand\n\n```bash\nai-sync status\n# Shows: current phase, completion %, what's done, what's next, last agent, blockers\n```\n\n---\n\n## All Commands\n\n### CLI Commands (terminal)\n\n| Command | Description |\n|---------|-------------|\n| `ai-sync init` | Create `.ai-sync/` + adapter files for all supported tools |\n| `ai-sync handoff` | Save state before switching agents (conflict detection + auto-progress) |\n| `ai-sync status` | Show progress with completion bar |\n| `ai-sync resume [tool]` | Generate resume prompt for the target tool |\n| `ai-sync diff` | Show changes since last handoff |\n| `ai-sync adapter <tool>` | Generate adapter file for a specific tool |\n| `ai-sync transfer` | Import session context via `continues` |\n| `ai-sync hooks install` | Install git hooks for auto-save on commit |\n| `ai-sync hooks remove` | Remove git hooks |\n\n### Plugin Commands (inside Claude Code)\n\n| Command | Description |\n|---------|-------------|\n| `/sync-init` | Bootstrap `.ai-sync/` in the current project |\n| `/handoff` | Save state before switching agents (with conflict detection) |\n| `/sync-status` | Show current progress, next steps, session history |\n| `/sync-resume` | Load full context from last handoff and continue |\n| `/sync-diff` | Show all changes since last handoff |\n| `/sync-adapter <tool>` | Generate adapter file for a specific tool |\n| `/sync-transfer` | Import session context from another tool |\n| `/sync-hooks install\\|remove` | Install/remove git hooks |\n\n---\n\n## How It Works Under the Hood\n\n### When an agent starts work\n\n1. Reads `.ai-sync/HANDOFF.md` — knows what happened and what's next\n2. Reads `.ai-sync/PROGRESS.md` — knows which tasks are done vs pending\n3. Reads `.ai-sync/PLAN.md` — follows the implementation plan\n\n### While working\n\n- Checks off completed tasks in `PROGRESS.md`\n- Documents blockers in `HANDOFF.md` immediately\n\n### When stopping\n\n1. **Conflict detection** — checks if another agent modified `HANDOFF.md` during the session\n2. **Auto-progress** — cross-references changed files against plan tasks and auto-checks `PROGRESS.md`\n3. **State capture** — writes `HANDOFF.md` with completed work, specific next steps, and build status\n4. **Session log** — creates a timestamped log in `.ai-sync/sessions/`\n\n### The five rules all agents follow\n\n1. **Follow the plan** — No unplanned features or refactors\n2. **Don't repeat work** — Check `PROGRESS.md` before starting anything\n3. **Be specific in handoffs** — \"Create `api/auth.ts` with OAuth flow\" not \"Continue auth work\"\n4. **Run verification** — Build and typecheck before stopping\n5. **Document decisions** — The next agent has zero context about why you made choices\n\n---\n\n## Supported Tools\n\n| Tool | Adapter | How it picks up context |\n|------|---------|------------------------|\n| **Claude Code** | Plugin + CLAUDE.md | Full integration: slash commands, auto-load on start, reminder on stop |\n| **Cursor** | `.cursorrules` | Reads `.ai-sync/HANDOFF.md` via rules file |\n| **OpenAI Codex** | `AGENTS.md` | Reads `.ai-sync/HANDOFF.md` via agents file |\n| **Cline** | `.clinerules` | Reads `.ai-sync/HANDOFF.md` via rules file |\n| **Windsurf** | `.windsurfrules` | Reads `.ai-sync/HANDOFF.md` via rules file |\n| **Aider** | `.aider.conf.yml` | Reads `.ai-sync/HANDOFF.md` via config |\n| **OpenCode** | `AGENTS.md` | Reads `.ai-sync/HANDOFF.md` via agents file |\n| **Continue.dev** | `.continuerules` | Reads `.ai-sync/HANDOFF.md` via rules file |\n| **GitHub Copilot** | `.github/copilot-instructions.md` | Reads `.ai-sync/HANDOFF.md` via instructions |\n\n---\n\n## Key Features\n\n- **Conflict detection** — Warns if another agent modified `HANDOFF.md` while you were working\n- **Auto-progress tracking** — Automatically checks off tasks when their output files are modified\n- **Build-state awareness** — Records whether the last agent left a clean or broken build\n- **Session audit trail** — Every agent session is logged with timestamps and decisions\n- **Zero lock-in** — Pure Markdown + YAML protocol. No proprietary format, no vendor lock-in\n\n---\n\n## Also Available As\n\n| Package | Description | Install |\n|---------|-------------|---------|\n| [`@oreolion/ai-sync`](https://www.npmjs.com/package/@oreolion/ai-sync) | CLI (this package) | `npm install -g @oreolion/ai-sync` |\n| `@oreolion/ai-sync-mcp` | MCP server for MCP-native tools | See [`packages/mcp-server/`](packages/mcp-server/) |\n| `ai-sync` (VS Code) | VS Code extension with sidebar UI | See [`packages/vscode-extension/`](packages/vscode-extension/) |\n| `ai-sync-action` | GitHub Action for CI/CD | See [`packages/github-action/`](packages/github-action/) |\n| `@oreolion/ai-sync-remote` | Cloudflare Workers API for teams | See [`packages/remote-sync/`](packages/remote-sync/) |\n| `@oreolion/ai-sync-dashboard` | Next.js analytics dashboard | See [`packages/dashboard/`](packages/dashboard/) |\n\n---\n\n## Plugin Structure (for contributors)\n\n```\nai-sync-plugin/\n├── .claude-plugin/\n│   └── plugin.json              # Plugin manifest\n├── commands/                    # Slash command definitions\n│   ├── sync-init.md\n│   ├── handoff.md\n│   ├── sync-status.md\n│   ├── sync-resume.md\n│   ├── sync-diff.md\n│   ├── sync-adapter.md\n│   ├── sync-transfer.md\n│   └── sync-hooks.md\n├── skills/\n│   └── ai-sync-protocol/\n│       └── SKILL.md             # Protocol spec (auto-loaded when .ai-sync/ exists)\n├── hooks/\n│   └── hooks.json               # Session start/stop hooks\n├── packages/                    # Standalone packages (CLI, MCP, VS Code, etc.)\n├── tests/\n│   └── validate-plugin.sh\n├── CONTRIBUTING.md\n├── ROADMAP.md\n└── LICENSE\n```\n\n## Protocol Specification\n\nThe 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.\n\n## Testing\n\n```bash\nbash tests/validate-plugin.sh\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 12307,
  "sha": "dc3065e31eebbb68547d97a1a82229053f8452cc16e804797ffc6a364af017ee",
  "repo_slug": "oreolion/ai-sync-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_oreolion_ai_sync_plugin_ai_sync_28516a33/readme"
}