Code Awareness

Code awareness (experimental) / Code-Awareness (experimentell)

English · Deutsch

English

Since 1.1.1, automatic triggers skip extraction when the graph already covers the source tree. Renames, replaced paths and size changes with preserved modification times invalidate the graph. Changes during a build retain one follow-up. Older manifests rebuild once after the upgrade. Linux watches skip ignored trees (including virtual environments, Rust targets, vendor and coverage); removing watches frees capacity again after a watch-limit failure.

Code awareness — what depends on the file you are editing

Experimental. Code awareness uses Graphify to build a code map of a repository. It can help an agent find its way into an unfamiliar or large repository. For “what breaks if I change this” it measurably did not beat plain search on repositories like ours, and it costs context (the dependents block before edits) and background CPU (graph refreshes).

Off until you turn it on, per repository:

bastra code enable          # in the repository you want it for
bastra code                 # what is enabled, and how current it is
bastra code disable         # turn it off again

With it on, Recall reads a map of your code and tells the agent, before it edits a file, which other files import or call into it. It also adds a find_code tool for looking up a symbol by name instead of grepping for it.

The map is built by Graphify, a separate open-source tool Recall installs on request (see INSTALL.md). It runs locally, reads only code, and sends nothing anywhere — no LLM ever sees your source.

Details worth knowing:

• The map lives in graphify-out/ inside the repository and is excluded from git automatically. It is never committed.
• It refreshes itself after edits, commits and branch switches, usually within a few seconds. While it is behind, anything Recall shows from it is marked as possibly outdated rather than presented as current.
• Nothing is indexed for a repository you have not enabled.
• enable and disable work from anywhere inside the repository and take effect within a few seconds, without restarting anything. A linked git worktree is its own repository and is enabled on its own.
• BASTRA_CODE_AWARENESS=off turns the whole feature off without changing what you enabled.
• In telemetry, the delivered-block count and token cost use the same delivery records. The passive code share means the share of Write/Edit injection, not all hook lanes. Build duration includes successful and failed builds, excluding lock checks and skipped runs.
• macOS and Linux for now.

If something looks wrong, bastra doctor reports the state of every enabled repository, and bastra code rebuild repairs a broken map after asking. A busy build lock is retried after 10, 20, 40, 80, 160 and 320 seconds; further automatic triggers do not shorten these waits. After the seventh locked attempt, automatic refreshes pause and retry once per hour. A successful attempt restores normal refresh triggers; a continuing lock keeps the hourly pace. bastra code index or bastra code rebuild can also update the map manually. The refresh log records the pause. Function anchors accept file.ts#name and file.ts#name() equally; Windows-style CRLF diffs are read normally.

Deutsch

Seit 1.1.1 überspringen automatische Trigger die Extraktion, wenn der Graph den Quellbaum bereits abdeckt. Umbenannte oder ersetzte Pfade sowie Größenänderungen bei unveränderter Änderungszeit machen ihn ungültig. Änderungen während eines Builds behalten einen Folgelauf. Alte Manifeste werden nach dem Upgrade einmal neu gebaut. Linux-Watches überspringen ignorierte Bäume (einschließlich virtueller Umgebungen, Rust-Targets, vendor und coverage); entfernte Watches geben nach einem Watch-Limit-Fehler wieder Kapazität frei.

Code-Awareness — was von der Datei abhängt, die du gerade bearbeitest

Experimentell. Code-Awareness baut mit Graphify eine Code-Karte eines Repositories. Sie kann einem Agenten helfen, sich in einem unbekannten oder großen Repository zurechtzufinden. Bei „was geht kaputt, wenn ich das ändere?“ war sie auf Repositories wie unserem messbar nicht besser als eine einfache Suche, und sie kostet Kontext (der Block mit abhängigen Dateien vor Änderungen) und Rechenzeit im Hintergrund (Aktualisieren der Karte).

Standardmäßig aus, und pro Repository einzuschalten:

bastra code enable          # im gewünschten Repository
bastra code                 # was aktiv ist und wie aktuell es ist
bastra code disable         # wieder ausschalten

Ist es an, liest Recall eine Karte deines Codes und sagt dem Agenten vor einer Änderung, welche anderen Dateien die bearbeitete importieren oder aufrufen. Dazu kommt ein Werkzeug find_code, das ein Symbol beim Namen findet, statt danach zu suchen.

Die Karte baut Graphify, ein eigenständiges Open-Source-Werkzeug, das Recall auf Wunsch mitinstalliert (siehe INSTALL.md). Es läuft lokal, liest ausschließlich Code und schickt nichts irgendwohin — kein Sprachmodell sieht deinen Quelltext.

Was du wissen solltest:

• Die Karte liegt in graphify-out/ im Repository und wird automatisch von Git ausgenommen. Sie wird nie committet.
• Sie aktualisiert sich nach Änderungen, Commits und Branch-Wechseln, meist binnen weniger Sekunden. Solange sie hinterherhinkt, wird alles, was Recall daraus zeigt, als möglicherweise veraltet gekennzeichnet statt als aktuell ausgegeben.
• Für ein Repository, das du nicht aktiviert hast, wird nichts indiziert.
• enable und disable funktionieren von überall im Repository und wirken binnen weniger Sekunden, ohne Neustart. Ein verknüpfter Git-Worktree ist ein eigenes Repository und wird für sich aktiviert.
• BASTRA_CODE_AWARENESS=off schaltet die ganze Funktion ab, ohne deine Aktivierungen zu verändern.
• In der Telemetrie stammen Zahl und Tokenkosten ausgelieferter Blöcke aus denselben Auslieferungen. Der passive Code-Anteil bezieht sich auf die Write/Edit-Einblendung, nicht auf alle Hook-Spuren. Die Build-Dauer umfasst erfolgreiche und fehlgeschlagene Builds, ohne Sperrprüfungen und ausgelassene Läufe.
• Vorerst macOS und Linux.

Wenn etwas nicht stimmt: bastra doctor nennt den Zustand jedes aktivierten Repositories, und bastra code rebuild repariert eine kaputte Karte nach Rückfrage. Eine belegte Build-Sperre wird nach 10, 20, 40, 80, 160 und 320 Sekunden erneut versucht; weitere automatische Auslöser verkürzen diese Pausen nicht. Nach dem siebten gesperrten Versuch werden automatische Aktualisierungen pausiert und einmal pro Stunde erneut versucht. Ein erfolgreicher Versuch gibt die normalen Auslöser wieder frei; bleibt die Sperre belegt, bleibt es beim Stundenabstand. bastra code index oder bastra code rebuild können die Karte auch manuell aktualisieren. Das Aktualisierungslog hält die Pause fest. Funktionsanker akzeptieren datei.ts#name und datei.ts#name() gleichwertig; Diffs mit Windows-Zeilenenden (CRLF) werden normal gelesen.