CarryCtx Core Skill

CarryCtx bietet KI-Coding-Agenten erstklassigen Projektstatus und Kontext-Kontinuität. Es ermöglicht Agenten, Aufgaben zu verwalten, granulare Fortschritte zu verfolgen, Checkpoints zu erstellen, AST-Code-Abhängigkeitsgraphen zu pflegen, stdio-MCP-Server auszuführen, Workflow-Vorlagen anzuwenden und Kontext nahtlos über Sitzungsneustarts und Git-Worktrees hinweg zu erhalten.

Wann anwenden

Verwenden Sie CarryCtx-Befehle, wenn:

Sie eine neue Aufgabe oder Sitzung starten: Agentenidentität registrieren, Sitzung starten und Kontext wiederherstellen (carryctx resume).
Sie Projektaufgaben verwalten: Aufgaben erstellen, übernehmen, starten, abschließen, blockieren oder abbrechen (carryctx task ...).
Sie granulare Fortschritte verfolgen: Strukturierte todo-, block-, risk- und note-Elemente erfassen.
Sie Zustand speichern / Checkpoints setzen: Aktuellen Arbeitsfortschritt, Git-Status und verbleibende Arbeiten vor dem Beenden von Sitzungen oder dem Wechsel des Fokus sichern.
Sie den Code-Graphen erkunden: AST-Modul-Abhängigkeiten scannen (carryctx graph scan) und Mermaid/DOT/ASCII-Diagramme exportieren (carryctx graph export).
Sie KI-Agenten-Tool-Integration (MCP) nutzen: Projektkontext für Cursor / Windsurf / AGY über den Model Context Protocol stdio-Server bereitstellen (carryctx mcp).
Sie Arbeitsabläufe standardisieren (Presets): Projekt-Workflow-Blaupausen, Codierungsregeln und Agenten-Personas auflisten, inspizieren und anwenden (carryctx preset ...).
Sie parallele Aufgaben bearbeiten: Aufgaben in dedizierten Git-Worktrees erstellen und isolieren (carryctx worktree ...).
Sie Gesundheitsprobleme diagnostizieren: carryctx doctor ausführen, um verwaiste Aufgaben, fehlende Hooks und Datenbankprobleme aufzudecken.
Sie alte Daten bereinigen: carryctx project prune verwenden, um abgeschlossene Aufgaben zu bereinigen und die Datenbank schlank zu halten.
Sie Agenten-Analysen durchführen: carryctx stats verwenden, um Agenten-Sitzungslängen, Aufgabenmetriken zu prüfen und Markdown/CSV-Berichte zu exportieren.
Sie frühere Arbeiten inhaltlich suchen: carryctx search "<query>" verwenden, um Aufgaben, Fortschrittselemente, Checkpoints oder Entscheidungen per Stichwort zu finden, anstatt SQL zu schreiben oder Commit-Nachrichten zu durchsuchen.

Voraussetzungen

CarryCtx CLI installieren (cargo install carryctx oder vorkompiliertes Binary).
CarryCtx im Projekt-Repository initialisieren: carryctx init.

Kurzreferenz

Aktion	Befehl	Zweck
Agent einrichten	`carryctx agent register --name "$(whoami)" --provider "claude-code"`	Agentenidentität registrieren
Aktueller Agent	`carryctx agent current`	Aktive Agentenidentität anzeigen
Sitzung starten	`carryctx session start`	Verfolgte Arbeitssitzung beginnen
Kontext wiederherstellen	`carryctx resume`	Aktuelle Aufgabe, Fortschritt & nächste Aktionen abrufen
Aufgabe erstellen	`carryctx task create --title "..." [--depends-on CTX-0001]`	Neue Aufgabe definieren
Aufgabe übernehmen	`carryctx task claim CTX-0001`	Aufgabe dem aktuellen Agenten zuweisen
Aufgabe bearbeiten	`carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]`	Titel, Priorität oder Beschreibung der Aufgabe aktualisieren
Aufgabe starten	`carryctx task start CTX-0001`	Aufgabe als in Bearbeitung markieren
Fortschritt verfolgen	`carryctx progress <todo	block
Checkpoint	`carryctx checkpoint --done "..." --remaining "..."`	Semantisch reichhaltigen Zustands-Snapshot speichern
Code-Graph scannen	`carryctx graph scan`	AST-Abhängigkeiten in SQLite-Graph extrahieren
Graph exportieren	`carryctx graph export --type <mermaid	dot
MCP Stdio-Server	`carryctx mcp`	MCP-stdio-Server mit 6 Agententools starten
Preset anwenden	`carryctx preset apply <preset_name>`	Workflow-SOPs, Regeln oder Personas einspielen
Worktree	`carryctx worktree create CTX-0001`	Isolierten Git-Worktree für Aufgabe erstellen
Sitzung beenden	`carryctx session end`	Sitzung sicher mit Checkpoint beenden
Doctor	`carryctx doctor`	Projektgesundheit diagnostizieren
Hooks installieren	`carryctx hooks install`	Auto-Checkpoint bei jedem Git-Commit
Daten bereinigen	`carryctx project prune --older-than 30`	Alte abgeschlossene Aufgaben bereinigen
Agenten-Statistiken	`carryctx stats [--markdown] [--output file.csv]`	Metriken einsehen und Leistungsberichte exportieren
Entscheidung	`carryctx decision add --title "..." --task CTX-0001`	Architekturentscheidung erfassen
Übergabe	`carryctx handoff create --target <agent> --task CTX-0001`	Arbeit zwischen Agenten übergeben
Sitzung pausieren	`carryctx session pause`	Aktive Sitzung pausieren (Timer stoppt)
Sitzung fortsetzen	`carryctx session resume`	Pausierte Sitzung fortsetzen
Suchen	`carryctx search "" [--type task	progress

Ausgabeverhalten (0.5.2+)

Die Textausgabe (Standard --format text) ist absichtlich kompakt: Entity-Befehle geben eine kurze Zeile pro Datensatz aus (Task created: CTX-0321, agent current gibt nur den Namen aus, Listen zeigen display_id, Status und einen gekürzten Titel/Zusammenfassung), sodass der Agentenkontext klein bleibt. Wenn vollständige Datensätze benötigt werden:

--verbose (globales Flag) oder [output] verbose = true in .carryctx/config.toml stellt die vollständige, hübsch formatierte Ausgabe wieder her.
--fields display_id,status,summary (globales Flag) oder die befehlsspezifische Tabelle [output.fields] schneidet Datensätze auf eine Positivliste in Text und JSON zu.
--format json gibt immer den vollständigen Umschlag zurück.

Die JSON-Ausgabe bleibt unverändert und ist der Maschinenvertrag: Jeder Erfolg ist ein einzelner Umschlag auf stdout, jeder Fehler ein einzelner Umschlag auf stderr.

Standard-Agenten-Workflow

1. Sitzungsinitialisierung & Kontextwiederherstellung

Zu Beginn jeder Interaktion oder nach einem Agentenneustart:

# Identität registrieren und festlegen, falls nicht bereits konfiguriert
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"

# Sitzung starten und aktuellen Kontext laden
carryctx session start
carryctx resume

Sitzungen pausieren und fortsetzen:

carryctx session pause    # Aktive Sitzung pausieren (Timer stoppt)
carryctx session resume   # Pausierte Sitzung fortsetzen
carryctx session end      # Sitzung mit optionalem Checkpoint beenden
carryctx session abandon  # Sitzung ohne Checkpoint beenden

2. Code-Abhängigkeitsanalyse (Graph-Subsystem)

Vor dem Ändern von Code oder dem Refactoring von Modulen:

# 1. AST-Abhängigkeiten der Codebasis scannen
carryctx graph scan

# 2. Sub-Graphen exportieren, zentriert um ein bestimmtes Modul
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2

# 3. Kompakte ASCII-Architekturübersicht auf Modulebene exportieren
carryctx graph export --type ascii --compact

3. Workflow-Presets & Regel-Injektion

Standardarbeitsanweisungen oder Kodierrichtlinien einspielen:

# Verfügbare Workflow-Presets auflisten
carryctx preset list

# Ein Standard-Bugfix-Workflow-Preset auf das aktuelle Projekt anwenden
carryctx preset apply workflows/bugfix

4. Aufgaben-Lebenszyklus

# Offene Aufgaben auflisten
carryctx task list --status ready

# Aufgabe übernehmen & starten
carryctx task claim CTX-0001
carryctx task start CTX-0001

# Aufgabe nach Überprüfung als abgeschlossen markieren
carryctx task complete CTX-0001

5. Granulare Fortschrittsverfolgung

Während der Arbeit strukturierte Fortschrittselemente protokollieren:

carryctx progress todo "Unit-Test für Auth-Middleware schreiben"
carryctx progress todo "JWT-Token-Validierung implementieren"
carryctx progress block "Warte auf Bestätigung der API-Endpunkt-Spezifikation"
carryctx progress risk "Breaking Change in Upstream-Abhängigkeit"
carryctx progress note "LRU-Cache verwendet, um Token-Nachschlagevorgänge zu optimieren"
# Ein Todo als abgeschlossen markieren:
carryctx progress complete PX-0001

6. Checkpoints erstellen

Zustand vor dem Beenden einer Sitzung, dem Wechseln von Aufgaben oder dem Übergeben von Arbeit speichern:

carryctx checkpoint \
  --done "Backend-Authentifizierungsendpunkte fertiggestellt" \
  --remaining "Frontend-Login-Formular-Integration" \
  --blocker "Keine"

7. Worktree-Parallelität

Bei gleichzeitiger Arbeit an unabhängigen Aufgaben:

carryctx worktree create CTX-0002
# Wechselt in ein isoliertes Worktree-Verzeichnis, das mit CTX-0002 verknüpft ist

7a. Entscheidungen & Übergaben aufzeichnen

Architekturentscheidungen erfassen und Arbeit zwischen Agenten übergeben:

# Eine Architekturentscheidung (ADR) verknüpft mit einer Aufgabe erfassen
carryctx decision add --title "SQLite für Speicherung verwenden" --task CTX-0001

# Entscheidungen auflisten oder durchsuchen
carryctx decision list
carryctx decision search --keyword SQLite

# Eine Entscheidung als durch eine neuere ersetzt markieren
carryctx decision supersede DEC-0001 --by DEC-0002

# Eine Übergabe erstellen, um Arbeit an einen anderen Agenten zu übergeben
carryctx handoff create --target <agent-ulid> --summary "API implementieren" --task CTX-0001

# Eine Übergabe annehmen, ablehnen oder schließen
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "Nicht mein Bereich"
carryctx handoff close HO-0001

7b. Volltextsuche in der Projekthistorie

Frühere Arbeiten nach Inhalt finden, nicht nach Erinnerung, welcher Branch oder welche Aufgabe sie berührt hat. Durchsucht Aufgabentitel/-beschreibungen, Fortschrittselemente, Checkpoint-Notizen und Entscheidungen, alle nach Relevanz sortiert:

# Alles durchsuchen
carryctx search "Markdown-Worker-Protokoll"

# Auf eine Entitätsart eingrenzen
carryctx search "Retry-Backoff" --type checkpoint

# Nach Status oder Besitzer der zugehörigen Aufgabe eingrenzen
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code

Jeder Treffer enthält die Anzeige-ID, den Status und (falls bekannt) den Branch der zugehörigen Aufgabe – verwenden Sie dies, bevor Sie verwandte Arbeiten beginnen, um bereits gelöste Probleme nicht zu duplizieren, und vor einer Übergabe, um den empfangenden Agenten auf den genauen Checkpoint oder die Entscheidung zu verweisen, die eine frühere Wahl erklärt.

8. Sitzung beenden & Bericht

# Arbeitssitzung beenden
carryctx session end

# Projekt-Statistikbericht für PR-Beschreibung oder Dokumentation exportieren
carryctx stats --markdown --output /tmp/project_stats.md

9. Model Context Protocol (MCP)-Integration

Um CarryCtx direkt in Cursor / Windsurf / AGY einzubinden:

{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}

Verfügbare MCP-Tools:

carryctx_graph_explorer: Projekt-Kontext-Graphen abfragen, scannen und exportieren
carryctx_context_manager: Persistenten Kontext, Checkpoints und Zustands-Snapshots verwalten
carryctx_task_manager: Projektaufgaben, Abhängigkeiten und Prioritäten verwalten
carryctx_progress_tracker: Aufgabenfortschritt, Notizen und Blocker verwalten
carryctx_decision_logger: Architekturentscheidungen protokollieren und durchsuchen
carryctx_project_admin: Projektdatenbank, Statistiken, Kaltspiegel-Archivierung und Konfiguration verwalten

10. Debugging & Fehlerbehebung

Strukturierte Debug-Protokollierung aktivieren, um Probleme zu diagnostizieren:

# Debug-Logs für CarryCtx-Operationen anzeigen
export RUST_LOG=carryctx=debug
carryctx task list          # Debug-Ausgabe vor Befehlsausgabe sehen

# Nur Fehler anzeigen
export RUST_LOG=error
carryctx status

# Diagnose ausführen
carryctx doctor             # Projektgesundheit prüfen
carryctx doctor --json      # Maschinenlesbare Diagnoseausgabe

Best Practices für Coding-Agenten

Immer carryctx resume beim Start ausführen: Orientiert den Agenten sofort zur aktuellen Aufgabe und zum Fortschritt.
Code-Graphen vor großen Refactorings scannen: carryctx graph scan verhindert defekte Upstream-Abhängigkeiten.
Aufgaben explizit übernehmen: Verhindert doppelte Ausführung, wenn mehrere Agenten am selben Repository arbeiten.
Strukturierte Fortschrittselemente verwenden: todo, done und block während der Ausführungsschritte aktuell halten.
Vor dem Anhalten einen Checkpoint setzen: Immer einen Checkpoint erstellen, bevor Sie die Kontrolle abgeben oder komplexe mehrschrittige Arbeiten abschließen.
carryctx doctor bei erster Verwendung oder nach einem Upgrade ausführen: Deckt Einrichtungslücken auf, bevor sie Laufzeitfehler verursachen.

CarryCtx – Agent Skill für persistenten Projektkontext

Was ist CarryCtx – Agent Skill für persistenten Projektkontext?

In Ihrer bevorzugten KI fragen

Dokumentation