SkillsCommandsConfigsSync - Unified YAML-configured synchronization for Claude Code files

These details have not been verified by PyPI

Project links

Project description

SCCS - SkillsCommandsConfigsSync

SCCS Overview

Language / Sprache: Deutsch | English

Deutsche Dokumentation

Projektübersicht

SCCS ist ein YAML-konfiguriertes bidirektionales Synchronisierungswerkzeug für Claude Code Dateien und optionale Shell-Konfigurationen. Es hält Skills, Commands, Hooks, Scripts und Shell-Configs zwischen einer lokalen Installation und einem Git-Repository synchron.

Version: 2.22.0 · Lizenz: AGPL-3.0 · Python: ≥3.10

Funktionen

YAML-Konfiguration — Zentrale config.yaml mit allen Sync-Kategorien
Flexible Kategorien — Claude Skills, Commands, Hooks, Scripts, Fish-Shell u.v.m.
Bidirektionale Synchronisierung — Zweiwege-Sync mit Konflikterkennung
Interaktive Konflikterkennung — Menügesteuerte Konfliktauflösung mit -i
Interaktive Divergenz-Auflösung — Menü (Rebase / Merge / Force-Push / Abort) wenn Branch von Remote abgewichen ist; CI-freundlich (auto-Abort ohne TTY)
Automatische Backups — Zeitgestempelte Sicherungen vor Überschreiben
Git-Integration — Auto-Commit und Push nach Synchronisierung
Plattform-Filter — Kategorien nur auf macOS, Linux oder beidem synchronisieren
Smart Conflict Resolution — --force newer löst Konflikte per Dateizeit (mtime)
Project Memories Sync — Claude's persistente Projekt-Memories synchronisieren
Selektiver Export/Import — ZIP-Archive mit Checkbox-Auswahl fuer Kundendeployments
Rich-Ausgabe — Formatierte Terminal-Ausgabe mit Rich
Memory Bridge — Persistenter Kontext zwischen Claude Code und Claude.ai via Git-Sync
Memory-CLI — Vollständige CRUD-Verwaltung mit sccs memory
Auto-Expire — Zeitgesteuerte Archivierung abgelaufener Memory-Items
Antigravity-Integration — Skills zu Antigravity IDE Prompts migrieren
Claude Desktop-Integration — Repository als Trusted Folder registrieren
sccs doctor — System & Plugin Health-Check für Node.js, claude CLI, Claude-Plugins und npx-Helper-Tools (plattformspezifisch: brew / winget / NodeSource-Manual)

Voraussetzungen

UV muss installiert sein:

Betriebssystem	Befehl
macOS	`brew install uv`
Linux / WSL	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
Windows	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

Installation

Als CLI-Tool (empfohlen):

uv tool install sccs

Aktualisierung:

uv tool upgrade sccs

UV aktualisieren:

# macOS
brew upgrade uv

# Linux / Windows
uv self update

Für Entwickler

git clone https://github.com/equitania/sccs.git
cd sccs
uv venv --python 3.13 && source .venv/bin/activate
uv pip install -e ".[dev]"
sccs --help

Workflows

Publisher (Änderungen teilen)

sccs sync --commit --push      # Synchronisieren, committen und pushen
sccs sync --dry-run             # Vorschau der Änderungen
sccs sync -c skills --push      # Nur Skills pushen

Subscriber (Änderungen empfangen)

sccs sync --pull                # Aktuelle Version ziehen und lokal synchronisieren
sccs sync --force repo          # Lokale Version mit Repo überschreiben
sccs sync -c skills --pull      # Nur Skills empfangen

Schnellstart

# Konfiguration erstellen
sccs config init

# Status anzeigen
sccs status

# Änderungen prüfen
sccs sync --dry-run

# Alles synchronisieren
sccs sync

# Bestimmte Kategorie synchronisieren
sccs sync -c claude_skills

Export/Import (Kundendeployment)

Konfigurationen selektiv als ZIP-Archiv exportieren und auf anderen Systemen importieren — ideal fuer Kundendeployments, bei denen nicht das gesamte Repository uebertragen werden soll.

Export

# Interaktive Auswahl per Checkbox
sccs export

# Alles exportieren (ohne Auswahl)
sccs export --all

# Eigenen Ausgabepfad angeben
sccs export -o ~/Desktop/kunde-config.zip

# Nur bestimmte Kategorien
sccs export -c claude_skills
sccs export -c claude_skills -c claude_agents

# Kombiniert: Nur Skills, ohne Interaktion
sccs export -c claude_skills --all -o skills.zip

Die interaktive Auswahl zeigt alle verfuegbaren Items gruppiert nach Kategorie mit Checkboxen:

? Select items to export (42 available):
  ── Claude Code Skills ──
  [✔] code-review
  [✔] git-workflow
  [ ] internal-tool
  ── Claude Agents ──
  [✔] code-reviewer
  ── Fish Shell (macos only) ──
  [✔] config.fish  (macos only)

Import

# Interaktive Auswahl, was importiert werden soll
sccs import config.zip

# Alles importieren
sccs import config.zip --all

# Vorschau ohne Schreiben
sccs import config.zip --dry-run

# Bestehende Dateien ueberschreiben (mit automatischem Backup)
sccs import config.zip --overwrite

# Ohne Backup ueberschreiben
sccs import config.zip --overwrite --no-backup

Einsatzbereiche

Szenario	Empfohlener Befehl
Skills an Kunden liefern	`sccs export -c claude_skills -o kunde.zip`
Fish-Config fuer Linux-Server	`sccs export -c fish_config -c fish_functions --all`
Komplett-Setup fuer neues System	`sccs export --all -o full-setup.zip`
Vorschau vor dem Import	`sccs import setup.zip --dry-run`
Sicheres Update bestehender Configs	`sccs import setup.zip --overwrite`

Konfiguration

Konfigurationsdatei: ~/.config/sccs/config.yaml

# Repository-Einstellungen
repository:
  path: ~/gitbase/sccs-sync      # Lokaler Repository-Pfad
  remote: origin                  # Git Remote Name
  auto_commit: false              # Auto-Commit nach Sync
  auto_push: false                # Auto-Push nach Commit
  auto_pull: false                # Auto-Pull vor Sync
  commit_prefix: "[SYNC]"         # Prefix für Commit-Nachrichten

# Sync-Kategorien
sync_categories:
  claude_skills:
    enabled: true
    description: "Claude Code Skills"
    local_path: ~/.claude/skills
    repo_path: .claude/skills
    sync_mode: bidirectional       # bidirectional | local_to_repo | repo_to_local
    item_type: directory           # file | directory | mixed
    item_marker: SKILL.md          # Marker-Datei für Verzeichnisse
    include: ["*"]
    exclude: ["_archive/*"]

  fish_config:
    enabled: true
    platforms: ["macos"]           # Nur auf macOS synchronisieren
    local_path: ~/.config/fish
    repo_path: .config/fish
    item_type: mixed
    include: ["config.fish", "functions/*.fish"]
    exclude: ["fish_history", "fish_variables"]

# Globale Ausschlüsse
global_exclude:
  - ".DS_Store"
  - "*.tmp"
  - "__pycache__"

Memory Bridge

Konzept

Claude Code (Terminal) und Claude.ai (Web) teilen keinen gemeinsamen Speicher. Der Memory Bridge löst dies file-basiert:

local: ~/.claude/memory/<slug>/MEMORY.md
↕ SCCS-Sync (bidirektional, via Git)
repo: .claude/memory/<slug>/MEMORY.md
→ Claude.ai:    sccs memory export  →  als <memory>...</memory> Block einfügen
→ Claude Code:  SessionStart-Hook lädt Memory automatisch als Context

Memory Item Format

Jedes Memory Item ist eine Datei MEMORY.md mit YAML-Frontmatter und Markdown-Body:

---
id: "project-odoo18-arch"
title: "Odoo 18 Architecture Decisions"
category: decision   # project|decision|learning|pattern|preference|reference|context
project: v18
tags: [odoo, architecture]
priority: 4          # 1 (niedrig) – 5 (kritisch)
created: "2026-02-23T10:00:00"
updated: "2026-02-23T14:30:00"
expires: null        # ISO datetime oder null
version: 1
---

# Odoo 18 Architecture Decisions

Inhalt in Markdown.

Konfiguration

Zwei neue Blöcke in ~/.config/sccs/config.yaml:

# 1. Memory-Kategorie (standardmäßig deaktiviert)
sync_categories:
  claude_memory:
    enabled: false           # Explizit aktivieren: sccs categories enable claude_memory
    description: "Claude Code <-> Claude.ai Memory Bridge"
    local_path: ~/.claude/memory
    repo_path: .claude/memory
    sync_mode: bidirectional
    item_type: directory
    item_marker: MEMORY.md
    conflict_resolution: newest   # Neuestes updated-Timestamp gewinnt
    exclude: ["_archive/*", "*.tmp"]

# 2. Memory-Einstellungen
memory_config:
  auto_expire: false           # Abgelaufene Items bei sccs sync archivieren
  max_context_chars: 8000      # Maximale Zeichen für SessionStart-Hook
  min_priority: 1              # Mindest-Priorität für Hook-Export
  max_age_days: null           # Maximales Alter (Tage), null = unbegrenzt

Lokale Einrichtung

# 1. Kategorie aktivieren
sccs categories enable claude_memory

# 2. Hook installieren (wird mit sccs sync -c claude_hooks synchronisiert)
#    Alternativ: hook direkt unter ~/.claude/hooks/load-memory.py ablegen

# 3. Hook in ~/.claude/settings.json eintragen (manuell!)

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{"type": "command", "command": "python3 ~/.claude/hooks/load-memory.py"}]
      }
    ]
  }
}

# 4. Optional: Anthropic API für Cloud-Sync (Files API)
uv pip install "sccs[memory]"
export ANTHROPIC_API_KEY="..."

# 5. Ersten Sync durchführen
sccs sync -c claude_memory

Wichtig: Das private Repository für Memory-Sync verwenden, da Memory-Items persönliche Entscheidungen und Kontextinformationen enthalten können.

Memory CLI-Befehle

# Memory-Items verwalten
sccs memory add "Titel" [--content "..."] [--from-stdin] [--from-file pfad] \
                        [--tag TAG] [--project P] [--priority 1-5] [--expires DATUM]
sccs memory list        [--project P] [--tag T] [--expired] [--min-priority N]
sccs memory show <slug> [--raw]
sccs memory edit <slug>
sccs memory update <slug> [--extend "..."] [--tag T] [--priority N] [--bump-version]
sccs memory delete <slug> [--force]   # Soft-Delete: verschiebt nach _archive/

# Suche und Export
sccs memory search "query" [--project P]
sccs memory export  [--format claude_block|markdown|json] \
                    [--project P] [--tag T] [--out DATEI] [--api]
sccs memory import conversation.json [--preview]

# Verwaltung
sccs memory expire        # Abgelaufene Items archivieren
sccs memory stats         # Statistiken anzeigen

Sync-Richtung und Konfliktauflösung

Aspekt	Verhalten
Sync-Modus	`bidirectional`: lokal ↔ Repository (Standard)
Konfliktauflösung	`conflict_resolution: newest`: Das Item mit dem neueren `updated`-Timestamp gewinnt automatisch
Soft-Delete	`sccs memory delete` verschiebt nach `_archive/<slug>/` — kein Datenverlust
Auto-Expire	Items mit vergangener `expires`-Zeit werden bei `sccs sync` archiviert wenn `auto_expire: true`
Prioritätsfilter	SessionStart-Hook respektiert `min_priority` aus `memory_config`
Zeichenlimit	Hook kürzt Context bei `max_context_chars` (Standard: 8000)

Export-Workflows für Claude.ai

# Als <memory>...</memory> Block für System-Prompt in Claude.ai
sccs memory export
sccs memory export --project v18 --format claude_block

# Als JSON (strukturiert)
sccs memory export --format json --out ~/Desktop/memory.json

# Über Anthropic Files API hochladen (erfordert sccs[memory] + ANTHROPIC_API_KEY)
sccs memory export --api

# Claude.ai Konversations-Export importieren
sccs memory import ~/Downloads/conversation.json
sccs memory import ~/Downloads/conversation.json --preview  # Vorschau ohne Speichern

Sicherheitshinweise

Privates Repository: claude_memory nur mit privatem Git-Repo nutzen
API-Key: ANTHROPIC_API_KEY ausschließlich als Umgebungsvariable, nie in Dateien
Globale Ausschlüsse: Bestehende global_exclude-Pattern schützen automatisch vor versehentlichem Sync sensibler Dateinamen (*token*, *secret*, *credential*)
--api ist immer explizit: Anthropic Files API-Upload niemals automatisch

Kategorien-Referenz

Feld	Typ	Pflicht	Beschreibung
`enabled`	bool	Nein	Kategorie aktivieren (Standard: true)
`description`	string	Nein	Beschreibung
`local_path`	string	Ja	Lokaler Quellpfad (unterstützt `~`)
`repo_path`	string	Ja	Pfad im Repository
`sync_mode`	string	Nein	`bidirectional`, `local_to_repo`, `repo_to_local`
`item_type`	string	Nein	`file`, `directory`, `mixed` (Standard: file)
`item_marker`	string	Nein	Marker-Datei für Verzeichnisse (z.B. `SKILL.md`)
`item_pattern`	string	Nein	Glob-Pattern für Dateien (z.B. `*.md`)
`include`	list	Nein	Einschluss-Patterns (Standard: `["*"]`)
`exclude`	list	Nein	Ausschluss-Patterns (Standard: `[]`)
`platforms`	list	Nein	Plattform-Filter: `["macos"]`, `["linux"]`, `null` = alle

CLI-Befehle

# Synchronisierung
sccs sync                        # Alle aktivierten Kategorien
sccs sync -c skills              # Bestimmte Kategorie
sccs sync -n                     # Vorschau (Dry-Run)
sccs sync -i                     # Interaktive Konfliktauflösung
sccs sync --force local          # Lokale Version erzwingen
sccs sync --force repo           # Repo-Version erzwingen
sccs sync --force newer          # Neuere Datei erzwingen (mtime)
sccs sync --commit --push        # Mit Git-Commit und Push
sccs sync --pull                 # Vorher Remote-Änderungen ziehen

# Status und Diff
sccs status                      # Sync-Status aller Kategorien
sccs diff                        # Alle Unterschiede anzeigen
sccs diff -c skills              # Diffs einer Kategorie
sccs log                         # Sync-Verlauf

# Konfiguration
sccs config show                 # Konfiguration anzeigen
sccs config init                 # Neue Konfiguration erstellen
sccs config edit                 # Im Editor öffnen
sccs config validate             # Konfiguration prüfen

# Export/Import
sccs export                      # Interaktive Auswahl + ZIP erstellen
sccs export --all -o config.zip  # Alles exportieren
sccs export -c claude_skills     # Nur bestimmte Kategorie
sccs import config.zip           # Interaktive Auswahl + importieren
sccs import config.zip --dry-run # Vorschau ohne Schreiben
sccs import config.zip --all     # Alles importieren

# Kategorien
sccs categories list             # Aktivierte Kategorien
sccs categories list --all       # Alle (inkl. deaktivierte)
sccs categories enable fish      # Kategorie aktivieren
sccs categories disable fish     # Kategorie deaktivieren

# Doctor (System & Plugin Health)
sccs doctor check                # Read-only Status-Tabelle (Exit 1 bei Problemen)
sccs doctor install              # Installiert fehlende Komponenten (Confirm pro Action)
sccs doctor install --yes        # Skip Confirms (CI use only)
sccs doctor update               # Plugins + npx-Tools aktualisieren

Standard-Kategorien

Claude Code (standardmäßig aktiv)

Kategorie	Pfad	Beschreibung
`claude_framework`	`~/.claude/*.md`	SuperClaude Framework-Dateien
`claude_skills`	`~/.claude/skills/`	Skills (Verzeichnisse mit SKILL.md)
`claude_commands`	`~/.claude/commands/`	Commands (einzelne .md-Dateien)
`claude_hooks`	`~/.claude/hooks/`	Event-Handler-Skripte
`claude_agents`	`~/.claude/agents/`	Sub-Agent-Definitionen mit Modell-Routing
`claude_scripts`	`~/.claude/scripts/`	Hilfsskripte
`claude_plugins`	`~/.claude/plugins/`	Plugin-Konfigurationen
`claude_mcp`	`~/.claude/mcp/`	MCP-Server-Konfigurationen
`claude_statusline`	`~/.claude/statusline.*`	Statusline-Skript

Claude Code (standardmäßig deaktiviert)

Kategorie	Pfad	Beschreibung
`claude_memories`	`~/.claude/projects/*/memory/`	Persistente Projekt-Memories (feedback, project, user, reference)
`claude_memory`	`~/.claude/memory/`	Memory Bridge Items (claude_memory aktivieren)
`claude_settings`	`~/.claude/settings.json`	Claude Code Settings (Permissions, Hooks-Config)

Shell (standardmäßig aktiv)

Kategorie	Pfad	Plattform	Beschreibung
`fish_config`	`~/.config/fish/`	alle	Fish-Shell-Konfiguration
`fish_config_macos`	`~/.config/fish/conf.d/*.macos.fish`	macOS	macOS-spezifische conf.d
`fish_functions`	`~/.config/fish/functions/`	alle	Fish-Funktionen
`fish_functions_macos`	`~/.config/fish/functions/macos/`	macOS	macOS-spezifische Funktionen
`starship_config`	`~/.config/starship.toml`	alle	Starship-Prompt

Konfliktauflösung

Bei Änderungen auf beiden Seiten bietet SCCS mehrere Auflösungsstrategien:

Interaktiver Modus (empfohlen):

sccs sync -i

Optionen im interaktiven Menü:

Lokal behalten — Lokale Version verwenden
Repo behalten — Repository-Version verwenden
Diff anzeigen — Unterschiede prüfen
Interaktives Merge — Hunk-für-Hunk-Zusammenführung
Externer Editor — In Editor öffnen
Überspringen — Dieses Element auslassen
Abbrechen — Sync komplett abbrechen

Automatische Auflösung:

sccs sync --force local          # Lokal gewinnt immer
sccs sync --force repo           # Repository gewinnt immer
sccs sync --force newer          # Neuere Datei gewinnt (per mtime)

Automatische Backups

Vor jedem Überschreiben erstellt SCCS zeitgestempelte Sicherungen:

~/.config/sccs/backups/
├── claude_skills/
│   └── my-skill.20250123_143052.bak
└── fish_config/
    └── config.fish.20250123_143052.bak

Plattform-Awareness

Kategorien können auf bestimmte Betriebssysteme beschränkt werden:

fish_config_macos:
  enabled: true
  platforms: ["macos"]              # Nur auf macOS synchronisieren
  local_path: ~/.config/fish/conf.d
  repo_path: .config/fish/conf.d
  item_pattern: "*.macos.fish"

Erkennung: Darwin → macos, Linux → linux, Windows → windows. Kategorien mit platforms: null synchronisieren auf allen Plattformen.

Wenn beim Start Kategorien aufgrund des platforms-Filters auf der aktuellen Plattform übersprungen werden, gibt SCCS einen einzeiligen Hinweis aus (nur in interaktiven Terminals, nicht in Pipes/CI):

ℹ Plattform: windows — Fish nicht verfügbar — übersprungen: fish_config, fish_functions
  Tipp: `sccs convert fish-to-pwsh` generiert PowerShell-Aliasse aus den Fish-Configs

Windows / PowerShell-Support

Auf Windows 11 mit PowerShell 7+ läuft SCCS direkt:

# Installation
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install sccs

# Konfiguration anlegen
sccs config init

# PowerShell-Profile-Kategorie aktivieren und syncen
sccs categories enable powershell_profile
sccs sync --category powershell_profile

Fish-Kategorien (fish_config, fish_functions) sind durch platforms: ["macos", "linux"] automatisch ausgeschlossen — kein Fehler, kein Sync-Versuch.

Fish → PowerShell Konvertierung

Auf macOS/Linux generiert ein einmaliger CLI-Aufruf ein modulares PowerShell-Profil aus deiner Fish-Konfiguration:

# Vorschau
sccs convert fish-to-pwsh --dry-run

# Konvertieren ins Sync-Repo
sccs convert fish-to-pwsh

# Ergebnis prüfen
ls ~/gitbase/sccs-sync/.config/powershell/
# Microsoft.PowerShell_profile.ps1
# conf.d/  functions/  README.md

Was wird konvertiert:

Fish	PowerShell	Hinweis
`alias name=value`	`Set-Alias -Name name -Value value -Scope Global -Force`	Wert ohne Whitespace
`alias name='cmd args'`	`function name { cmd args @args }`	Mit Argumenten — `@args`-Splatting
`set -gx VAR value`	`$env:VAR = "value"`	`$HOME` bleibt `$HOME`
`fish_add_path /opt/bin`	duplikatsicheres `$env:PATH`-Prepend	Nutzt `[IO.Path]::PathSeparator`
`abbr -a name expansion`	`Set-Alias` oder `function`	Kürzeste Semantik
`.macos.fish`, `.linux.fish`	übersprungen	Plattform-spezifisch
Fish-Funktionen (`function … end`)	Stub mit Original als Kommentar	Manuell portieren

Nach Edits in ~/.config/fish/ einfach sccs convert fish-to-pwsh --force erneut aufrufen — bestehende Zieldateien werden mit .bak gesichert.

Architektur

sccs/
├── cli.py                # Click CLI mit Befehlsgruppen
├── cli_memory.py         # Memory Command Group
├── config/               # Konfigurationsmanagement
│   ├── schema.py         #   Pydantic-Modelle
│   ├── loader.py         #   YAML-Laden/Speichern
│   └── defaults.py       #   Standard-Konfiguration
├── sync/                 # Synchronisierungs-Engine
│   ├── engine.py         #   Hauptorchestrator
│   ├── category.py       #   Kategorie-Handler
│   ├── item.py           #   SyncItem, Scan-Funktionen
│   ├── actions.py        #   Aktionstypen und -ausführung
│   ├── state.py          #   State-Persistenz
│   └── settings.py       #   JSON-Settings-Ensure
├── transfer/             # Export/Import-Modul
│   ├── manifest.py       #   ZIP-Manifest (Pydantic)
│   ├── exporter.py       #   Scan + ZIP-Erstellung
│   ├── importer.py       #   ZIP-Extraktion + Platzierung
│   └── ui.py             #   questionary Checkbox-Helpers
├── git/                  # Git-Operationen
│   └── operations.py     #   Commit, Push, Pull, Status
├── memory/               # Memory Bridge Modul
│   ├── __init__.py       #   Modul-Exports
│   ├── item.py           #   MemoryItem (Frontmatter + Markdown)
│   ├── manager.py        #   CRUD-Layer für ~/.claude/memory/
│   ├── filter.py         #   Filter und Sortierung
│   ├── bridge.py         #   Import/Export Claude.ai
│   └── api.py            #   Optionaler Anthropic Files API Layer
├── output/               # Terminal-Ausgabe
│   ├── console.py        #   Rich-Console
│   ├── diff.py           #   Diff-Anzeige
│   └── merge.py          #   Interaktives Merge
└── utils/                # Hilfsfunktionen
    ├── paths.py          #   Pfad-Utilities, atomares Schreiben
    ├── hashing.py        #   SHA256-Hashing
    └── platform.py       #   Plattformerkennung

Entwicklung

# Tests
pytest                            # Alle Tests
pytest --cov=sccs                 # Mit Coverage (Minimum: 60%)

# Code-Qualität
ruff check sccs/ tests/           # Linting
ruff format sccs/ tests/          # Formatierung
mypy sccs/                        # Typenprüfung
bandit -r sccs/                   # Security-Scan

Lizenz

AGPL-3.0 — Equitania Software GmbH

English Documentation

Project Overview

SCCS is a YAML-configured bidirectional synchronization tool for Claude Code files and optional shell configurations. It keeps skills, commands, hooks, scripts, and shell configs in sync between a local installation and a Git repository.

Version: 2.22.0 · License: AGPL-3.0 · Python: ≥3.10

Features

YAML Configuration — Single config.yaml with all sync categories
Flexible Categories — Claude skills, commands, hooks, scripts, Fish shell, and more
Bidirectional Sync — Full two-way synchronization with conflict detection
Interactive Conflict Resolution — Menu-driven conflict handling with -i flag
Interactive Divergence Resolution — Menu (Rebase / Merge / Force-Push / Abort) when the branch has diverged from its remote; CI-friendly (auto-Abort without TTY)
Automatic Backups — Timestamped backups before overwriting files
Git Integration — Auto-commit and push after sync operations
Platform Filtering — Sync categories only on macOS, Linux, or both
Smart Conflict Resolution — --force newer resolves conflicts by file modification time
Project Memories Sync — Sync Claude's persistent project memories across machines
Selective Export/Import — ZIP archives with checkbox selection for customer deployments
Rich Console Output — Formatted terminal output with Rich
Memory Bridge — Persistent context between Claude Code and Claude.ai via Git sync
Memory CLI — Full CRUD management with sccs memory
Auto-Expire — Time-based archiving of expired memory items
Antigravity Integration — Migrate skills to Antigravity IDE prompts
Claude Desktop Integration — Register repository as trusted folder
sccs doctor — System & plugin health checks for Node.js, the claude CLI, configured Claude plugins and npx helper tools (platform-aware: brew / winget / NodeSource manual)

Prerequisites

UV must be installed:

OS	Command
macOS	`brew install uv`
Linux / WSL	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
Windows	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

Installation

As CLI tool (recommended):

uv tool install sccs

Update:

uv tool upgrade sccs

Update UV itself:

# macOS
brew upgrade uv

# Linux / Windows
uv self update

For Developers

git clone https://github.com/equitania/sccs.git
cd sccs
uv venv --python 3.13 && source .venv/bin/activate
uv pip install -e ".[dev]"
sccs --help

Workflows

Publisher (share your configs)

sccs sync --commit --push      # Sync, commit and push to remote
sccs sync --dry-run             # Preview what would change
sccs sync -c skills --push      # Push only skills category

Subscriber (receive shared configs)

sccs sync --pull                # Pull latest and sync to local
sccs sync --force repo          # Overwrite local with repo version
sccs sync -c skills --pull      # Pull only skills category

Quick Start

# Initialize configuration
sccs config init

# Show sync status
sccs status

# Preview changes
sccs sync --dry-run

# Synchronize all enabled categories
sccs sync

# Sync specific category
sccs sync -c claude_skills

Export/Import (Customer Deployment)

Selectively export configurations as ZIP archives and import them on other systems — ideal for customer deployments where the full repository should not be transferred.

Export

# Interactive checkbox selection
sccs export

# Export everything (no prompt)
sccs export --all

# Custom output path
sccs export -o ~/Desktop/customer-config.zip

# Specific categories only
sccs export -c claude_skills
sccs export -c claude_skills -c claude_agents

# Combined: only skills, non-interactive
sccs export -c claude_skills --all -o skills.zip

The interactive selection shows all available items grouped by category with checkboxes:

? Select items to export (42 available):
  ── Claude Code Skills ──
  [✔] code-review
  [✔] git-workflow
  [ ] internal-tool
  ── Claude Agents ──
  [✔] code-reviewer
  ── Fish Shell (macos only) ──
  [✔] config.fish  (macos only)

Import

# Interactive selection of what to import
sccs import config.zip

# Import everything
sccs import config.zip --all

# Preview without writing
sccs import config.zip --dry-run

# Overwrite existing files (with automatic backup)
sccs import config.zip --overwrite

# Overwrite without backup
sccs import config.zip --overwrite --no-backup

Use Cases

Scenario	Recommended Command
Deliver skills to customer	`sccs export -c claude_skills -o customer.zip`
Fish config for Linux server	`sccs export -c fish_config -c fish_functions --all`
Full setup for new system	`sccs export --all -o full-setup.zip`
Preview before import	`sccs import setup.zip --dry-run`
Safe update of existing configs	`sccs import setup.zip --overwrite`

Configuration

Config file: ~/.config/sccs/config.yaml

# Repository settings
repository:
  path: ~/gitbase/sccs-sync      # Local repository path
  remote: origin                  # Git remote name for push
  auto_commit: false              # Auto-commit after sync
  auto_push: false                # Auto-push after commit
  auto_pull: false                # Auto-pull before sync
  commit_prefix: "[SYNC]"         # Prefix for commit messages

# Sync categories
sync_categories:
  claude_skills:
    enabled: true
    description: "Claude Code Skills"
    local_path: ~/.claude/skills
    repo_path: .claude/skills
    sync_mode: bidirectional       # bidirectional | local_to_repo | repo_to_local
    item_type: directory           # file | directory | mixed
    item_marker: SKILL.md          # Marker file for directory items
    include: ["*"]
    exclude: ["_archive/*"]

  fish_config:
    enabled: true
    platforms: ["macos"]           # Only sync on macOS
    local_path: ~/.config/fish
    repo_path: .config/fish
    item_type: mixed
    include: ["config.fish", "functions/*.fish"]
    exclude: ["fish_history", "fish_variables"]

# Global excludes
global_exclude:
  - ".DS_Store"
  - "*.tmp"
  - "__pycache__"

Memory Bridge

Concept

Claude Code (terminal) and Claude.ai (web) share no common memory. The Memory Bridge solves this file-based:

local: ~/.claude/memory/<slug>/MEMORY.md
↕ SCCS sync (bidirectional, via Git)
repo: .claude/memory/<slug>/MEMORY.md
→ Claude.ai:    sccs memory export  →  paste as <memory>...</memory> block
→ Claude Code:  SessionStart hook loads memory automatically as context

Memory Item Format

Each memory item is a MEMORY.md file with YAML frontmatter and Markdown body:

---
id: "project-odoo18-arch"
title: "Odoo 18 Architecture Decisions"
category: decision   # project|decision|learning|pattern|preference|reference|context
project: v18
tags: [odoo, architecture]
priority: 4          # 1 (low) – 5 (critical)
created: "2026-02-23T10:00:00"
updated: "2026-02-23T14:30:00"
expires: null        # ISO datetime or null
version: 1
---

# Odoo 18 Architecture Decisions

Content in Markdown.

Configuration

Two new blocks in ~/.config/sccs/config.yaml:

# 1. Memory category (disabled by default)
sync_categories:
  claude_memory:
    enabled: false           # Enable explicitly: sccs categories enable claude_memory
    description: "Claude Code <-> Claude.ai Memory Bridge"
    local_path: ~/.claude/memory
    repo_path: .claude/memory
    sync_mode: bidirectional
    item_type: directory
    item_marker: MEMORY.md
    conflict_resolution: newest   # Item with newer updated timestamp wins
    exclude: ["_archive/*", "*.tmp"]

# 2. Memory settings
memory_config:
  auto_expire: false           # Archive expired items on sccs sync
  max_context_chars: 8000      # Maximum characters for SessionStart hook
  min_priority: 1              # Minimum priority for hook export
  max_age_days: null           # Maximum age (days), null = unlimited

Local Setup

# 1. Enable the category
sccs categories enable claude_memory

# 2. Install the hook (synced via sccs sync -c claude_hooks)
#    Alternative: place hook directly at ~/.claude/hooks/load-memory.py

# 3. Register hook in ~/.claude/settings.json (manual step!)

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{"type": "command", "command": "python3 ~/.claude/hooks/load-memory.py"}]
      }
    ]
  }
}

# 4. Optional: Anthropic API for cloud sync (Files API)
uv pip install "sccs[memory]"
export ANTHROPIC_API_KEY="..."

# 5. Run first sync
sccs sync -c claude_memory

Important: Use a private repository for memory sync, as memory items may contain personal decisions and context information.

Memory CLI Commands

# Manage memory items
sccs memory add "Title" [--content "..."] [--from-stdin] [--from-file path] \
                        [--tag TAG] [--project P] [--priority 1-5] [--expires DATE]
sccs memory list        [--project P] [--tag T] [--expired] [--min-priority N]
sccs memory show <slug> [--raw]
sccs memory edit <slug>
sccs memory update <slug> [--extend "..."] [--tag T] [--priority N] [--bump-version]
sccs memory delete <slug> [--force]   # Soft-delete: moves to _archive/

# Search and export
sccs memory search "query" [--project P]
sccs memory export  [--format claude_block|markdown|json] \
                    [--project P] [--tag T] [--out FILE] [--api]
sccs memory import conversation.json [--preview]

# Management
sccs memory expire        # Archive expired items
sccs memory stats         # Show statistics

Sync Direction and Conflict Resolution

Aspect	Behavior
Sync mode	`bidirectional`: local ↔ repository (default)
Conflict resolution	`conflict_resolution: newest`: item with newer `updated` timestamp wins automatically
Soft-delete	`sccs memory delete` moves to `_archive/<slug>/` — no data loss
Auto-expire	Items with a past `expires` time are archived on `sccs sync` when `auto_expire: true`
Priority filter	SessionStart hook respects `min_priority` from `memory_config`
Character limit	Hook truncates context at `max_context_chars` (default: 8000)

Export Workflows for Claude.ai

# As <memory>...</memory> block for system prompt in Claude.ai
sccs memory export
sccs memory export --project v18 --format claude_block

# As JSON (structured)
sccs memory export --format json --out ~/Desktop/memory.json

# Upload via Anthropic Files API (requires sccs[memory] + ANTHROPIC_API_KEY)
sccs memory export --api

# Import Claude.ai conversation export
sccs memory import ~/Downloads/conversation.json
sccs memory import ~/Downloads/conversation.json --preview  # Preview without saving

Security Notes

Private repository: Only use claude_memory with a private Git repo
API key: Store ANTHROPIC_API_KEY as environment variable only, never in files
Global excludes: Existing global_exclude patterns automatically protect against accidental sync of sensitive filenames (*token*, *secret*, *credential*)
--api is always explicit: Anthropic Files API upload is never automatic

Category Field Reference

Field	Type	Required	Description
`enabled`	bool	No	Enable/disable category (default: true)
`description`	string	No	Human-readable description
`local_path`	string	Yes	Local source path (supports `~`)
`repo_path`	string	Yes	Path in repository
`sync_mode`	string	No	`bidirectional`, `local_to_repo`, `repo_to_local`
`item_type`	string	No	`file`, `directory`, `mixed` (default: file)
`item_marker`	string	No	Marker file for directory items (e.g., `SKILL.md`)
`item_pattern`	string	No	Glob pattern for file items (e.g., `*.md`)
`include`	list	No	Patterns to include (default: `["*"]`)
`exclude`	list	No	Patterns to exclude (default: `[]`)
`platforms`	list	No	Platform filter: `["macos"]`, `["linux"]`, `null` = all

CLI Commands

# Synchronization
sccs sync                        # All enabled categories
sccs sync -c skills              # Specific category
sccs sync -n                     # Preview (dry-run)
sccs sync -i                     # Interactive conflict resolution
sccs sync --force local          # Force local version
sccs sync --force repo           # Force repo version
sccs sync --force newer          # Force newer file (by mtime)
sccs sync --commit --push        # With git commit and push
sccs sync --pull                 # Pull remote changes first

# Status and diff
sccs status                      # Sync status of all categories
sccs diff                        # Show all differences
sccs diff -c skills              # Diffs for a category
sccs log                         # Sync history

# Configuration
sccs config show                 # Show configuration
sccs config init                 # Create new configuration
sccs config edit                 # Open in editor
sccs config validate             # Validate configuration

# Export/Import
sccs export                      # Interactive selection + create ZIP
sccs export --all -o config.zip  # Export everything
sccs export -c claude_skills     # Specific category only
sccs import config.zip           # Interactive selection + import
sccs import config.zip --dry-run # Preview without writing
sccs import config.zip --all     # Import everything

# Categories
sccs categories list             # List enabled categories
sccs categories list --all       # All (incl. disabled)
sccs categories enable fish      # Enable category
sccs categories disable fish     # Disable category

# Doctor (system & plugin health)
sccs doctor check                # Read-only status table (exit 1 on problems)
sccs doctor install              # Install missing components (confirm per action)
sccs doctor install --yes        # Skip confirms (CI use only)
sccs doctor update               # Update plugins + refresh npx tools

Default Categories

Claude Code (enabled by default)

Category	Path	Description
`claude_framework`	`~/.claude/*.md`	SuperClaude Framework files
`claude_skills`	`~/.claude/skills/`	Skills (directories with SKILL.md)
`claude_commands`	`~/.claude/commands/`	Commands (single .md files)
`claude_hooks`	`~/.claude/hooks/`	Event handler scripts
`claude_agents`	`~/.claude/agents/`	Sub-agent definitions with model routing
`claude_scripts`	`~/.claude/scripts/`	Utility scripts
`claude_plugins`	`~/.claude/plugins/`	Plugin configurations
`claude_mcp`	`~/.claude/mcp/`	MCP server configs
`claude_statusline`	`~/.claude/statusline.*`	Statusline script

Claude Code (disabled by default)

Category	Path	Description
`claude_memories`	`~/.claude/projects/*/memory/`	Persistent project memories (feedback, project, user, reference)
`claude_memory`	`~/.claude/memory/`	Memory Bridge items (enable claude_memory to use)
`claude_settings`	`~/.claude/settings.json`	Claude Code settings (permissions, hooks config)

Shell (enabled by default)

Category	Path	Platform	Description
`fish_config`	`~/.config/fish/`	all	Fish shell configuration
`fish_config_macos`	`~/.config/fish/conf.d/*.macos.fish`	macOS	macOS-specific conf.d
`fish_functions`	`~/.config/fish/functions/`	all	Fish custom functions
`fish_functions_macos`	`~/.config/fish/functions/macos/`	macOS	macOS-specific functions
`starship_config`	`~/.config/starship.toml`	all	Starship prompt

Conflict Resolution

When both local and repo have changes, SCCS offers multiple resolution strategies:

Interactive mode (recommended):

sccs sync -i

Interactive menu options:

Keep local — Use local version
Keep repo — Use repository version
Show diff — View differences
Interactive merge — Hunk-by-hunk merge
External editor — Open in editor
Skip — Skip this item
Abort — Stop sync completely

Automatic resolution:

sccs sync --force local          # Local wins all conflicts
sccs sync --force repo           # Repository wins all conflicts
sccs sync --force newer          # Newer file wins (by mtime)

Automatic Backups

Before overwriting any file, SCCS creates timestamped backups:

~/.config/sccs/backups/
├── claude_skills/
│   └── my-skill.20250123_143052.bak
└── fish_config/
    └── config.fish.20250123_143052.bak

Platform Awareness

Categories can be restricted to specific operating systems:

fish_config_macos:
  enabled: true
  platforms: ["macos"]              # Only sync on macOS
  local_path: ~/.config/fish/conf.d
  repo_path: .config/fish/conf.d
  item_pattern: "*.macos.fish"

Detection: Darwin → macos, Linux → linux, Windows → windows. Categories with platforms: null sync on all platforms.

When categories are skipped on the current platform due to the platforms filter, SCCS prints a one-line dimmed hint at startup (only in interactive terminals, not in pipes/CI):

ℹ Plattform: windows — Fish nicht verfügbar — übersprungen: fish_config, fish_functions
  Tipp: `sccs convert fish-to-pwsh` generiert PowerShell-Aliasse aus den Fish-Configs

Windows / PowerShell Support

SCCS runs natively on Windows 11 with PowerShell 7+:

# Install
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install sccs

# Initialize config
sccs config init

# Enable and sync the PowerShell profile category
sccs categories enable powershell_profile
sccs sync --category powershell_profile

Fish categories (fish_config, fish_functions) carry platforms: ["macos", "linux"] and are skipped automatically on Windows — no error, no sync attempt.

Fish → PowerShell Conversion

On macOS/Linux a one-shot CLI command generates a modular PowerShell profile from your Fish configuration:

# Preview
sccs convert fish-to-pwsh --dry-run

# Convert into the sync repo
sccs convert fish-to-pwsh

# Inspect
ls ~/gitbase/sccs-sync/.config/powershell/
# Microsoft.PowerShell_profile.ps1
# conf.d/  functions/  README.md

Conversion rules:

Fish	PowerShell	Note
`alias name=value`	`Set-Alias -Name name -Value value -Scope Global -Force`	Single-word value
`alias name='cmd args'`	`function name { cmd args @args }`	With args — uses `@args` splatting
`set -gx VAR value`	`$env:VAR = "value"`	`$HOME` stays `$HOME`
`fish_add_path /opt/bin`	duplicate-aware `$env:PATH` prepend	Uses `[IO.Path]::PathSeparator`
`abbr -a name expansion`	`Set-Alias` or `function`	Closest semantic fit
`.macos.fish`, `.linux.fish`	skipped	Platform-specific
Fish functions (`function … end`)	Stub with original as comment	Port by hand

After editing Fish files, just rerun sccs convert fish-to-pwsh --force — existing target files are backed up as .bak.

Architecture

sccs/
├── cli.py                # Click CLI with command groups
├── cli_memory.py         # Memory Command Group
├── config/               # Configuration management
│   ├── schema.py         #   Pydantic models
│   ├── loader.py         #   YAML loading/saving
│   └── defaults.py       #   Default configuration
├── sync/                 # Synchronization engine
│   ├── engine.py         #   Main orchestrator
│   ├── category.py       #   Category handler
│   ├── item.py           #   SyncItem, scan functions
│   ├── actions.py        #   Action types and execution
│   ├── state.py          #   State persistence
│   └── settings.py       #   JSON settings ensure
├── transfer/             # Export/Import module
│   ├── manifest.py       #   ZIP manifest (Pydantic)
│   ├── exporter.py       #   Scan + ZIP creation
│   ├── importer.py       #   ZIP extraction + placement
│   └── ui.py             #   questionary checkbox helpers
├── git/                  # Git operations
│   └── operations.py     #   Commit, push, pull, status
├── memory/               # Memory Bridge module
│   ├── __init__.py       #   Module exports
│   ├── item.py           #   MemoryItem (frontmatter + Markdown)
│   ├── manager.py        #   CRUD layer for ~/.claude/memory/
│   ├── filter.py         #   Filtering and sorting
│   ├── bridge.py         #   Claude.ai import/export
│   └── api.py            #   Optional Anthropic Files API layer
├── output/               # Terminal output
│   ├── console.py        #   Rich console
│   ├── diff.py           #   Diff display
│   └── merge.py          #   Interactive merge
└── utils/                # Utilities
    ├── paths.py          #   Path utilities, atomic writes
    ├── hashing.py        #   SHA256 hashing
    └── platform.py       #   Platform detection

Development

# Tests
pytest                            # All tests
pytest --cov=sccs                 # With coverage (minimum: 60%)

# Code quality
ruff check sccs/ tests/           # Linting
ruff format sccs/ tests/          # Formatting
mypy sccs/                        # Type checking
bandit -r sccs/                   # Security scan

License

AGPL-3.0 — Equitania Software GmbH

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

2.33.1

May 26, 2026

2.33.0

May 26, 2026

2.32.2

May 26, 2026

2.32.1

May 25, 2026

2.32.0

May 25, 2026

2.31.0

May 24, 2026

2.29.1

May 24, 2026

2.29.0

May 11, 2026

2.28.1

May 6, 2026

2.28.0

May 6, 2026

2.27.0

May 5, 2026

2.26.0

May 5, 2026

2.25.0

May 5, 2026

2.24.0

May 5, 2026

2.23.0

May 4, 2026

2.22.1

May 4, 2026

This version

2.22.0

May 4, 2026

2.21.3

May 4, 2026

2.21.2

May 4, 2026

2.21.0

May 4, 2026

2.20.2

Apr 28, 2026

2.20.1

Apr 28, 2026

2.19.1

Apr 28, 2026

2.19.0

Apr 28, 2026

2.18.0

Apr 24, 2026

2.17.1

Apr 22, 2026

2.17.0

Mar 29, 2026

2.16.0

Mar 26, 2026

2.15.0

Mar 26, 2026

2.14.0

Mar 23, 2026

2.13.0

Mar 22, 2026

2.12.0

Mar 22, 2026

2.11.0

Mar 22, 2026

2.10.0

Mar 14, 2026

2.9.0

Mar 14, 2026

2.8.0

Feb 24, 2026

2.7.0

Feb 23, 2026

2.6.0

Feb 19, 2026

2.5.0

Feb 16, 2026

2.3.0

Feb 9, 2026

2.2.0

Jan 28, 2026

2.1.1

Jan 28, 2026

2.1.0

Jan 27, 2026

2.0.8

Jan 23, 2026

2.0.7

Jan 23, 2026

2.0.6

Jan 23, 2026

2.0.5

Jan 23, 2026

2.0.4

Jan 22, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sccs-2.22.0.tar.gz (374.3 kB view details)

Uploaded May 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sccs-2.22.0-py3-none-any.whl (124.5 kB view details)

Uploaded May 4, 2026 Python 3

File details

Details for the file sccs-2.22.0.tar.gz.

File metadata

Download URL: sccs-2.22.0.tar.gz
Upload date: May 4, 2026
Size: 374.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for sccs-2.22.0.tar.gz
Algorithm	Hash digest
SHA256	`77437b53a5351f90c5cb0ceac3e99d00318b2a3e740823bdee34e9d70d96918f`
MD5	`c9eac3b98dd41dd5d5484ecf1a9c1a03`
BLAKE2b-256	`cc3879e51770bb55de14a6beb46236220ebb2e8b5a5b1ba978617495cb1858ee`

See more details on using hashes here.

File details

Details for the file sccs-2.22.0-py3-none-any.whl.

File metadata

Download URL: sccs-2.22.0-py3-none-any.whl
Upload date: May 4, 2026
Size: 124.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for sccs-2.22.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c7afce7da6a4d48ab32f9e333e315020763c5b6f3b379b666c03e391b0865ffc`
MD5	`613b3509e7824303e00b74523a9d468a`
BLAKE2b-256	`480b314ed55e583ed9232e42706044b395ffff1b40df1981b8e858d07f91c5f7`

See more details on using hashes here.

sccs 2.22.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

SCCS - SkillsCommandsConfigsSync

Deutsche Dokumentation

Projektübersicht

Funktionen

Voraussetzungen

Installation

Für Entwickler

Workflows

Publisher (Änderungen teilen)

Subscriber (Änderungen empfangen)

Schnellstart

Export/Import (Kundendeployment)

Export

Import

Einsatzbereiche

Konfiguration

Memory Bridge

Konzept

Memory Item Format

Konfiguration

Lokale Einrichtung

Memory CLI-Befehle

Sync-Richtung und Konfliktauflösung

Export-Workflows für Claude.ai

Sicherheitshinweise

Kategorien-Referenz

CLI-Befehle

Standard-Kategorien

Claude Code (standardmäßig aktiv)

Claude Code (standardmäßig deaktiviert)

Shell (standardmäßig aktiv)

Konfliktauflösung

Automatische Backups

Plattform-Awareness

Windows / PowerShell-Support

Fish → PowerShell Konvertierung

Architektur

Entwicklung

Lizenz

English Documentation

Project Overview

Features

Prerequisites

Installation

For Developers

Workflows

Publisher (share your configs)

Subscriber (receive shared configs)

Quick Start

Export/Import (Customer Deployment)

Export

Import

Use Cases

Configuration

Memory Bridge

Concept

Memory Item Format

Configuration

Local Setup

Memory CLI Commands

Sync Direction and Conflict Resolution

Export Workflows for Claude.ai

Security Notes

Category Field Reference

CLI Commands

Default Categories

Claude Code (enabled by default)

Claude Code (disabled by default)

Shell (enabled by default)

Conflict Resolution

Automatic Backups