ctx-manager

Ein anbieterunabhängiges Context-Engineering-CLI und MCP-Server für die agentische Entwicklung in mehreren Sprachen.

ctx-manager sitzt zwischen Ihrem Docs/-Ordner (PRDs, Architekturdokumente, Phasenpläne, API-Spezifikationen) und KI-Coding-Agenten (Claude Code, Cursor, Windsurf) und reduziert Token-Ausgaben auf zwei Arten:

• Deterministisches, headerbasiertes Dokument-Slicing – ziehen Sie genau den Abschnitt, den Sie benötigen, aus einer Blaupausendatei, nicht das Ganze. Strukturell (Regex über Markdown-Header), nicht RAG/Embeddings.

• Ein append-only, git-validiertes Memory_Ledger.md – genauer Sitzungszustand, damit Agenten nicht neu ableiten oder halluzinieren, was bereits gebaut wurde. Jeder Eintrag wird vor der Markierung als verifiziert gegen die tatsächliche git status-Ausgabe geprüft.

Funktioniert identisch über Rust, Go, TypeScript, Python oder jeden anderen Stack hinweg – ctx-manager berührt niemals Ihren Anwendungscode, nur Docs/.

Installation

uvx --from ctx-manager ctx --help

Kein Virtualenv-Setup, keine globale Installation erforderlich.

Related MCP server: Claude Session MCP

Verwendung

Eine Blaupausendatei nach Header slicen:

ctx build --slice "PRD.md > 5. Feature List"

Gibt den Inhalt des übereinstimmenden Abschnitts auf stdout aus – leiten Sie ihn in CLAUDE.md oder dorthin, wo Ihr Agent Kontext liest.

Nächste Phase automatisch slicen, basierend auf der Ledger-Historie:

ctx build --auto-phase

Liest Memory_Ledger.md für die zuletzt abgeschlossene Phase und slict automatisch den Abschnitt der nächsten Phase aus Phase_file.md – kein manuelles --slice-Ziel erforderlich. Fällt mit einer Warnung auf Phase 0 zurück, wenn das Ledger noch keine abgeschlossenen Phasen enthält.

Einen verifizierten Eintrag zum Sitzungs-Ledger hinzufügen:

ctx append-ledger --summary "Implemented the login endpoint" --category completed

Prüft git status gegen Ihr Projekt, bevor geschrieben wird, und stellt dem Eintrag [Verified: N files changed], [Reasoning/State Only] oder [Unverified: not a git repo] voran, je nachdem, was gefunden wird – so wird die selbst gemeldete „fertig“-Behauptung eines Agenten gegen das geprüft, was tatsächlich auf der Festplatte passiert ist.

Als MCP-stdio-Server ausführen (für Cursor, Windsurf, Claude Desktop):

ctx mcp

Stellt query_slice, append_ledger_entry und get_current_phase als MCP-Tools bereit und ruft dabei exakt denselben Codepfad wie die obigen CLI-Befehle auf.

Konfiguration

ctx-manager sucht von Ihrem aktuellen Verzeichnis aus aufwärts nach .context/config.toml. Wenn keine gefunden wird, verwendet es sinnvolle Standardwerte (Docs/-Ordner, Memory_Ledger.md usw.) und warnt einmal.

[project]
docs_dir = "Docs/"
ledger_file = "Memory_Ledger.md"
phase_file = "Phase_file.md"

[blueprint_files]
files = ["PRD.md", "Architecture.md", "API_Spec.md"]

[git]
scope = "docs_dir"  # or "repo_root"

Überschreiben Sie die Suche vollständig mit --project-root.

Claude-Code-Integration

Beispielhafte SessionStart/SessionEnd-Hooks (automatisches Aktualisieren von CLAUDE.md vor einer Sitzung über --auto-phase, automatisches Protokollieren im Ledger danach) finden Sie in examples/claude_code_hooks/.

Designprinzipien

1. Docs/ rein, Docs/ raus – berührt niemals Anwendungscode, in keiner Sprache.

2. Billig vor schwer – stdlib re vor Embeddings, subprocess git vor einer Git-Bibliothek, lokales stdio vor jedem Netzwerkdienst.

3. Append-only-Ledger – kein Codepfad überschreibt Memory_Ledger.md vollständig. Niemals.

4. Laut scheitern, nicht leise – ein fehlender Header oder eine fehlende Datei gibt einen expliziten Fehler zurück, niemals leeren Inhalt, auf dem ein Agent halluzinieren könnte.

Siehe Docs/Architecture.md und Docs/PRD.md für die vollständige Designbeschreibung (dieses Projekt dogfoodet sich selbst – sein eigener Docs/-Ordner wird während der eigenen Entwicklung von ctx-manager geslicet und verfolgt).

Einschränkungen

ctx-manager kann einen Agenten nicht daran hindern, es zu umgehen. Nichts hier stoppt einen Agenten mit direktem Dateisystemzugriff, der Docs/PRD.md direkt liest, anstatt über ctx build zu gehen. Dies ist eine strukturelle Grenze, kein fehlendes Feature – ein subprozessbasiertes CLI hat keinen Hook in die Dateilese-Toolaufrufe eines anderen Prozesses.

Wenn Sie tatsächliche Durchsetzung benötigen (nicht nur Konvention), muss diese von der Agentenlaufzeit selbst kommen:

• Claude Code: Verwenden Sie permissions.deny-Regeln in .claude/settings.json, um das Read-Tool zu blockieren, Docs/*.md direkt zu berühren, und erzwingen Sie so die Abhängigkeit von der CLAUDE.md, die ctx build --auto-phase generiert. Siehe die eigenen Berechtigungsdokumente von Claude Code – dies ist nichts, was ctx-manager für Sie konfiguriert.

• MCP-Clients (Cursor, Windsurf usw.): Was auch immer an Dateisystemzugriffskontrollen dieser Client bietet, falls vorhanden – außerhalb der Kontrolle von ctx-manager.

Ohne eine dieser Maßnahmen ist ctx-manager eine Konvention, von der erwartet wird, dass der Agent sie befolgt, gestützt durch verifizierte Sitzungshistorie (das Ledger) – keine Sandbox.

Entwicklung

git clone <this-repo>
cd ctx-manager
uv sync
uv run pytest

Lizenz

MIT – siehe LICENSE.