nub/docs/FEATURES.md

nub — Feature-Übersicht

Diese Seite beschreibt, was nub kann, aus Anwendersicht. Für die Architektur dahinter siehe KONZEPT.md, für Bau-/Test-Anleitungen siehe die README und TESTING.md.

Grundprinzip

nub ist ein terminal-nativer Coding-Agent: ein einzelnes Go-Binary ohne Laufzeit-Abhängigkeiten, das mit einem LLM über Tool-Calling zusammenarbeitet, um Aufgaben in einem Code-Repository zu erledigen — Dateien lesen und ändern, Befehle ausführen, Tests laufen lassen, und das Ganze über mehrere Schritte hinweg, bis die Aufgabe erledigt ist.

Zwei Bedienmodi:

• TUI (Standard, wenn stdin/stdout ein Terminal sind) — interaktive Oberfläche mit Streaming-Anzeige, Farb-Hervorhebung, Diff-Overlay und Slash-Kommandos.
• Print-Modus (-p) — zeilenbasiert über stdin/stdout, für Skripte, Pipes und Automatisierung.

Beide Modi sind dünne Consumer desselben Event-Streams; der Kern-Loop kennt keinen von beiden und verhält sich in beiden identisch.

Agent-Loop

• Streaming-Antworten — Text erscheint, während das Modell es erzeugt, nicht erst am Ende.
• Paralleles Tool-Calling — fordert das Modell mehrere Tool-Aufrufe in einem Schritt an, laufen sie gleichzeitig statt nacheinander.
• Steering — während der Agent noch arbeitet, eine neue Nachricht schicken (TUI: Enter); sie wird eingeschleust, sobald der aktuelle Tool-Aufruf fertig ist, ohne auf das Ende des ganzen Turns zu warten.
• Follow-up-Queue — alternativ eine Nachricht für nach dem aktuellen Turn vormerken (TUI: Alt+Enter), statt den laufenden Gedankengang zu unterbrechen.
• Sicherheitsgrenzen — Obergrenze für Turns pro Anfrage, Timeout pro Tool-Aufruf, automatische Erkennung, wenn das Modell denselben Tool-Aufruf wiederholt in eine Schleife läuft.
• Sauberer Abbruch — Ctrl+C (TUI) bzw. Ctrl+C im Print-Modus bricht einen laufenden bash-Aufruf inklusive aller Kindprozesse ab, statt sie als Zombies zurückzulassen.

Eingebaute Tools

Tool	Was es tut
read	Datei mit Zeilennummern lesen, mit Offset/Limit für große Dateien
write	Datei vollständig (neu) schreiben
edit	Gezielter String-Ersatz; bei mehrdeutigem Treffer Fehler statt Raten
bash	Shell-Befehl ausführen, mit Timeout und sauberem Abbruch
glob	Dateien per Muster finden, .gitignore wird respektiert
grep	Volltextsuche mit Kontextzeilen
todo	Fortschritts-Liste für lange Aufgaben (nur In-Memory)
read_skill	Vollständigen Inhalt eines Skills nachladen (siehe unten)
question	Freitext-Rückfrage an den Nutzer stellen (in der TUI als Block im Transkript, Antwort kommt als normales Tool-Ergebnis zurück; im Print-Modus ein harter Fehler, siehe unten)

Dazu kommen automatisch alle Tools, die über angebundene MCP-Server verfügbar sind (siehe „MCP" unten).

Sessions

• Jede Konversation ist ein Baum, kein linearer Verlauf — jederzeit lässt sich zu einem früheren Punkt zurückspringen und von dort aus neu weiterarbeiten, ohne den ursprünglichen Verlauf zu verlieren.
• Persistenz: Jede Session wird fortlaufend auf die Platte geschrieben (.nub/sessions/), nicht erst beim Beenden — ein Absturz verliert keine Historie.
• Fortsetzen: nub resume <session-id> nimmt eine frühere Session genau dort wieder auf, wo sie aufgehört hat.
• Rewind/Branch: Auf einen früheren Punkt zurückspringen und neu weiterarbeiten erzeugt einen zweiten Ast — beide bleiben erhalten und einzeln aufrufbar (TUI: /tree oder /branch; CLI: nub resume --branch).
• Sessions auflisten: nub sessions zeigt alle Sessions im aktuellen Verzeichnis mit Kurzbeschreibung.
• Session-Wechsel ohne Neustart: In der TUI listet /sessions alle Sessions des Projekts; Enter wechselt live zur gewählten Session (der bisherige Verlauf wird aus der Historie neu aufgebaut), Entf löscht eine Session unwiderruflich (mit Rückfrage). Die gerade aktive Session lässt sich nicht löschen.

Kontext

• Automatischer System-Prompt aus Basis-Prompt, Umgebungsinfo (OS/Shell/Repo-Root/Branch) und konfigurierten Kontext-Dateien (Default: AGENTS.md, REPOMAP.md).
• walk_up: Kontext-Dateien werden nicht nur im Repo-Root gesucht, sondern auf dem Weg vom aktuellen Verzeichnis dorthin eingesammelt — näher am Arbeitsverzeichnis gewinnt inhaltlich.
• Budget-Kontrolle: Kontext-Dateien werden auf ein Token-Budget begrenzt; bei Überschreitung wird sichtbar gekürzt statt still abgeschnitten.
• nub map: generiert eine REPOMAP.md mit Verzeichnisbaum und exportierten Symbolen (Go: über go/ast, andere Sprachen: Dateikopf als Fallback). Warnt, wenn die Repomap gegenüber dem aktuellen Git-Stand veraltet ist.
• SYSTEM.md: eine Datei im Repo-Root überschreibt den eingebauten Basis-System-Prompt vollständig, für projektspezifisches Verhalten.

Auto-Compaction & Tokens

• Sobald der geschätzte Kontextverbrauch eine Schwelle (Default 75 % des Modell-Fensters) überschreitet, fasst nub die ältere Hälfte der Session automatisch zusammen (bearbeitete Dateien, Entscheidungen, offene Aufgaben) und ersetzt sie durch eine kompakte Zusammenfassung — die letzten Turns bleiben immer im Original erhalten.
• Die Zusammenfassung ist nicht destruktiv: der Originalverlauf bleibt im Session-Baum erhalten, ein Rewind auf einen Punkt davor funktioniert weiterhin.
• Manuell erzwingen: /compact (TUI) oder nub compact <session-id>.
• Die Token-Schätzung kalibriert sich während des Laufs gegen die tatsächlich vom Provider gemeldete Token-Nutzung.

Skills

• Wiederverwendbare Anleitungen für wiederkehrende Aufgaben (z.B. „Vorgehen bei Refactorings"), als Markdown-Datei mit kurzem Frontmatter (Name + Beschreibung) unter .nub/skills/<name>/SKILL.md oder global unter ~/.nub/skills/.
• Progressive Disclosure: Nur Name und Beschreibung stehen im System-Prompt (~30 Token pro Skill). Der volle Inhalt wird erst geladen, wenn das Modell ihn über read_skill tatsächlich braucht — spart Kontext bei Skills, die in der aktuellen Aufgabe gar nicht relevant sind.
• nub skills (CLI) bzw. /skills (TUI) zeigen, was gefunden wurde.
• Als Slash-Command: Jeder Skill ist in der TUI direkt per /<name> [Zusatzinfo] aufrufbar — schickt eine kurze Direktive statt den Body einzufügen, das Modell lädt ihn weiterhin selbst nach. Eingebaute Kommandos gewinnen bei Namenskollision.

MCP (Model Context Protocol)

• Externe Tool-Server lassen sich per Config anbinden ([[mcp]]-Einträge: lokaler Prozess über stdio oder ein HTTP-Endpoint).
• Alle konfigurierten Server werden parallel verbunden, mit Timeout — ein nicht erreichbarer oder kaputter Server verhindert den Start nicht, sondern fällt mit einer Warnung raus.
• Tools erscheinen mit <server>__-Präfix, um Namenskollisionen zwischen Servern zu vermeiden.
• Allowlist: pro Server lässt sich einschränken, welche Tools geladen werden (tools = [...]); ohne Allowlist wird ab 15 Tools gewarnt, weil das spürbar Kontext kostet.
• Profile: [profiles] in der Config gruppiert Server, sodass sich z.B. nur die für eine Code-Review relevanten Server verbinden lassen (--profile review), statt immer alle.
• nub mcp (CLI) bzw. /mcp (TUI) zeigen verbundene Server und ihre Tools.

TUI-Details

• Streaming mit Markdown-Rendering: laufender Text erscheint sofort, fertige Antworten werden nachträglich als Markdown formatiert.
• Diff-Overlay: Datei-Änderungen (write/edit) erscheinen farbig (+/-) direkt im Transkript.
• Farbliche Unterscheidung zwischen eigenen Nachrichten, Assistant-Text, Tool-Aufrufen/-Ergebnissen, Slash-Kommando-Ausgaben, Hintergrund- Ereignissen (z.B. Auto-Compaction) und echten Fehlern — alle Farben passen sich automatisch an helle oder dunkle Terminals an.
• Eingabe-Historie (↑/↓), Scrollen der Nachrichtenliste (PgUp/PgDn, Ctrl+U/D, Mausrad).
• Interaktives Baum-Modal (/tree, /branch) zum Durchsuchen und Auswählen früherer Punkte der Session.
• Export: /export [pfad] schreibt das komplette Transkript als Markdown-Datei.

Konfiguration

• Geschichtet: eingebaute Defaults → ~/.config/nub/config.toml (global) → .nub/config.toml (projektlokal) → NUB_*-Umgebungs- variablen — spätere Schicht gewinnt.
• Mehrere Endpoints: beliebig viele [[endpoint]]-Einträge (OpenAI, lokale Server wie Ollama/LM Studio/vLLM, …), einzeln in ihren Fähigkeiten konfigurierbar (z.B. parallel_tool_calls = false für Server, die das nicht unterstützen).
• Ohne jede Config-Datei funktioniert nub bereits mit sinnvollen Defaults gegen die echte OpenAI-API.
• nub init (CLI) bzw. /init (TUI) legen .nub/config.toml mit einer vollständig kommentierten Beispiel-Config (inkl. Permissions- Beispiel) sowie ein minimalistisches AGENTS.md an — beides nur, falls noch nicht vorhanden, nichts wird überschrieben.

Sicherheit & Robustheit

• Permissions pro Tool: read/glob/grep/write/edit/bash lassen sich einzeln auf auto, ask (Rückfrage in der TUI, im Print-Modus ein harter Fehler) oder deny setzen. deny_paths/ deny_bash sperren zusätzlich bestimmte Pfade bzw. Befehlsmuster, unabhängig vom sonst konfigurierten Modus.
• question-Tool: generische Rückfrage-Fähigkeit, die sowohl das Modell selbst als auch Skills (per Anweisung) nutzen können, um eine Freitext-Frage (optional mit Vorschlägen) an den Nutzer zu stellen und die Antwort direkt als Tool-Ergebnis zurückzubekommen — dieselbe Mechanik wie bei einer ask-Permission-Rückfrage, nur nicht an ein bestimmtes Tool gebunden. In der TUI erscheint sie als Block im Transkript (kein Overlay); die nächste Eingabe wird als Antwort gewertet statt als neue Nachricht oder Slash-Kommando. Im Print-Modus liefert sie einen klaren Fehler statt zu blockieren, da Print bewusst headless laufen soll.
• Datei-Tools sind auf das Repository beschränkt (inkl. Auflösen von Symlinks, um ein Verlassen des Repo-Roots zu verhindern).
• Sessiondateien haben restriktive Dateirechte (0600) und werden automatisch von Git ausgeschlossen (.git/info/exclude, nicht .gitignore — das bleibt Sache des Projekts).
• Kein Tool-Aufruf endet ohne Ergebnis — auch bei Abbruch oder Fehler bekommt das Modell eine verwertbare Antwort statt eines hängenden Zustands.