cowork-sync

해결하려는 문제

작은 팀이 Claude Code로 코드베이스 하나를 함께 고칩니다. push와 pull이 자꾸 부딪히니 팀은 차례를 정해 일하게 됩니다. 한 사람이 일을 끝내고 push 한 뒤 알리면, 다음 사람이 pull 하는 식입니다. 팀이 바라는 건 공유 스프레드시트에 가까운 경험입니다. 모두가 같은 파일에서 동시에 일하고, 각자의 Claude는 다른 사람이 무엇을 고치고 있는지 아는 것이죠.

cowork-sync는 그중 앞부분을 다룹니다. 팀원은 각자 자기 PC에서, 자기 클론으로, 자기 Claude Code 세션을 띄워 저장소 하나의 브랜치 하나에서 일합니다. 누군가 파일을 저장하면 그 변경이 다른 모든 사람의 작업 트리에 전달됩니다.

뒷부분인 ‘각자의 Claude가 다른 사람이 무엇을 고치고 있는지 아는 것’은 계획 단계이며 이번 미리보기에는 없습니다. 지금은 Claude가 동기화를 알지 못하고, Claude의 수정도 다른 저장된 파일과 똑같이 동기화됩니다.

이번 미리보기의 대상: 비공개 원격 저장소를 둔 테스트용 저장소에서 실시간 동기화를 시험해 보려는 사람입니다. 실제 운영 중인 저장소나 공개 저장소에는 맞지 않습니다.

동작 방식

클론마다 백그라운드 프로세스(데몬)가 하나씩 돌아갑니다. 데몬들은 이미 쓰고 있는 git 원격 저장소의 사용자 지정 ref 두 개로 작업을 주고받습니다. 그 사이에 끼는 별도 서버는 없습니다.

파일을 저장하면 일어나는 일

1. Claude Code든 다른 편집기든, 파일을 저장합니다. 내 클론의 데몬이 이를 감지합니다. 데몬은 자기만의 비공개 git 인덱스로 파일을 읽으며, 내 인덱스는 건드리지 않습니다.
2. 데몬이 변경을 원격 저장소에 올립니다. refs/cowork/<branch>/board는 fast-forward로만 이어지는 보드 커밋 체인이자 기준 기록이고, refs/cowork/<branch>/code는 가장 최근 공유 트리의 미러입니다.
3. 모든 push는 리스(--force-with-lease)로 보호되는 fast-forward입니다. 그래서 어떤 PC도 다른 PC의 갱신을 덮어쓸 수 없습니다. 두 PC가 동시에 push 하면, 진 쪽이 다시 fetch 한 뒤 재시도합니다.
4. 팀원들의 데몬이 변경을 fetch 하고, 명시적인 병합 기준(merge base)을 지정해 git merge-tree로 병합합니다.
5. 각 데몬이 결과를 자기 작업 트리에 씁니다. 파일은 데몬이 마지막으로 읽은 바이트 그대로일 때만 써지므로, 방금 저장한 내 수정이 덮어써지는 일은 없습니다. 파일 묶음은 전부 쓰거나 전혀 쓰지 않습니다.

알아 둘 점

• 두 사람이 같은 줄을 바꾸면 한 버전이 이깁니다. 다른 버전은 클론에 보류(hold) 기록으로 보관되며 버려지지 않습니다. 다만 미리보기에는 이를 보거나 되살리는 명령이 아직 없습니다.
• 미리보기는 내 브랜치(refs/heads/<branch>)에 절대 push 하지 않습니다. 일반 git fetch는 사용자 지정 ref를 내려받지 않으므로 평소의 git 이력은 깨끗하게 유지됩니다.
• 설정, 훅, CI 파일(.claude/, CLAUDE.md, .github/workflows/, .gitattributes 등)은 실시간으로 동기화되지 않습니다. 이런 파일은 평소처럼 git 커밋으로만 옮겨집니다.
• 비밀 정보처럼 보이는 이름의 새 파일(.env, *.pem, *.key, id_rsa*, *credentials* 등)은 공유되지 않습니다. 1 MiB를 넘는 새 파일도 공유되지 않고, 50 MiB 이상인 파일은 실시간으로 동기화되지 않습니다.
• 호스트 부하를 낮추려고 팀 전체가 push 예산을 나눠 씁니다. 분당 12회, 제한이 걸린 뒤 30분 동안은 6회입니다. 데몬의 루프는 활동 중일 때 2.5초, 한가할 때 10초마다 돌아갑니다.
• HEAD를 움직이는 git 명령(commit, switch, checkout, pull, merge, rebase, stash)을 실행하면 HEAD가 제자리로 돌아올 때까지 동기화가 멈춥니다(freeze). 이런 명령은 동기화를 중지한 뒤 실행하세요. 보드의 이력이 다시 쓰이는 일이 생기면, 복구될 때까지 모든 PC의 동기화가 멈춥니다.

내 PC 밖으로 나가는 것

• 가는 곳: 내 클론의 git 원격 저장소 하나뿐이며, git을 통해서만 갑니다. 데몬은 git의 입력 프롬프트를 끈 채로 git을 자식 프로세스로 실행하고, 데몬 번들은 Node 네트워크 모듈을 하나도 불러오지 않습니다.
• 보내는 것: 동기화 범위 안에서 내가 저장한 파일의 경로와 내용, 그리고 보드 커밋. 저장소를 읽을 수 있는 사람은 누구나 이를 가져갈 수 있으며, 미리보기는 원격 저장소가 비공개인지 확인하지 않습니다.
• 내 이름: 공유 커밋에는 표시 이름이 붙습니다. --name을 주면 그 이름, 아니면 git user.name, 그것도 없으면 “cowork peer”입니다. 커밋의 이메일 주소 칸에는 임의로 만든 값이 들어가며, 내 git 이메일은 쓰지 않습니다.
• 참여 기록: PC가 보드에 참여하면 표시 이름, 플러그인 버전, 플러그인 해시, 프로토콜 번호, core.autocrlf 설정값, 저장소 필터 드라이버의 해시 지문(경로는 담지 않음)이 보드에 남습니다. 첫 PC가 동기화를 시작할 때는 호스트를 확인하려고 잠깐 쓰는 확인용 ref를 push 했다가 지웁니다.
• 내 PC에 남는 것: .git/cowork/status.json, 데몬 로그(.git/cowork/log/daemon-0.jsonl), 보류 기록, 그리고 127.0.0.1에서만 접속을 받는 읽기 전용 뷰어(선택).
• 설계상 텔레메트리, 오류 보고, 업데이트 확인, 분석은 두지 않으며, 소스 린트가 뷰어의 로컬 서버를 뺀 모든 곳에서 Node 네트워크 모듈을 막습니다. 설계 규칙과 린트일 뿐, 독립적인 감사를 받은 것은 아닙니다.

요구 사항과 명령

필요한 것

• Claude Code 2.1.270 이상.
• Node.js 20 이상(PATH에서 실행할 수 있어야 함).
• git 2.43 이상. 더 낮은 git이면 start가 거부합니다.
• Windows, macOS 또는 Linux.
• 사용자 지정 ref(refs/cowork/*)를 받아 주고 --force-with-lease를 실제로 적용하는 비공개 git 원격 저장소. GitHub는 둘 다 됩니다. 첫 PC의 start가 호스트를 확인해 보고, 조건에 맞지 않으면 거부합니다.
• git 자격 증명 도우미(credential helper)에서 가져오는 자격 증명. git의 입력 프롬프트가 꺼져 있으므로, 자격 증명이 없으면 응답 없이 멈추는 대신 거부 메시지가 나옵니다.
• 참여하는 모든 PC에 플러그인을 설치하고 각자 자기 클론을 둡니다. .git은 작업 트리와 같은 볼륨에 있어야 합니다.

명령

Claude Code는 플러그인의 명령 이름을 /cowork-sync:cowork로 붙이므로, 이 이름을 전부 입력하세요. 같은 동작을 터미널에서도 node "<플러그인 폴더>/dist/cli.js" <동작> 형태로 실행할 수 있으며, /cowork-sync:cowork view가 그 경로를 출력해 줍니다.

start는 --publish=all|none(처음 시작할 때 커밋하지 않은 로컬 작업을 공유할지, 이 PC에 둘지), --remote <name>, --name <display name>도 받습니다.

명령이 거부될 때는 코드가 붙은 이유와, 실행할 명령이 적힌 next: 줄을 출력합니다.

start가 확인하는 것

• 메인 클론에서 실행해야 합니다. 연결된 워크트리(linked worktree)나 서브모듈은 거부합니다.
• 브랜치가 체크아웃되어 있고, 원격 저장소에 있으며, 원격보다 앞서거나 뒤처지지 않아야 합니다. 병합이나 리베이스가 진행 중이어도 안 됩니다.
• 원격의 fetch URL과 push URL이 같아야 하고, insteadOf 재작성이 적용되지 않아야 합니다.
• 클론마다 데몬은 하나만 돌 수 있습니다.
• 처음 시작할 때 커밋하지 않은 변경이 있으면 선택을 묻습니다. 팀과 공유할지, 이 PC에만 둘지 고르세요.

업데이트, 제거, 정리

이 마켓플레이스는 자동으로 업데이트되지 않습니다. 업데이트하려면 /plugin marketplace update cowork-sync를 실행한 뒤 claude plugin update cowork-sync@cowork-sync를 실행하세요. 플러그인을 지우려면 claude plugin uninstall cowork-sync@cowork-sync를 실행합니다.

동기화를 중지하거나 플러그인을 지워도 원격 저장소의 사용자 지정 ref는 남습니다. 모든 PC가 멈춘 뒤에 직접 지울 수 있습니다. 예:

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

지금 되는 것과 미리보기의 한계

로드맵

첫 정식 공개 릴리스인 v1을 목표로 한 계획입니다. 계획일 뿐이며 날짜는 정해져 있지 않습니다.

• 보류와 변경 묶음: 보류 기록 보기와 되살리기, 대량 변경 차단기, 되돌림 감지기.
• 함수 단위 선점: Python, JS/TS, C#은 심볼 단위로, 그 밖의 텍스트 파일은 블록 단위로.
• Claude Code 연동: 훅, 편집 게이트, MCP 도구, 로컬 IPC.
• Claude 간 협업: 충돌 처리 흐름, 요청과 응답, 세션에 보내는 알림.
• 전체 명령: start, stop, pause, resume, save, adopt, recover, uninstall, status, doctor. 원격 저장소 비공개 확인, 비밀 정보 검사, 6개 언어 메시지.
• 세션에 묶인 동기화: Claude Code 세션이 열려 있는 동안, 또는 /cowork start --human <minutes>로 정한 시간 동안만 동기화. 공개 원격 저장소는 거부.
• 호스트: GitHub, GitLab, Gitea. 시작할 때 사용자 지정 ref와 리스 지원이 확인되는 경우에 한합니다.
• 뷰어 2: 슬래시 명령으로 쓰는 view, 6개 언어, WebM과 GIF 내보내기, 하이라이트 모음. 뷰어 2의 마지막 작업이 첫 정식 공개 릴리스입니다.
• 호스트에 따라 달라지는 작업을 내놓기 전에 할 시험: 다른 네트워크에 있는 두 번째 PC, 강제 로그아웃을 포함한 24시간 자격 증명 시험, 대화형 터미널과 VS Code에서의 시험.

끝난 일과 다음 일은 개발자 노트 docs/STATUS.md(영어)에 있습니다.

라이선스, 쉬운 말로

cowork-sync는 소스 공개형(source-available)이며, Functional Source License 1.1에 미래 라이선스로 Apache License 2.0을 붙인 FSL-1.1-ALv2를 따릅니다. 저작권 2026 Youngmin Seo.

• 경쟁 목적의 사용만 빼면 어떤 목적으로든 사용, 복사, 수정, 공유할 수 있습니다.
• 경쟁 목적의 사용이란 이 소프트웨어, 또는 본질적으로 같은 일을 하는 것을 상용 제품이나 서비스로 다른 사람에게 제공하는 것을 말합니다.
• 내부 사용, 비상업적 교육과 연구, 라이선스를 받은 사람을 위한 전문 서비스는 허용됩니다.
• 각 릴리스는 공개된 지 2년 뒤부터 Apache License 2.0으로 이용할 수 있습니다.
• 보증은 없으며, 상표권은 주지 않습니다.
• 기여하려면 기여자 라이선스 계약(CLA)이 필요합니다. 풀 리퀘스트에 댓글을 달아 동의합니다.

이 요약은 라이선스 자체가 아닙니다. 조건은 LICENSE.md(영어)에 있으며, 이 파일은 fsl.software의 공식 FSL-1.1-ALv2 원문입니다. CLA는 CONTRIBUTING.md에 설명되어 있습니다.

자주 묻는 질문