cowork-sync

The problem

A small team edits one codebase with Claude Code. Pushes and pulls collide, so the team takes turns: one person finishes, pushes and says so, and the next person pulls. What the team wants is closer to a shared spreadsheet: everyone works in the same files at once, and each person’s Claude knows what the others are touching.

cowork-sync covers the first part of that. Each teammate works on their own PC, in their own clone, with their own Claude Code session, on one branch of one repository. When someone saves a file, the change reaches everyone else’s working tree.

The second part, each person’s Claude knowing what the others are touching, is planned and not in this preview. Today Claude does not know about the sync; its edits sync like any other saved file.

Who the preview is for: people who want to try live sync on a test repository with a private remote. It is not for production repositories or public repositories.

How it works

Each clone runs one background process, the daemon. The daemons share work through two custom refs on the git remote you already use. Nothing else is in the path: there is no server.

What happens when you save a file

1. You save a file, from Claude Code or any editor. The daemon in your clone picks it up. It reads through its own private git index and never touches yours.
2. It publishes the change to your remote. refs/cowork/<branch>/board is a fast-forward-only chain of board commits and is the authority; refs/cowork/<branch>/code mirrors the latest shared tree.
3. Every push is a fast-forward guarded by a lease (--force-with-lease), so no PC can overwrite another’s update. When two PCs push at once, the one that loses fetches and tries again.
4. Teammates’ daemons fetch the change and merge it with git merge-tree, using explicit merge bases.
5. Each daemon writes the result into its working tree. A file is written only if it still holds the bytes the daemon last read, so an edit you just saved is never overwritten. A group of files is written all or none.

Details that matter

• When two people change the same line, one version wins. The other is kept as a hold record in the clone and is never thrown away. The preview has no command yet to see or restore it.
• The preview never pushes to your branch (refs/heads/<branch>). A plain git fetch does not download the custom refs, so your normal history stays clean.
• Settings, hooks and CI files (.claude/, CLAUDE.md, .github/workflows/, .gitattributes and similar) never sync live. They move only through ordinary git commits.
• New files with secret-like names (.env, *.pem, *.key, id_rsa*, *credentials* and more) are not shared. New files over 1 MiB are not shared, and files of 50 MiB or more never sync live.
• The team shares a push budget of 12 pushes a minute, 6 for half an hour after any throttling, to keep the load on the host low. The daemon’s loop runs every 2.5 s when active and every 10 s when idle.
• Git commands that move HEAD (commit, switch, checkout, pull, merge, rebase, stash) freeze sync until HEAD is back. Stop sync before you run them. If the board’s history is ever rewritten, every PC freezes until it is recovered.

What leaves your PC

• Where it goes: only to your clone’s own git remote, through git. The daemon runs git as child processes with git’s prompts turned off, and its bundle loads no Node network module.
• What is sent: the paths and contents of the files you save that are in sync scope, plus board commits. Anyone who can read the repository can fetch them, and the preview does not check that the remote is private.
• Your name: shared commits carry a display name: --name if you pass it, else your git user.name, else “cowork peer”. The commit address is a placeholder, not your git e-mail.
• Join record: when a PC joins the board, the board records its display name, the plugin version, a hash of the plugin, the protocol number, the core.autocrlf setting and hashed fingerprints of the repository’s filter drivers (no paths). When the first PC starts sync, the daemon also pushes a short-lived probe ref to test the host, then deletes it.
• What stays on your PC: .git/cowork/status.json, the daemon log (.git/cowork/log/daemon-0.jsonl), hold records, and the optional read-only viewer, which listens on 127.0.0.1 only.
• The design rules out telemetry, crash reporting, update checks and analytics, and a source lint bans Node network modules everywhere except the viewer’s local server. This is a design rule plus a lint, not an independent audit.

Requirements and commands

What you need

• Claude Code 2.1.270 or newer.
• Node.js 20 or newer on PATH.
• git 2.43 or newer. start refuses an older git.
• Windows, macOS or Linux.
• A private git remote that accepts custom refs (refs/cowork/*) and enforces --force-with-lease. GitHub does both. The first PC’s start probes the host and refuses one that does not.
• Credentials from a git credential helper. Git’s prompts are off, so a missing credential gives a refusal, not a hang.
• Every PC that takes part installs the plugin and has its own clone, with .git on the same volume as the work tree.

Commands

Claude Code names the plugin’s command /cowork-sync:cowork; type that name in full. The same verbs also run in a terminal, as node "<plugin folder>/dist/cli.js" <verb>; /cowork-sync:cowork view prints that path.

start also takes --publish=all|none (at the first start, share or keep your uncommitted local work), --remote <name> and --name <display name>.

When a command refuses, it prints the reason with a code, and a next: line with the command to run.

What start checks

• It runs in the main clone. A linked worktree or a submodule is refused.
• The branch is checked out, exists on the remote, and is neither ahead of nor behind it. No merge or rebase may be in progress.
• The remote’s fetch URL equals its push URL, and no insteadOf rewrite applies.
• Only one daemon runs per clone.
• If you have uncommitted changes at the first start, it asks you to choose: share them with the team, or keep them on this PC.

Update, remove, clean up

Updates are not automatic for this marketplace. To update, run /plugin marketplace update cowork-sync, then claude plugin update cowork-sync@cowork-sync. To remove the plugin, run claude plugin uninstall cowork-sync@cowork-sync.

Stopping sync or uninstalling the plugin leaves the custom refs on the remote. After every PC has stopped, you can delete them by hand, for example:

git push origin --delete refs/cowork/main/board refs/cowork/main/code

What works today, and the preview’s limits

Roadmap

Planned for v1, the first full public release. These are plans; no dates are set.

• Holds and change-sets: see and restore hold records, a mass-change breaker, a revert detector.
• Function-level claims: Python, JS/TS and C# by symbol, other text files by block.
• Claude Code integration: hooks, an edit gate, MCP tools and local IPC.
• Claude-to-Claude coordination: conflict flows, requests and answers, notifications to sessions.
• The full command set: start, stop, pause, resume, save, adopt, recover, uninstall, status, doctor; a check that the remote is private; a secrets scanner; messages in six languages.
• Sync tied to a session: sync while a Claude Code session is open, or for a set time with /cowork start --human <minutes>. Public remotes refused.
• Hosts: GitHub, GitLab and Gitea, once the start probe confirms custom refs and leases.
• Viewer 2: view as a slash command, six-language catalogs, WebM and GIF export, a highlight reel. Its last task is the first full public release.
• Before host-dependent work ships: a second PC on another network, a 24-hour credential run with a forced sign-out, and interactive terminal and VS Code runs.

The developer notes in docs/STATUS.md list what is done and what comes next.

Licence, in plain words

cowork-sync is source-available under the Functional Source License 1.1, with the Apache License 2.0 as its future licence (FSL-1.1-ALv2). Copyright 2026 Youngmin Seo.

• You may use, copy, change and share it for any purpose except a competing use.
• A competing use means offering it, or something that does substantially the same thing, to others as a commercial product or service.
• Internal use, non-commercial education, non-commercial research, and professional services for a licensee are allowed.
• Each release becomes available under the Apache License 2.0 two years after it is released.
• There is no warranty, and the licence grants no trademark rights.
• Contributions need the contributor licence agreement (CLA). You agree to it with a comment on your pull request.

This summary is not the licence. Read LICENSE.md for the terms, the official FSL-1.1-ALv2 text from fsl.software, and CONTRIBUTING.md for the CLA.

Frequently asked questions