ki-grok/03-die-interaktive-tui-im-detail.md

Kapitel 3

Die interaktive TUI im Detail

Kern in einem Satz: Die TUI ist dein Cockpit: Scrollback zeigt die Wahrheit (Tools, Diffs, Denken), der Prompt steuert den nächsten Schritt – und wer Fokus, Abbruch und Modes beherrscht, spart Stunden „der Agent macht komische Dinge“.

---

3.1 Warum die TUI zuerst meistern

Headless und ACP (Kapitel 10–11) nutzen dieselbe Engine. In der TUI siehst du aber live, was der Harness tut: welcher Tool-Call, welcher Diff, welche Freigabe, welcher Mode. Wer nur Headless lernt, debuggt Permissions später blind.

Alltagsschmerz: Du tippst einen langen Auftrag, der Agent startet, du merkst den Fehler im Prompt – und findest Esc / Ctrl+C nicht. Oder du scrollerst im Diff und landest versehentlich im Always-approve-Mode. Dieses Kapitel macht die Gesten bewusst.

Zwei Lesegeschwindigkeiten (Day-1 = erste Lernsession, siehe Vorwort):

Pfad	Kurz	Wann
Day-1-Cockpit (~20 Min.)	Fokus, Abbruch, Modes, @/!, Kurz-Slash, Sessions 1–2	Grok Build neu; nach Kapitel 2
Referenz / Vertiefung	Vim, Navigation, Queue, volle Shortcuts, Sessions 3–4	Stecken geblieben oder Alltag ausreizen

Day-1 im Detail (Reihenfolge):

1. 3.2–3.3 Anatomie und Fokus
2. 3.4 nur Merksatz Esc vs. Ctrl+C (Tabelle skimmen)
3. 3.5 Modes
4. 3.7 nur @ und !
5. 3.8 Slash-Kurzreferenz
6. 3.11–3.13 Sessions 1–2 und Parcours-Pflichtteil

Referenz bei Bedarf: 3.4 Edge-Cases (Vim-Esc, Steal-Esc); 3.6; History/Multiline/Queue in 3.7; 3.9–3.10; Sessions 3–4.

Du musst die Shortcut-Tabellen nicht auswendig können, bevor Plan Mode (Kapitel 4) kommt. Muskeln zuerst: Fokus, Abbruch, Mode erkennen, Diff lesen. Was du heute änderst: Day-1-Pfad fahren, Rest bookmarken.

Übungsrepo: weiter beispiele/todo-cli/ aus Kapitel 2 – oder dein Side-Projekt.

---

3.2 Anatomie der Oberfläche

Nach dem Login siehst du im Wesentlichen zwei Zonen plus Overlays: den Scrollback oben und den Prompt unten. Wer die Rollen kennt, sucht Shortcuts nicht im falschen Fokus und liest Diffs dort, wo sie erscheinen.

Teil	Was du siehst	Wofür
Scrollback	Prompts, Antworten, Thinking, Tool-Calls, Diffs, Tasks	Lesen, navigieren, collapsen, kopieren
Prompt	Eingabezeile unten	Aufträge, /-Commands, @-Anhänge, !-Shell
Overlays	Slash-Menü, File-Picker, Settings, Session-Picker, …	Harness steuern, ohne den Chat zu „überreden“

Was du mitnimmst: Scrollback = Review-Oberfläche; Prompt = Steuerung; Overlays = Harness-Menüs. Sticky User-Prompts im Scrollback helfen, Turns zu scannen: „Wo habe ich den Scope gesetzt?“ ist oft die bessere Frage als „Warum ist das Modell dumm?“.

Thinking-Blöcke (wenn das Modell Reasoning liefert) sind collapsbar – nützlich zum Nachvollziehen, teuer im Scroll-Rauschen. Ctrl+E expandiert/collapst Thinking global (Kapitel-Shortcuts unten).

Tool-Calls streamen in Echtzeit: Shell-Output, Suchtreffer, Inline-Diffs bei Edits. Das ist deine Review-Oberfläche, nicht nur Dekoration.

---

3.3 Fokus: Prompt vs. Scrollback

Geste	Wirkung
Tab	Fokus wechseln Prompt ↔ Scrollback
Space (Scrollback fokussiert, Simple Mode)	Prompt fokussieren
Enter (Prompt fokussiert)	Nachricht senden

Warum Fokus trainieren? Viele Shortcuts gelten nur im Scrollback (Navigation, Fold, Copy). Tippe „blind“ im Scrollback-Modus, landet Text im Prompt – oder gar nicht, je nach Mode. Faustregel: Schreiben → Prompt fokussiert. Lesen/Review → Scrollback fokussiert.

---

3.4 Abbruch, Clear, Rewind – Esc und Ctrl+C

Das ist der Abschnitt, den du zweimal liest, wenn der erste „hängende“ Turn kommt.

Zustand	Geste	Wirkung
Turn läuft (Default / kein Fullscreen-Vim)	Esc	Turn sofort abbrechen, Draft bleibt
Turn läuft, Fullscreen + Vim-Mode	Esc	kein Cancel – nutze Ctrl+C o. Ä.
Turn läuft, Draft nicht leer	Ctrl+C	zuerst Draft leeren; zweites Ctrl+C auf leerem Prompt cancelt
Idle, Prompt nicht leer	2× Esc (≤800 ms)	Prompt leeren (Text landet in History)
Idle, Prompt leer, es gibt Messages	2× Esc	Rewind-Picker (wie /rewind)
Nach Esc-Cancel ~1 s	doppeltes Esc	Rewind-Arm unterdrückt – kein versehentliches Rewind

Esc vs. Ctrl+C (Merksatz): Esc bricht den laufenden Turn ab und schützt den Draft. Ctrl+C ist „erst aufräumen, dann stoppen“ und eskaliert Richtung Quit, wenn du weiterdrückst.

Steal-Esc: Offene Menüs, Dropdowns, Selection und Modi (! Shell, # Remember, Feedback) fangen Esc zuerst ab – erwartbar, sobald du Overlays nutzt.

---

3.5 Session-Modes: Normal, Plan, Always-approve

Shift+Tab im fokussierten Prompt cyclt die Session-Modes: Normal → Plan → Always-approve → Normal. Auto ist nicht in diesem Zyklus – dafür /auto (Feature-abhängig).

Hebel	Mode / Wirkung
Shift+Tab	Mode cyclen (Normal / Plan / Always-approve)
Ctrl+O	Always-approve (YOLO) toggeln
/always-approve	Always-approve toggeln
/auto	Auto-Mode (Classifier; gefährliche Calls können weiter fragen) – Feature-abhängig
/plan	Plan Mode betreten (Kapitel 4)
/settings / F2	Settings-Modal

Terminal-Hinweis: Auf Apple Terminal kann Ctrl+O primär Interject/Send-now belegen (kein modified Enter) – dann YOLO über /always-approve oder /settings. Details: User-Guide Terminal Support.

Was die Modes bedeuten (Arbeitsdefinition):

Mode	Praxis
Normal (Permission oft ask)	Alltag: lesen oft frei, Schreiben/Shell oft mit Freigabe
Plan	Read-only Planung (außer Plan-Datei) – Ansatz freigeben, bevor Code fließt
Always-approve	Fast keine Permission-Prompts; Deny-Regeln und Hooks greifen weiter
Auto	Weniger Prompts durch Safety-Checks; blockierte Calls scheitern/eskalieren

Achtung: Always-approve ist kein „sicherer Turbo“. Es ist ein Turbo ohne Klick-Bremse. In der Lern- und Review-Phase aus; in CI nur mit Deny/Hooks und engem Scope (Kapitel 10, 13).

Plan + Always-approve: Plan Mode blockiert Repo-Edits; riskante Shell und andere Non-Edit-Tools können unter Always-approve trotzdem laufen – Details und Subagent-Gate in Kapitel 4.

Mikrogeschichte: Du cyclst versehentlich auf Always-approve, der Agent installiert eine Dependency und pusht einen Branch. Diff war „grün“ im Scrollback – Ownership war weg. Gegenmittel: Mode-Anzeige im UI bewusst lesen; nach Experimenten Shift+Tab zurück auf Normal.

Day-1-Cockpit bis hier: Anatomie, Fokus (Tab), Abbruch (Esc), Modes (Normal / Plan / Always-approve aus).

Day-1 – so weiter (nicht linear alles lesen): springe zu 3.7 (@ und !) → 3.8 (Slash-Kurzreferenz) → 3.11–3.12 (Sessions 1–2) → 3.13 (Parcours Pflichtteil). Abschnitte 3.6, 3.9–3.10 und die Vertiefungs-Unterabschnitte in 3.7 (History, Multiline, Queue) sowie Sessions 3–4 überspringen – bei Bedarf später nachschlagen.

---

3.6 Navigation und Fold im Scrollback

Referenz / Vertiefung – am Tag 1 optional (Day-1-Leser: weiter bei 3.7).

Simple Mode (Default): Pfeiltasten navigieren; Buchstaben fokussieren oft den Prompt und tippen.

Vim Mode (opt-in): /vim-mode oder [ui] vim_mode = true in config.toml. Dann j/k, h/l, g/G, y/Y usw. im Scrollback.

Aktion	Simple	Vim (Scrollback)
Nächster / vorheriger Eintrag	↓ / ↑	j / k
Nächster / vorheriger User-Turn	Shift+→ / Shift+←	L / H (Shift)
Eintrag einklappen / ausklappen	← / →	h / l
Alle Thinking toggeln	Ctrl+E	Ctrl+E
Block-Inhalt kopieren	(Vim: y)	y
Metadaten kopieren (z. B. Shell-Cmd)	(Vim: Y)	Y
Fullscreen-Viewer	Enter	Enter
Seite scrollen	PageUp / PageDown	gleich

PageUp/PageDown scrollen die Conversation oft auch bei Prompt-Fokus, ohne den Draft zu stehlen – praktisch beim Nachlesen während du den nächsten Prompt baust.

Warum Fold? Lange Shell-Logs und riesige Diffs füllen den Viewport. Collapsen hält den Faden; Expand nur für Review. In Vim-Mode ⇧E expandiert/collapst alles.

---

3.7 Prompt-Power: @, !, History, Multiline, Queue

Day-1: die beiden Unterabschnitte @ und !. History, Multiline und Queue sind Vertiefung.

Dateien mit @

# Day-1 mit todo-cli
@todo/store.py erkläre Speichern und Laden. Noch nichts ändern.
@todo/cli.py:1-40 was macht der Einstieg?

# später / eigenes Repo
@src/api/auth.ts prüfe die Fehlerbehandlung. Noch nichts ändern.
@!.github/workflows/ci.yml erkläre den Job test.

Fuzzy-Picker, .gitignore-aware. ! ohne Leerzeichen direkt nach @ für Dotfiles/versteckte Pfade (@!.env, @!.github) – Secrets nicht achtlos anhängen.

Shell-Mode mit !

Auf leerem Prompt ! tippen → Shell-Mode. Du führst Befehle selbst aus (nicht der Agent-Turn). Nützlich für git status, pytest, schnelle Checks, ohne den Agenten zu bitten.

Prompt-History (Vertiefung)

• Leerer Prompt: ↑ öffnet History mit dem letzten Prompt.
• /history für Fuzzy-Suche.
• Recalled !-Befehle landen wieder im Shell-Mode.

Multiline (Vertiefung)

Hebel	Wirkung
/multiline oder Ctrl+M (Prompt fokussiert)	Multiline toggeln
Multiline an: Enter	Neue Zeile
Multiline an: Shift+Enter / Alt+Enter	Senden

Wann Multiline? Lange Specs, Stacktraces, mehrere Constraints – ohne dass Enter den Turn zu früh startet.

Prompt-Queue (Vertiefung)

Während ein Turn läuft, kannst du Folge-Prompts queuen. Pane toggeln: Ctrl+; (Alternativen je Plattform: Ctrl+', unter lokalem macOS-VS-Code-Family oft Ctrl+4). Mid-turn leeres Enter kann den obersten Queue-Eintrag force-senden – bewusst einsetzen.

---

3.8 Slash-Commands: die tägliche Kurzreferenz

Vollständige Liste: User-Guide und Kapitel 18. Hier die Befehle, die den Alltag tragen:

Command	Zweck
/new (/clear)	Frische Session
/resume	Session-Picker
/compact [Hinweis]	Kontext komprimieren
/context	Token-/Kategorie-Breakdown
/session-info (/status, /info)	Session-Metadaten
/rewind	Zu früherem Turn zurück
/fork	Session ab hier verzweigen
/model (/m), /effort	Modell / Reasoning-Effort
/plan, /view-plan	Plan Mode (Kapitel 4)
/always-approve, /auto	Permission-Modes
/vim-mode, /minimal, /fullscreen	Bedien-/Render-Modi
/copy, /export	Antwort sichern
/doctor	Diagnose
/hooks, /plugins, /skills, /marketplace	Extensions-Modal
/quit (/exit)	Beenden

Skills mit user-invocable: true erscheinen ebenfalls im /-Menü – dann ist /mein-skill ein Workflow, kein Builtin (Kapitel 8).

Command Palette: Ctrl+P oder ? – wenn du den Slash-Namen vergessen hast.

---

3.9 Wichtige Agent-Shortcuts (eine Tabelle zum Üben)

Referenz – ausdrucken oder bookmarken; nicht auswendig vor dem ersten Plan Mode.

Key	Aktion
Ctrl+P / ?	Command Palette
Ctrl+M	kontextabhängig: Model-Picker (Prompt nicht fokussiert) oder Multiline (Prompt fokussiert)
Ctrl+O	Always-approve toggeln (Apple Terminal: oft Interject – dann /always-approve)
Ctrl+S	Session-Picker (Resume)
Ctrl+N	Neue Session (wo gebunden)
Shift+Tab	Mode cyclen Normal/Plan/Always-approve (Prompt fokussiert)
Ctrl+T	Todos-Pane
Ctrl+G	Tasks-Pane (Fullscreen-TUI); in Minimal-Mode oft External-Editor
Ctrl+B	Laufenden Foreground-Command in den Background
Ctrl+. / Ctrl+X	Keyboard-Shortcuts-Hilfe (Ctrl+X ist der robuste Fallback)
F2 / Ctrl+,	Settings

Terminal-Fallen: In tmux, VS-Code-integriertem Terminal oder ohne Kitty-Keyboard-Protocol greifen manche Chords nicht. Dann: /doctor, Shortcuts-Hilfe, und Ctrl+X statt Ctrl+..

---

3.10 Render-Modi: Fullscreen vs. Minimal

Referenz / optional. Am Tag 1 bleibst du im Fullscreen-Default.

Mode	Charakter
Fullscreen (Standard-TUI)	Alt-Screen, klassisches Agent-UI
Minimal	Experimenteller scrollback-nativer Modus

Umschalten: /minimal, /fullscreen (Alias /full), CLI --minimal / --fullscreen. Sticky-Verhalten über Default screen mode in Settings / [ui] screen_mode – CLI-Flags und Slash-Switch können session-scoped sein; Details im User-Guide Getting Started / Slash Commands.

Wann Minimal? Wenn du Scrollback-natives Lesen bevorzugst. Wann Fullscreen? Default-Lernpfad und die meisten Shortcuts-Beschreibungen in diesem Buch.

---

3.11 Session-Lifecycle im Alltag

grok                  # neue interaktive Session im CWD
grok -c               # continue last
grok --resume ID      # konkrete Session

In der TUI:

Ziel	Mittel
Neu	/new, oft Ctrl+N
Fortsetzen	/resume, Ctrl+S
Umbenennen	/rename / /title
Verzweigen	/fork
Zurückspulen	/rewind oder 2× Esc (leer)
Kontext retten	/compact keep die API-Entscheidungen
Kontext prüfen	/context, /session-info

Sessions liegen unter ~/.grok/sessions/ (Kapitel 12). Warum nicht alles in einer Session? Kontextfenster und Widersprüche. Frischer Kontext ist oft billiger als „bitte vergiss den alten Plan“.

---

3.12 Praxis-Sessions (2–4)

Day-1: Sessions 1–2. Sessions 3–4, sobald Abbruch und Modes sitzen.

Session 1 – Nur lesen, Tools beobachten

Mit todo-cli:

@todo/store.py erkläre Speichern und Laden in einfachen Worten. Ändere nichts.

Oder generisch:

Liste die Top-Level-Struktur und nenne die drei Dateien,
die ein neuer Entwickler zuerst lesen sollte. Ändere nichts.

Trainingsziel: Scrollback lesen, Tool-Calls collapsen, keine Freigabe für Writes. Optional @README.md anhängen.

Session 2 – Edit mit bewusster Freigabe

Ergänze in NOTES.md einen vierten Bullet „Nächster Lernschritt: Plan Mode“.
(Falls NOTES.md fehlt: mit genau diesem einen Bullet anlegen.)
Nur diese Datei. Danach git-diff-fähig halten.

Trainingsziel: Permission-Prompt lesen, Diff im Scrollback expandieren, manuell git diff (Prompt oder !).

Session 3 – Abbruch und Nachschärfen (Vertiefung)

Mit todo-cli absichtlich zu breit:

Refactore die gesamte todo-cli auf ein neues Persistenz-Framework.

Oder generisch:

Refactore das gesamte auth-Modul auf das neueste Pattern.

Sobald der Agent zu breit sucht oder den ersten riskanten Befehl vorschlägt: Esc. Dann:

Stop. Scope enger: nur store.py – erkläre atomare Writes in einem Absatz.
Kein Refactor, kein neues Framework.

Trainingsziel: Abbruch ohne Scham; Prompt heilen statt „weiterwursteln“.

Session 4 – Mode-Bewusstsein (Vertiefung)

1. Shift+Tab bis Plan Mode (oder /plan).
2. Auftrag (todo-cli): „Plane atomare Writes in store.save – noch kein Code.“
3. Plan lesen; nicht implementieren lassen, bis Kapitel 4.
4. Zurück auf Normal.
5. Ctrl+O kurz testen und sofort wieder aus – spüre den Unterschied in den Prompts.

Trainingsziel: Mode ist ein Harness-Hebel, kein Dekor.

---

3.13 Jetzt selbst machen: TUI-Parcours (20 Minuten)

Jetzt selbst machen

Day-1 (Pflicht, ~15 Min.):

1. grok in beispiele/todo-cli (oder eigenem Übungsrepo); /session-info und /context öffnen.
2. Session 1 (nur lesen) – einen Tool-Block collapsen und wieder expandieren.
3. Mit @ eine Datei anhängen und eine gezielte Frage stellen.
4. Session 2 (kleiner Edit) – Diff lesen, Freigabe bewusst geben.
5. Einen absichtlich schlechten Prompt senden und mit Esc abbrechen; nachschärfen.

Optional (Vertiefung):

6. /history oder ↑ nutzen, um einen alten Prompt zu recyclen.
7. Multiline an, Stacktrace einfügen, senden.
8. /doctor einmal ausführen und ein Finding notieren (auch wenn alles grün ist).
9. Optional: /vim-mode 5 Minuten, dann zurück.

---

3.14 Häufige Fehler

Symptom	Ursache	Fix
Tasten landen „nirgendwo“	Fokus im Scrollback / Overlay	Tab, Esc schließt Overlay
Esc bricht nicht ab	Fullscreen-Vim	Ctrl+C oder Vim aus
Versehentlich YOLO	Ctrl+O / Shift+Tab	Mode zurück; Diffs prüfen
Context „voll“ / Drift	Lange Session	/compact mit Hinweis oder /new
Shortcuts tot in tmux/VS Code	Terminal-Protokoll	/doctor, Ctrl+X, Guide Terminal
Agent ändert zu viel	Scope fehlt	Abbrechen, enger Prompt, Plan Mode

---

3.15 Checkliste TUI-Alltag

• Ich wechsle bewusst Prompt ↔ Scrollback (Tab)
• Ich kann einen Turn mit Esc/Ctrl+C zuverlässig stoppen
• Ich lese Diffs und Shell-Befehle vor dem Allow
• Ich kenne meinen aktuellen Mode (Normal / Plan / Always-approve)
• Ich nutze @ statt „lies irgendwas im Repo“
• Ich weiß, wann /compact vs. /new
• /doctor ist mein erster Schritt bei kaputter TUI

---

Was du jetzt kannst

• Scrollback und Prompt gezielt bedienen, abbrechen und rewinden
• Modes (Normal, Plan, Always-approve, Auto) und ihre Risiken einordnen
• Die Alltags-Slash-Commands und – bei Bedarf – die Shortcut-Referenz nutzen
• Mindestens zwei kurze Sessions fahren, die Review- und Scope-Muskeln trainieren

Nächste Schritte

→ Kapitel 04 – Plan Mode, Review und Freigabe: vor dem Code den Ansatz freigeben – und Diffs danach kontrolliert abnehmen. Stecken geblieben bei PATH/Login/TUI? Kapitel 2.12 und später 16.6.