sync-agenta

Wersja 2.1.4 · historia zmian

Skill dla Claude Code, który trzyma tę samą konfigurację agenta na wszystkich Twoich maszynach — komputerze (macOS lub Windows) i serwerze VPS z Linuksem. Przez prywatne repozytorium na GitHubie, bez ręcznego kopiowania plików.

Synchronizuje: CLAUDE.md, skille, komendy, reguły, hooki, agentów, ustawienia, listę wtyczek i pamięć projektów.

Po co to komuś

Konfigurujesz agenta na laptopie: piszesz skille, dodajesz hooki, uczysz go swoich reguł. Potem stawiasz VPS, żeby agent pracował, gdy Ty śpisz — i okazuje się, że tam jest gołe Claude Code, które nic o Tobie nie wie. Albo pracujesz na dwóch komputerach i ciągle nie wiesz, na którym jest nowsza wersja skilla.

Ten skill to załatwia: konfiguracja jedzie do prywatnego repozytorium, a każda maszyna pobiera ją przy starcie sesji i odsyła zmiany po jej zakończeniu. Na serwerze robi to harmonogram (cron).

Czego potrzebujesz

• Claude Code
• node w wersji 22 lub nowszej, git
• gh — narzędzie GitHuba, zalogowane (gh auth login --web --git-protocol https)
• gitleaks — skaner pilnujący, żeby żadne hasło nie wyjechało do internetu
• claude-nomad — silnik synchronizacji: npm i -g [email protected]
• konto GitHub (darmowe wystarczy — prywatne repozytoria bez opłat)

Skrypt bin/check-prereqs.sh sprawdzi wszystko i dla każdego braku wypisze gotową komendę instalacji.

Instalacja

Dwa polecenia w Claude Code — nic nie klonujesz ręcznie:

/plugin marketplace add studiogo/sync-agenta
/plugin install sync-agenta@sync-agenta

Potem napisz: „zainstaluj synchronizację". Skill przeprowadzi Cię przez resztę — zapyta, czy ta maszyna to komputer, czy serwer, sprawdzi wymogi, założy prywatne repozytorium i pokaże pełną listę plików PRZED pierwszą wysyłką.

Kolejność ma znaczenie: najpierw komputer (on zasiewa repozytorium), dopiero potem serwer (on tylko pobiera).

Aktualizacja

/plugin update sync-agenta

To wszystko. Hooki niesie sam plugin, a Claude Code podstawia do nich aktualną ścieżkę — nowa wersja przejmuje automatykę bez żadnego wpinania. Zmiany zaczynają działać od następnego uruchomienia Claude Code.

Jak to działa

Dwie warstwy w jednym repozytorium:

• shared/ — obsługiwana przez claude-nomad: CLAUDE.md, skille, komendy, reguły, ustawienia
• custom/ — obsługiwana przez ten skill: hooki, agenci, lista wtyczek

Warstwa custom/ płynie w jedną stronę: komputer wysyła, VPS tylko pobiera. Bez tego dwie maszyny kasowałyby sobie nawzajem zmiany. Konsekwencja: hook dopisany ręcznie na serwerze zostanie nadpisany — twórz je na komputerze.

Automatyka na komputerze to trzy hooki Claude Code: pobranie przy starcie sesji, wysyłka po każdej zakończonej turze agenta (nie częściej niż raz na 5 minut) oraz wysyłka przy wyjściu z agenta — ta ostatnia bez ograniczenia częstotliwości, żeby plik utworzony w ostatniej minucie pracy nie został na maszynie. Na serwerze pracuje harmonogram co N minut, bo tam sesja agenta praktycznie się nie kończy.

Pełny opis mechanizmu, spisany z prawdziwych uruchomień: JAK-TO-DZIALA.md.

Bezpieczeństwo

Cztery bramki, każda sprawdzona testem:

bramka	co robi
zgoda przed pierwszą wysyłką	pokazuje pełną listę plików i czeka na Twoje „tak"
skaner sekretów	gitleaks skanuje przed każdą wysyłką; znaleziony klucz = wysyłka wstrzymana
kontrola prywatności	repozytorium musi być PRIVATE, inaczej skill się zatrzymuje
plik ponad 95 MB	wycofywany z wysyłki (GitHub odrzuca ~100 MB i blokuje repozytorium)

Nigdy nie jadą do repozytorium: .credentials.json, ~/.claude.json, settings.local.json, pliki .env, katalogi venv / node_modules.

Środowiska Pythona i Node (venv, node_modules) mieszkają poza katalogiem skilli, w ~/.claude/skill-envs/, a w skillu zostaje tylko dowiązanie. Dzięki temu synchronizacja ich nie kasuje i nie próbuje przenosić programów skompilowanych pod jeden system na drugi.

Odinstalowanie

W Claude Code napisz: „odinstaluj synchronizację" — skill uruchomi bin/uninstall.sh (Windows: uninstall.ps1) ze swojego katalogu. Potem możesz usunąć sam plugin: /plugin uninstall sync-agenta.

Deinstalator zdejmuje hooki i wpis z harmonogramu. Nie kasuje żadnych plików — konfiguracja, kopia repozytorium i samo repozytorium na GitHubie zostają. Kroki nieodwracalne (usunięcie repozytorium) wykonujesz sam, świadomie.

Stan testów

Sprawdzone uruchomieniem, nie tylko przeczytane:

• macOS — pełny obieg: wysyłka, pobranie, sześć scenariuszy awaryjnych, odinstalowanie.
• Linux (serwer) — instalacja, rozpoznanie roli serwera, praca z harmonogramu, odinstalowanie.
• Windows — cały obieg na żywo, wersja 2.1.4: instalacja z marketplace'u, hooki odpalane przez Claude Code, wysyłka zakończona commitem na GitHubie. Wcześniej sprawdzono też, że hook przy wyjściu z agenta dowozi plik utworzony chwilę wcześniej.

Niesprawdzone na żywo: instalacja od zera na konfiguracji większej niż 1 GB oraz Windows na fizycznym komputerze — tam sprawdzona jest sama mechanika, nie pełny przebieg instalacji. Problemy zgłaszaj przez Issues.

Ograniczenia

• Silnik claude-nomad jest przypięty do wersji 0.64.1 — aktualizuj świadomie, po nomad doctor.
• Repozytorium z ciężkimi skillami potrafi ważyć ponad 1 GB; na tanim VPS sprawdź miejsce przed pobraniem (skill to robi za Ciebie).
• Rozmowy i pamięć projektów jadą razem z konfiguracją — trzymaj repozytorium prywatne.

Zgłoszenia i zmiany

Znalazłeś usterkę albo masz uwagę: załóż zgłoszenie i wybierz szablon — utrata pliku, awaria instalacji, bramka bezpieczeństwa lub propozycja.

Nie wklejaj do zgłoszenia zawartości swojej konfiguracji ani kluczy. Nazwy plików i komunikaty błędów wystarczą.

Zanim wyślesz zmianę w kodzie, przeczytaj CONTRIBUTING.md — jest tam lista rzeczy, których autor świadomie nie przyjmie, i to, co sprawdzić przed zgłoszeniem. Obowiązuje Kodeks postępowania.

Licencja

MIT