wctx

Arbeitsbereichskontext für Coding-Agenten.

Ihr System erstreckt sich über mehrere Repositories. Auch der Kontext Ihres Agenten sollte das tun.

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

Eine Coding-Agenten-Sitzung ist auf ein Repository beschränkt, weil dort Dateien bearbeitet werden. Das untersuchte System ist das nicht. Eine Sitzung in Ihrem UI-Repository stellt also fest, dass der Fehler tatsächlich in Ihrem SDK liegt – und wenn Sie eine Woche später eine neue Sitzung im SDK öffnen, ist dieses Wissen verloren.

wctx verwandelt abgeschlossene Agentensitzungen in strukturierten, evidenzbasierten Engineering-Kontext und stellt diesen zukünftigen Sitzungen über MCP zur Verfügung. Lokal zuerst: keine Cloud-Konten, keine Embeddings, kein Transkript-Upload.

Zwei-Minuten-Demo

pnpm install
pnpm demo

Kein API-Key, kein Netzwerk. Es erstellt drei synthetische Repositories, importiert eine abgeschlossene Sitzung aus einem und stellt dann eine Frage in natürlicher Sprache aus einem anderen:

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

Dann ändert sich die SDK-Datei, und die Evidenz ist nicht mehr vertrauenswürdig:

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

Vollständige Anleitung: docs/demo.md.

Related MCP server: obsmcp

Installation

Erfordert Node 22+ und git.

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

MCP-Einrichtung

claude mcp add wctx -- wctx mcp

Oder für Codex und andere MCP-Clients:

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

Sieben Werkzeuge, geordnet nach schrittweiser Offenlegung, damit sie in einem Kontextfenster erschwinglich bleiben:

wctx mcp-info gibt die Oberfläche und Client-Konfigurationsschnipsel aus.

Aufzeichnen, was eine Sitzung gelernt hat

Ein Befehl am Ende einer Sitzung. Er importiert die Sitzung bei Bedarf und zeichnet die Evidenz in einem einzigen Schritt auf, wobei standardmäßig die Sitzung verwendet wird, in der Sie gerade arbeiten:

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

Oder bitten Sie einfach Ihren Agenten, es zu tun – "zeichne auf, was wir gelernt haben" – und er ruft finalize_session mit seiner eigenen Sitzungs-ID auf. Er muss nie eine interne ID kennen, und der wiederholte Aufruf in einer Sitzung sammelt Evidenz an, anstatt die Sitzung zu duplizieren.

Proaktiv machen

Ein Agent tut dies nur, wenn etwas ihn dazu auffordert, und der stärkste Ort, dies zu sagen, ist die eigene Agenten-Datei des Projekts – diese werden bei jeder Anfrage gelesen:

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

Die Anleitung deckt ab, wann gesucht werden soll (vor der Untersuchung von etwas Nicht-Trivialem), wann aufgezeichnet werden soll (Grundursachen, Entscheidungen mit Begründung, mühsam errungene Einschränkungen, ungelöste Fragen, Überraschungen) und was nicht aufgezeichnet werden soll. Das ist der Unterschied zwischen einem Werkzeug, an das man sich erinnert, es zu verwenden, und einem, das sich ansammelt.

Wenn überhaupt keine Zusammenfassung angegeben wird, leitet wctx capture eine sachliche aus den aufgezeichneten Werkzeugaktivitäten der Sitzung ab – Dateianzahl, Befehle, Fehler, geänderte Dateien. Absichtlich langweilig: Eine Erzählung aus Werkzeugaufrufen zu erfinden, wäre genau der selbstbewusste Unsinn, den dieses Projekt sich weigert zu produzieren.

Kernkonzepte

Arbeitsbereich (Workspace) — ein logisches Produkt oberhalb der Repositories. Die Kontextgrenze. Repositories bleiben die Bearbeitungsgrenze; nichts hier erweitert den Schreibbereich eines Agenten.

Repository — ein registrierter Git-Checkout, identifiziert durch seinen echten Pfad (realpath), sodass dasselbe Repository nicht zweimal über einen Symlink oder ein Unterverzeichnis registriert werden kann. Es kann zu mehreren Arbeitsbereichen gehören.

Beziehung (Relation) — eine deklarierte, gerichtete, typisierte Kante (uses, depends_on, calls, imports, consumes_api, provides_api, shares_schema_with, related). Die Traversierung folgt Kanten in beiden Richtungen, denn wenn verify-ui websdk verwendet, dann möchte eine Sitzung in websdk trotzdem wissen, was verify-ui gelernt hat.

Sitzung (Session) — eine normalisierte Coding-Agenten-Sitzung von Xirp, Claude Code oder generischem JSONL, mit ihrem Arbeitsverzeichnis (cwd), Branch, Commit, Nachrichten und Werkzeugaktivitäten.

Evidenz (Evidence) — ein Befund, eine Entscheidung, eine Änderung, eine unbeantwortete Frage, ein bekanntes Problem, eine Architekturnotiz oder eine Einschränkung, angehängt an das Repository, über das sie sich bezieht (oft nicht das, in dem die Sitzung lief), mit den Dateien und Symbolen, die sie betrifft, und dem Commit, bei dem sie gültig war.

Frische (Freshness) — ein git-basiertes Urteil, ob sich die referenzierten Dateien seit diesem Commit geändert haben: current (aktuell), possibly_stale (möglicherweise veraltet), stale (veraltet) oder unknown (unbekannt).

Architektur

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

Details und die Begründung hinter jeder Grenze: docs/architecture.md.

Xirp-Integrationsstatus

Xirp hat sich als echter, dokumentierter Lesepfad herausgestellt, daher ist der Adapter real und kein Platzhalter.

Der Adapter fixiert beide Schema-Strings und meldet sich laut bei einer unbekannten Version, anstatt zu raten. Vollständige Evidenz, einschließlich dessen, was noch unbestätigt ist und wie es reproduziert werden kann: docs/research/xirp.md.

Sicherheit

Nichts verlässt Ihren Rechner. Keine Cloud, keine Telemetrie, keine Embeddings-API, kein Transkript-Upload; die gesamte Abhängigkeitsliste ist @modelcontextprotocol/server, better-sqlite3, commander und zod.

• Transkripte werden in Ihr Datenverzeichnis kopiert (Claude Code löscht seine eigenen nach 30 Tagen) zusammen mit einer geschwärzten Kopie – und nur die geschwärzte Kopie wird jemals ausgeliefert.

• Die Schwärzung umfasst private Schlüssel, JWTs, Autorisierungsheader, AWS/GitHub/Slack/OpenAI/Google-Tokens, berechtigte URLs und geheime Zuweisungen. Es handelt sich um einen Best-Effort-Musterabgleich und ist keine Garantie dafür, dass ein Transkript sicher geteilt werden kann.

• Evidenz, die an Agenten zurückgegeben wird, wird als historische, nicht vertrauenswürdige Daten gekennzeichnet, und anweisungsähnliche Zeilen ("ignoriere alle vorherigen Anweisungen") werden neutralisiert. Abschwächung, keine Immunität.

• Jeder Git-Aufruf verwendet ein Argument-Array, niemals einen Shell-String. FTS5-Abfragen werden konstruiert, niemals interpoliert.

• Transkriptlöschung und Evidenzlöschung sind unabhängige Operationen.

Details: docs/security.md.

Vergleich mit bestehenden Werkzeugen

Fähigkeitsbehauptungen stammen aus der jeweiligen README der Projekte, geprüft am 13.08.2026. Nichts hier behauptet, dass ein anderes Projekt etwas nicht kann.

Vollständige Übersicht mit der Gedächtnisgrenze jedes Projekts, dem Erfassungsmechanismus und dem, was als Idee wiederverwendet wurde: docs/research/competitive-landscape.md.

Evaluierung

Auf einem synthetischen Korpus mit 15 Abfragen und 28 Einträgen (pnpm eval) erschien die relevante frühere Sitzung in den Top Fünf für 15 von 15 Abfragen und belegte den ersten Platz für 11 von 15, mit einer medianen lokalen Retrieval-Latenz von 1,6 ms. Das Hinzufügen der Arbeitsbereichs-Topologie zu einfachem FTS5 ließ die Trefferquote bei diesem Korpus unverändert, verbesserte aber den MRR von 0,839 auf 0,867, machte die Repository-Zuordnung exakt (0,93 → 1,00) und eliminierte Ergebnisse aus nicht verwandten Repositories (0,20 → 0,00 pro Abfrage).

Der Korpus ist klein, synthetisch und von derselben Person geschrieben, die auch die Abfragen geschrieben hat. Was das für die Interpretation der Zahlen bedeutet, wird in docs/evaluation.md dargelegt.

Einschränkungen

Die vollständige Liste: KNOWN_LIMITATIONS.md. Die drei wichtigsten Einschränkungen:

• Die Abfrage ist schlüsselwortbasiert. FTS5 vergleicht Tokens. Eine vollständig umformulierte Anfrage ohne lexikalische Überschneidung kann erfolglos bleiben; strukturelle Verstärkungen gleichen dies nur teilweise aus.

• Aktualität ist keine Verifikation. Sie beantwortet nur „Haben sich die referenzierten Dateien geändert?“, niemals „Ist diese Behauptung noch gültig?“. Eine Verhaltensänderung in einer unberührten Datei bleibt unsichtbar.

• Beziehungen werden deklariert, nicht abgeleitet. Eine nicht deklarierte Beziehung bleibt für die Bewertung unsichtbar.

Roadmap

Geordnet nach dem zu erwartenden Nutzen für die Kernschleife:

1. Automatische Sitzungsabschluss durch einen stop-Hook im Testrahmen (derzeit manuell).

2. Härtung der Xirp-Adapter über verschiedene Versionen und die codex- / gemini-Testrahmen hinweg.

3. Erkennung von Konflikten und Vorschläge zur Ablösung – das Schema unterstützt beides; nichts füllt diese Felder.

4. Import von catalog-info.yaml aus Backstage / Portal hinter der vorhandenen CatalogProvider-Schnittstelle.

5. Ein anspruchsvollerer Evaluationskorpus mit nahezu identischen Befunden, um zu testen, ob die Topologie hilft, zu finden statt nur zu ordnen.

Mitwirken

Siehe CONTRIBUTING.md. pnpm typecheck && pnpm lint && pnpm test müssen bestehen, und pnpm demo muss aus einem sauberen Klon ohne Anmeldeinformationen funktionieren.

Zuschreibung und Nichtzugehörigkeit

wctx ist ein unabhängiges Open-Source-Experiment, inspiriert von öffentlichen Ideen aus Xirp, Spotify Portal, Backstage und MCP.

Es ist weder mit Spotify verbunden noch von Spotify unterstützt.

Es wurde kein Quellcode aus einem der in der Vergleichstabelle aufgeführten Projekte kopiert. Die Backstage-Komponente/System-Unterscheidung dient als Designinspiration, nicht als Laufzeitabhängigkeit, und es wird keine Backstage-Instanz benötigt.

Lizenz

MIT. Siehe LICENSE.