Agent config sync

<img src="banner.png" width="100%" alt="agent-config-sync banner">

Agent Config Sync

Ein uebergreifendes Sync-Protokoll fuer MCP-Server und Skills ueber alle bekannten Agent-Apps und CLIs. Statt fuer jedes App-Paar ein eigenes Skript zu pflegen, beschreibt dieser Skill deklarativ, welche Tools auf einem System leben, was sie teilen sollen (MCP / Skills / beides) und wie (pull, push, bidirektional/verteilen). Ein generischer Ablauf liest diese Deklaration und fuehrt den Sync aus.

Claude-MCP-Profile-Backend: Fuer claude-code und claude-desktop wird ellmos-controlcenter-mcp als Backend genutzt (MCP-Tool resolve_profile/switch_profile). sync.py enthaelt keine eigene Claude-Profil-Logik; der Agent ruft die ControlCenter-MCP-Tools zur Laufzeit auf. Direkt lesbare JSON-Profildateien (z.B. shared.json) werden weiterhin direkt gelesen.

Loest mcp-config-sync ab: Der aeltere Skill mcp-config-sync ist als Registry-Beziehung claude-pair (pull, scope mcp) in diesem Skill umschlossen. Sobald agent-config-sync produktiv eingesetzt wird, sollte mcp-config-sync auf status: deprecated gesetzt werden.

Verhaeltnis zu bestehenden Skills (keine Duplikation)

Skill	Zustaendigkeit	Verhaeltnis
agent-config-sync (dieser)	Sync von MCP-Servern + Skills ueber alle Agent-Tools, regelbasiert	Achse 1 (Inter-Agent) + Inter-IDE-Verteilung
mcp-config-sync	nur MCP, nur Claude Code <-> Claude Desktop, 1 Skript	Spezialfall, der hier umschlossen wird (siehe references/legacy-mcp-config-sync.md); bleibt vorerst als Legacy bestehen
agents-bridge	leitet fremde Agents per Redirect-Datei auf die EINE Regel-Quelle CLAUDE.md	Regel-Sync (Wissen/Workflows), NICHT Tool-Config. Komplementaer.
system-onboarding	Erstaufsetzen eines neuen Systems (Reihenfolge der Installation)	liefert die Config-Ort-Tabellen, auf denen dieser Skill aufbaut

Was dieser Skill NICHT ist: kein Regel-/CLAUDE.md-Sync (das macht agents-bridge), kein System-Erstsetup (das macht system-onboarding), kein Plugin-/Extension-Marktplatz-Abgleich (die Toolkits sind komplementaer, siehe mcp-config-sync/references/plugin-extension-parity.md).

Die drei Datenebenen

Der Skill trennt bewusst Was-soll-passieren von Wie-sehen-die-Anbieter-aus von Wo-liegt-es-real:

  REGISTRY  (lokal/privat)        was syncen welche Tools wie? (Beziehungen, Modus, Scope)
      |  liest
      v
  CONFIG    (publizierbar)        Anbieter-Standardspezifikationen: pro Tool wo + Format
      |  loest Pfade auf nach
      v
  CACHE     (lokal/privat)        aufgeloeste reale Verzeichnisse/Dateien (Lauf-Cache)

Datei	Inhalt	Privacy
REGISTRY.md + registry.example.json	welche Tools vorhanden, Sync-Paare/-Gruppen, Modus, Scope	Template publizierbar; reale registry.json lokal/gitignored
CONFIG.md + config.json	je Anbieter: Config-Ort (Platzhalter <HOME>), Format, Merge-Key, Eigenheiten, Quellen-Stand	publizierbar (neutral)
CACHE.md + cache.json	aufgeloeste reale Pfade auf DIESEM System	lokal/gitignored

Ablauf (Protokoll)

0. Lock + Vorsicht

• Bei aktiver LOCK*.txt im Zielbereich: nichts schreiben (LOCK-System beachten).
• Default ist read-only: --status/--plan veraendern nichts. --apply nur mit --yes und nach Anzeige des Plans.

1. Registry lesen

• registry.json (Fallback: registry.example.json) laden.
• Liefert: vorhandene Tools auf diesem host, die Sync-Beziehungen (Paare/Gruppen), je Beziehung Modus (pull | push | bidirectional) und Scope (mcp | skills | both).

2. Config lesen (Anbieter-Specs)

• config.json laden: je Anbieter Config-Ort (mit <HOME>-Platzhalter), Format (json | toml | dir), mcp_key (z.B. mcpServers), skills_dir, Eigenheiten.

3. Cache aufloesen

• Platzhalter (<HOME>, <APPDATA>, ...) gegen das reale System aufloesen → cache.json.
• Pruefen, ob die Datei/der Ordner existiert. Fehlt sie → Lernmechanismus (Schritt 6).

4. Plan bilden (pull vs. verteilen)

• Pro Beziehung den Quellzustand lesen und mit dem Zielzustand vergleichen.
• pull: ein designierter Master/Hub wird gelesen, Ziele bekommen dessen Stand.
• push/verteilen: ein Quell-Tool verteilt an mehrere Ziele.
• bidirectional: Vereinigung; bei Konflikt (gleicher Key, anderer Wert) → eskalieren, nicht raten.
• Fuer mcp: nur den mcp_key-Block ersetzen, restliche Config-Felder erhalten; Format-Konvertierung JSON↔TOML, wo noetig (Codex = TOML).
• Fuer skills: Verzeichnis-Abgleich (skills_dir); App-spezifische Eigenheiten beachten (z.B. Claude Desktop liest ~/.claude/skills/ NICHT direkt → Bridge-Skill, siehe mcp-config-sync/references/skills-sync-options.md).
• Ausgabe: menschenlesbarer Plan (welche Datei, welche Keys, add/update/remove).

5. Anwenden + Verifizieren (nur --apply --yes)

• Vor jedem Schreiben Backup mit Zeitstempel.
• Schreiben (Format-erhaltend, nur Ziel-Block).
• Verifikation: Ziel erneut lesen, Soll/Ist vergleichen; Diff ausgeben.
• Hinweis: Apps ggf. neu starten (Claude Desktop komplett beenden), damit Aenderungen greifen.

6. Lernmechanismus (Selbstheilung der Config)

Wird ausgeloest, wenn ein Config-Ort fehlt, ein Anbieter unbekannt ist oder ein Format nicht passt:

1. Config-Ort veraltet/nicht gefunden → Systemsuche nach den bekannten Dateinamen:
   • MCP-Server-Suche: ellmos-FileCommander (fc_search_files/fc_search) oder Glob ueber die Home-/AppData-Wurzeln nach *config*.json, config.toml, claude_desktop_config.json, settings.json, mcp.json.
   • Gefundenen realen Pfad in cache.json eintragen; wenn er dauerhaft vom Config-Standard abweicht, config.json (mit Stand-Hinweis) aktualisieren.
2. Unbekannter Anbieter (Tool, das in config.json fehlt) → WebSearch nach "<tool> MCP config file location" / "<tool> custom rules file", Ergebnis verifizieren, neuen Anbieter-Eintrag in config.json anlegen (mit sources-Feld + Datum).
3. Format-/Schema-Unsicherheit → aktuelle Spezifikation per WebSearch UND Context7 (resolve-library-id → query-docs, z.B. "Model Context Protocol", "claude code mcp config", "codex config.toml") nachschlagen; config.json korrigieren.

Jede automatische Config-Aenderung dokumentiert sich selbst: Feld sources + updated im betroffenen Anbieter-Eintrag setzen.

Aufruf

# Status: Pfade aufloesen, Existenz pruefen, cache.json aktualisieren (read-only fuer Agent-Configs)
PYTHONIOENCODING=utf-8 python scripts/sync.py --status

# Plan: was wuerde ein Sync tun? (read-only, kein Schreiben)
PYTHONIOENCODING=utf-8 python scripts/sync.py --plan

# Anwenden: block-replace pro Relation, Backup + Verifikation (bestaetigung erforderlich)
PYTHONIOENCODING=utf-8 python scripts/sync.py --apply --yes

# Tests ausfuehren (nutzen nur Fixtures -- keine echten Configs)
PYTHONIOENCODING=utf-8 python -m pytest skills/infrastructure/agent-config-sync/tests/ -v

ControlCenter-Backend (Claude-Provider)

Fuer claude-code- und claude-desktop-Targets wird kein direkter Config-Write gemacht. Stattdessen den ellmos-controlcenter-mcp-Server nutzen:

resolve_profile()   -- aktives Profil und Serverinhalt lesen
switch_profile()    -- Profil wechseln / MCP-Config-Datei neu erzeugen

Der --plan-Output zeigt explizit, welche ControlCenter-Aktion noetig ist.

Privacy / Konventionen

• Publizierbar (neutral): SKILL.md, CONFIG.md, config.json, REGISTRY.md, registry.example.json, CACHE.md, cache.example.json, scripts/. Nur Platzhalter (<HOME>, ~, <HOST>, <USER>), KEINE echten Personen-Pfade/Hostnames.
• Lokal/privat (gitignored): registry.json, cache.json (die mit echten Pfaden gefuellten Instanzen fuer DIESES System). Muster in der .SKILLS/.gitignore ergaenzt.
• Quelle = skills/.... NICHT nach ~/.claude/skills/ deployen — das entscheidet der User spaeter via skill_sync.py. Nicht committen/pushen ohne Freigabe.

Aufbau dieses Skills

agent-config-sync/
├── SKILL.md                  (diese Datei — das Protokoll, DE)
├── SKILL.en.md               (englische Version)
├── REGISTRY.md               Doku: was syncen welche Tools wie
├── registry.example.json     Template (publizierbar)
├── registry.json             reale Instanz fuer dieses System (LOKAL, gitignored)
├── CONFIG.md                 Doku: Anbieter-Standardspezifikationen
├── config.json               je Anbieter: Ort + Format + Eigenheiten (publizierbar)
├── CACHE.md                  Doku: Lauf-Cache aufgeloester Pfade
├── cache.example.json        Template (publizierbar)
├── cache.json                aufgeloeste reale Pfade (LOKAL, gitignored)
├── scripts/
│   └── sync.py               Funktionale Implementierung (--status/--plan/--apply)
├── tests/
│   └── test_sync.py          Pytest-Tests (nur Fixtures, keine echten Config-Writes)
└── references/
    └── legacy-mcp-config-sync.md   wie der alte MCP-Skill hier aufgeht

Changelog

0.2.0 (2026-06-20)

• --apply implementiert: format-erhaltendes JSON-block-replace, TOML-Abschnitt-replace (Codex), Backup + Verifikation je Schritt, Skills-Verzeichnis-Abgleich.
• Test-Suite (tests/test_sync.py, 15 Tests, nur Fixtures -- keine echten Config-Writes).
• ControlCenter-Backend-Anbindung: Claude-Provider-Writes delegieren an ellmos-controlcenter-mcp (resolve_profile/switch_profile); keine eigene Profil-Logik.
• Test-Isolation via --root-Flag und AGENT_CONFIG_SYNC_TEST_ROOT-Env-Guard.
• Nutzerneutral: Platzhalter in SKILL.md/CONFIG/Templates; registry.json/cache.json gitignored.
• Versionierungs-Konformitaet: last_sync_from_origin: null (originaerer custom-Skill), status: active, in registry/components.json aufgenommen.
• Supersede-Relation zu mcp-config-sync in references/legacy-mcp-config-sync.md und SKILL.md-Kopftext modelliert.
• i18n: SKILL.md (DE, primaer) + SKILL.en.md (EN, vollstaendig).

0.1.0 (2026-06-20)

• Initiales Scaffold: Protokoll-SKILL.md, Registry/Config/Cache-Modell (Template + Doku), Lernmechanismus (Systemsuche/WebSearch/Context7), scripts/sync.py-Stub (--status/--plan). Umschliesst mcp-config-sync als Spezialfall.