winget install --id=Monkey1Wizard.ccync -e ccync is a standalone cross-agent plugin / MCP / skills manager. Install a plugin (or adopt a master agent's setup) once, and ccync projects it onto every coding agent's native surface — Claude Code, Codex, GitHub Copilot, Gemini CLI, OpenCode, and Antigravity. The `ccync` binary provides init, sync, add, remove, list, doctor, backup, restore, and uninstall commands.
English | 繁體中文
A cross-agent plugin, MCP, and skills manager. Install a plugin once and project it to every coding agent you use, including Claude Code, GitHub Copilot, Codex, Antigravity, Gemini, and OpenCode.
ccync serves as the management component of a broader ecosystem. It handles arbitrary third-party plugins, MCP servers, and skills, ensuring they remain consistent across all your agents. (The workflow counterpart is maintained as a separate product.)
> Status: Alpha. Core plugin management—including resolution, git cloning, caching, pinning, and cross-agent adoption/reconciliation—is fully functional. Projection of installed plugins onto every agent's skill, command, agent, and MCP surface is implemented and available.
curl -fsSL https://raw.githubusercontent.com/monkey1wizard/ccync/main/packaging/install.sh | bash
irm https://raw.githubusercontent.com/monkey1wizard/ccync/main/packaging/install.ps1 | iex
Both scripts verify the binary against checksums.txt (SHA-256 is mandatory, while cosign verification is best-effort).
The binary is installed to ~/.local/bin on macOS/Linux, or %USERPROFILE%\.local\bin on Windows.
winget (Windows): winget install Monkey1Wizard.ccync
Homebrew (macOS/Linux):
brew tap monkey1wizard/tap
brew install ccync
cargo install --git https://github.com/monkey1wizard/ccync
This installs directly to ~/.cargo/bin/ccync without requiring a manual clone.
If you need the source tree (e.g., for development):
git clone https://github.com/monkey1wizard/ccync.git
cd ccync
cargo build --release # Produces target/release/ccync
Next, add the built binary to your PATH:
cp target/release/ccync ~/.local/bin/target\release\ccync.exe to a directory included in your PATH.Verify the installation:
ccync --version # Outputs: ccync x.y.z
# 1. Initial setup: Select a master agent and adopt its plugins and MCP configuration.
ccync init claude # Skips master prompt; shows agent multi-select, then projects immediately.
# 2. Project everything to all selected agents.
ccync sync
# 3. Add a third-party plugin. Accepts a git URL, local path, archive, or catalog ID.
ccync add https://github.com// # Git URL
ccync add /path/to/plugin # Local path (git copy or plain dir)
ccync add plugin-v1.tar.gz # Archive (.zip / .tar.gz)
ccync add my-catalog-plugin # Bare catalog ID
# 4. List all managed items (personal and adopted).
ccync list
> First Run: ccync init guides you through an interactive master-agent selection and agent multi-select (defaults: claude, codex, copilot), then shows the same grouped touch-scope disclosure as any other first projection (selected agent surfaces + the four fixed MCP host files) before projecting to the selected agents immediately — no second confirmation prompt, since the agent-selection UI already served as the intent signal. In non-interactive shells, supply the master explicitly (ccync init claude); agent defaults are applied automatically.
ccync's own state (config, lockfile, cache, canonical render) is maintained in ~/.ccync/ (a hidden, machine-local directory). ccync also projects that state onto each selected agent's live config surface outside ~/.ccync/ — ~/.claude/skills/..., ~/.claude.json, ~/.codex/config.toml, ~/.copilot/mcp-config.json, and equivalents for the other supported agents — which fulfills the core principle of "install once, project everywhere."
| Command | Description |
|---|---|
ccync init [] | Performs the initial setup by selecting a master agent and adopting its plugins/MCP. |
ccync sync [--dry-run] [--yes] | The projection engine. Resolves the catalog, renders it, and projects skills, commands, agents, and MCP configurations to every agent. Use --yes to skip the first-run confirmation. --dry-run skips every live-surface write it reports on, but a one-time internal layout migration under ~/.ccync/ always runs first and is not gated by --dry-run — migration may precede the preview. |
ccync add [--no-sync] [--yes] | Adds a personal plugin from any supported source (git URL, local path, .zip/.tar.gz archive, or catalog ID) and automatically synchronizes. |
ccync remove [--yes] | Removes a managed item (personal or adopted) and automatically synchronizes. |
ccync list [--upgrade-available] | Lists installed managed items (personal and adopted); with --upgrade-available, a read-only outdated check printing current → latest (exit 3 when updates exist, 0 when none, 1 on error). |
ccync show | Prints full detail of one installed plugin (source, strategy, pinned sha, held, component count). Mirrors brew info / winget show. |
ccync doctor | Runs a read-only management health check. |
ccync backup / ccync restore | Exports or imports machine-local state. |
ccync uninstall | Reverses ccync's projections (live MCP / marketplace / skill·command·agent surfaces) and removes derived ~/.ccync/ state, preserving config.json + plugins.json and never editing PATH. See the manual. |
ccync update [--check] | Self-updates the ccync binary (Homebrew brew update semantics). Self-replaces only a curl/irm install; refuses and redirects under Homebrew/winget/cargo. --check reports versions without writing. |
Run ccync --help for the complete command surface.
Catalog (plugins/catalog.json): The curated collection of installable plugins and profiles. This is a repo/build-time source embedded into the ccync binary at build — not a live file on disk under ~/.ccync/.
Resolution (executed during ccync sync): Merges the catalog, machine configuration, and personal catalog to generate ~/.ccync/build/lock.json.
Universal Install: ccync add accepts four types of sources—git URLs, local paths, archives (.zip / .tar.gz), and bare catalog IDs—using a single command and unified fetching pipeline. A local path routes by filesystem identity: a directory containing .git (working copy or linked worktree) is fetched like a Git source and stays upgradeable; a plain directory with no .git is fetched as an immutable content snapshot, pinned by a SHA-256 hash of its contents like an archive, and refreshed via ccync remove + ccync add rather than ccync upgrade. Catalog IDs are resolved to their underlying source before fetching. All sources are stored in ~/.ccync/cache/@/.
Canonical Root: render_canonical_root copies the skills/, commands/, agents/, and hooks/ subdirectories of every managed plugin into ~/.ccync/build/render/, and merges .mcp.json entries. During every re-rendering (including after ccync remove), stale component directories are pruned first.
Hooks: Plugins that provide hooks/hooks.json have their hooks materialized into the canonical root alongside skills/commands/agents. Claude Code can load them via a session-scoped claude --plugin-dir invocation — ccync does not execute hooks or register them with Claude automatically. Since non-Claude agents (Codex, Gemini CLI, OpenCode) lack a hook surface for CC-plugins, hooks are simply inapplicable (not missing) for them.
Projection (executed during ccync sync): The projection engine writes each plugin's skills, commands, agents, and MCP settings into every selected agent's native configuration format.
First-Run Gate: On a new machine without prior projections, ccync sync, ccync add, and ccync remove all share this gate — they show a grouped touch-scope disclosure (selected agent surfaces, previewed as "would touch"; the four fixed MCP host files, labeled "may be written" — skipped when already identical) and request confirmation before writing ( needs to bypass it non-interactively, same as /). Use or set the environment variable for non-interactive execution. shows this same grouped disclosure right after its own agent-selection UI, but skips the — not the disclosure itself — because the agent multi-select already served as the intent signal. runs the gate but always passes , so it auto-confirms without prompting. For , the live-surface render/projection happens strictly the gate passes — a declined gate leaves catalog/cache/lockfile writes in place but produces zero live-surface writes.
For details on the crate hierarchy, refer to docs/architecture.md. For a comprehensive command reference, see docs/manual.md.
| macOS / Linux | Windows | |
|---|---|---|
| Home Directory Env | HOME | USERPROFILE |
| ccync Home | ~/.ccync | %USERPROFILE%\.ccync |
| Binary | ccync | ccync.exe |
| PATH Installation | ~/.local/bin | %USERPROFILE%\.local\bin (or any directory on your PATH) |
~/.ccync is a hidden directory. You can navigate to it using cd ~/.ccync on any OS, or by enabling "show hidden files" in your file manager.
ccync: command not found — The binary is not in your PATH. Review the Install section or run it using its absolute path (e.g., ./target/release/ccync).Failed to parse : ... — One of ccync's JSON state files (e.g. ~/.ccync/plugins.json or ~/.ccync/build/lock.json) is malformed. Fix or remove the offending file; ~/.ccync/build/ is fully rebuildable via ccync sync, but ~/.ccync/plugins.json is machine-local input state — restore it from a ccync backup if you have one, or re-add your personal plugins.ccync list shows what's installed), then run ccync sync to (re-)project. If it still doesn't appear, run ccync doctor to check for a stale or missing canonical root.ccync doctor reports errors about the canonical root — This indicates a real staleness or integrity issue (e.g. the canonical root is out of date relative to the lockfile). Run ccync sync to rebuild it.add — ccync relies on your system's git. Ensure git is installed and the repository URL is accessible.ccync search to look it up on GitHub/GitLab; confirming a match delegates straight to ccync add. See the manual for exit codes and non-interactive output.This README serves as the entry point (installation → first plugin → synchronization). For further details:
ccync includes a small set of internal developer commands that are dispatchable but not listed in ccync --help. These are for use by ccync maintainers during development:
ccync refresh — Rebuild the derived layer (canonical render + agent projection) from existing ~/.ccync state without running the full sync lifecycle. Re-runs can shift generatedAt timestamps even when content is otherwise unchanged.ccync rollback — Roll back the ccync source repo to the latest stable release tag (v*) and rebuild derived outputs.See docs/devguide.md for full contracts, prerequisites, and guard conditions.
MIT.
ccync upgrade [] [--dry-run] | Upgrades installed git-source plugins (URL or local git working copy) to their latest commit (Homebrew brew upgrade semantics), then re-projects. Archives and plain local-directory snapshots have no upstream and are skipped — refresh those via ccync remove + ccync add. Default all; --dry-run shows the diff without writing. Held plugins are skipped. |
ccync cleanup [--dry-run] | Prunes orphaned ~/.ccync/cache/@ dirs left by upgrade (Homebrew brew cleanup semantics). Fail-closed: never deletes a live or undecidable dir. --dry-run lists only. |
ccync pin · --remove · --list | Prevents a plugin from being upgraded (winget-style pin; state in the held field — distinct from the pin/pinnedSha sha fields). |
ccync search [--limit N] [--no-add] | Looks up a plugin by name on GitHub/GitLab when you know its name but not its clone URL, then offers to delegate to ccync add. Never writes config.json or auto-binds a URL. |
remove--yessyncadd--yesCCYNC_ASSUME_YES=1ccync initccync upgradeassume_yes=trueaddInitialization Requirement: ccync sync, a projecting ccync add (no --no-sync), ccync remove, and a non-dry ccync upgrade all refuse with an error naming ccync init if ~/.ccync/config.json does not yet exist — the refusal happens before any domain mutation. Pre-init exceptions: ccync add --no-sync, ccync sync --dry-run, ccync upgrade --dry-run, ccync init itself, and the pre-init-available commands (list, show, doctor, search, backup, restore, pin, update --check) all stay available before ccync init has run.
| Command | Requires prior ccync init? | Pre-init exception |
|---|---|---|
ccync init [] | No — this is the initializing command | always available |
ccync sync | Yes | --dry-run |
ccync add | Yes, when projecting | --no-sync |
ccync remove | Yes | none |
ccync upgrade [] | Yes, when applying | --dry-run |
pre-init-available commands (list, show, doctor, search, backup, restore, pin, update --check) | No | always available |