CodeAlmanac – Codebase-Wiki für KI-Coding-Agenten

• Ein lebendiges Wiki, das Entscheidungen, Abläufe, Invarianten und Fallstricke (Gotchas) festhält, die sich nicht allein im Code abbilden lassen, und KI-Agenten damit Kontext liefert
  • Dokumentiert, warum das System seine aktuelle Form hat, was in der Vergangenheit kaputtging und wie Workflows über Dateien/Services hinweg verlaufen
• Das Wiki wird als Markdown-Dateien im Repository gespeichert und kann nach lokaler Indexierung wie Code in Git gereviewt werden
• Agenten und Menschen verwenden dieselben lokalen Lesebefehle: search, show, topics, health, validate
  • Unterstützt Suche nach Dateipfaden mit search --mentions src/checkout/; mit --wiki <name> lassen sich andere Wikis abfragen
• Lifecycle-Aufgaben zur kontinuierlichen Aktualisierung des Wikis werden über drei explizite Agenten ausgeführt: build / ingest / garden
  • Nutzt das separat veröffentlichte Yoke SDK
  • ingest: integriert Dateien, Verzeichnisse, Git-Diffs, Commit-Bereiche, GitHub-PRs/-Issues, URLs und Transkripte lokaler Agenten ins Wiki
  • garden: räumt veraltete Seiten, schwache Links, Topics, doppelte Seiten usw. auf
• Damit man sich keine Wartungsbefehle merken muss, werden drei Arten von lokalen macOS-launchd-Background-Jobs bereitgestellt
  • Sync (alle 5 Stunden): scannt aktuelle Codex-/Claude-Unterhaltungen und reiht sie per ingest-Job für das relevante Wiki ein
  • Garden (alle 24 Stunden): prüft bei allen registrierten Wikis Wissen auf Veralterung, Duplikate und schwache Verknüpfungen
  • Update (alle 24 Stunden): aktualisiert die CLI nur zu sicheren Zeitpunkten automatisch; wird übersprungen, wenn Lifecycle-Aufgaben laufen
• Vollständig lokale Ausführung statt Hosting-Service oder Cloud-Synchronisierung; Logs werden unter ~/.codealmanac/logs/ gespeichert
• Ausführungshistorien bleiben als lokale Job-Records erhalten und sind auch nach dem Schließen des Terminals abrufbar
  • jobs, jobs show, jobs logs, jobs attach, jobs cancel
  • Mit --json in Skripte integrierbar
• Provider nutzen almanac-yoke als zentrale Schnittstelle; Codex verwendet app-server, Claude das Python Agent SDK
  • OAuth-Sessions aus bestehendem Codex/Claude Code werden wiederverwendet
• Der lokale Viewer, der mit serve gestartet wird, ist schreibgeschützt und rendert Navigation für Seiten/Suche/Topics/Backlinks/Dateireferenzen
• Lifecycle-Agenten laufen mit weitreichenden, nicht interaktiven Dateisystemberechtigungen
  • Der Ordner almanac/ ist eine Richtlinie für Anweisungen/Commits, keine OS-Sandbox; daher nur in vertrauenswürdigen Repositories ausführen
• Telemetrie ist optional. Code/Pfade/Prompts/Transkripte/Zugangsdaten werden nicht übertragen, GeoIP ist deaktiviert; Blockierung ist auch mit DO_NOT_TRACK=1 möglich
• Apache-2.0-Lizenz