Rolle in der Werkstatt
Die Kontrollschicht der Werkstatt — sie bringt passenden Kontext in den Auftrag, setzt konkrete Grenzen und macht lokale Agentenarbeit nachvollziehbar.
— Kontrollschicht · lokale Arbeitsprobe
Local-onlySchicht: Observability
Wie ich Agenten vorbereite, begrenze und beobachte
Ein Agent braucht mehr als einen Auftrag. Prompt Prelude bringt vor dem Start passende Fähigkeiten in den Kontext, Hooks reagieren an festen Stellen und das Agent Observatory macht den späteren Ablauf sichtbar.
Drei Bausteine, drei Zeitpunkte: Prompt Prelude bereitet vor. Hooks ergänzen oder begrenzen während des Ablaufs. Das Observatory ordnet Ereignisse live und im Replay. Gemeinsam bilden sie eine Kontrollschicht für meine lokale Arbeit mit Claude Code.
Prompt PreludeClaude-Code-HooksAgent ObservatoryVorbereiten · Begrenzen · BeobachtenLokal · nachvollziehbar
Die Laufzeit bleibt lokal. Das Observatory läuft nur auf 127.0.0.1; private Prompts und Ablaufdaten werden nicht öffentlich übertragen. Die hier gezeigte Replay-Spur ist vollständig bereinigt.
Statischer Swimlane-Preview00:00 → 00:42
Main
Review
Fix
Balken = Tool-Call-Spans · Farbe = Agent (Main / Review / Fix) · Lücken = Denk-/Wartezeit
Zuletzt aktualisiert:
Jetzt prüfbar
- Architektur & Live-Swimlane-Demo — hier dokumentiert
- Code: lokales Repository (kein Remote) — Walkthrough auf Anfrage
— Rollen-Transfer
Was diese Route in der Werkstatt beweist.
Hier zeige ich, wie aus Vorbereitung, festen Eingriffspunkten und sichtbaren Abläufen eine zusammenhängende Kontrollschicht entsteht.
Transfer
Übertragbar sind gezielter Kontextabruf, ereignisgebundene Regeln, sichere Fehlerwege und Replay-Denken.
Öffentlicher Beleg
Sieben Architekturdiagramme, eine sanitisierte Replay-Demo, die Hook-Pipeline und offen benannte Systemgrenzen.
Grenze
Prompt Prelude blockiert nicht, das Observatory erzwingt keine Regeln und die sichtbare Laufzeit deckt lokale Claude-Code-Sessions ab.
01Ein Auftrag reicht nicht
Ein Auftrag reicht nicht
Das Problem
Ein Auftrag sagt dem Agenten noch nicht, welcher Kontext passt, welche Regeln gelten und wie sich der spätere Ablauf nachvollziehen lässt. Genau diese drei Fragen verbindet die Kontrollschicht.
vor der Arbeit
Prompt Prelude
vorbereiten
Erkennt den Themenbereich und bringt passende Fähigkeiten als kompakten Hinweis in den Auftrag ein.
während des Ablaufs
Hooks
begrenzen und ergänzen
Reagieren auf definierte Ereignisse und können Hinweise ergänzen, protokollieren oder eine Aktion stoppen.
währenddessen und danach
Agent Observatory
sichtbar machen
Ordnet lokale Claude-Code-Sessions, Subagenten und Werkzeugereignisse zu einem nachvollziehbaren Ablauf.
Diagramm
Vom vorbereiteten Auftrag über eine Hook-Prüfung bis zur sichtbaren Ablaufspur
02Vor der Arbeit
Vor der Arbeit
Prompt Prelude: vor der eigentlichen Arbeit
Prompt Prelude liest den Auftrag, erkennt Themenbereich und Arbeitsphase und fragt den Atlas nach passenden Fähigkeiten. Aus den Treffern entsteht ein kurzer Hinweis, mit dem Claude Code gezielter beginnen kann.
Diagramm
Prompt Prelude erkennt den Auftrag, fragt passende Fähigkeiten ab und übergibt einen kompakten Hinweis
Prompt Prelude blockiert selbst keine Aktion. Es bereitet den Auftrag vor; eine verbindliche Prüfung gehört an einen dafür vorgesehenen Hook.
03An festen Ereignispunkten
An festen Ereignispunkten
Hooks: an definierten Stellen reagieren
Hooks werden nicht irgendwann aktiv, sondern an benannten Punkten einer Session. Dadurch lässt sich eine Reaktion genau dort ausführen, wo zusätzlicher Kontext, eine Sicherheitsprüfung, ein Protokolleintrag oder eine Übergabe gebraucht wird.
Diagramm
Ereignispunkte einer Claude-Code-Session und die möglichen Reaktionen der Hooks
Vorbereitung
SessionStart und UserPromptSubmit können Kontext ergänzen, bevor die eigentliche Arbeit Fahrt aufnimmt.
Sicherheit
PreToolUse kann eine konkrete Aktion prüfen und sie bei einer klaren Regelverletzung stoppen.
Qualität
PostToolUse und Stop können Ergebnisse protokollieren oder eine abschließende Prüfung anstoßen.
Gedächtnis
PreCompact und SubagentStop helfen dabei, Übergaben und wichtige Zwischenergebnisse festzuhalten.
04Währenddessen und danach
Währenddessen und danach
Observatory: den Ablauf sehen
Das Agent Observatory ordnet lokale Claude-Code-Sessions, Subagenten und Werkzeugereignisse zu einer Zeitspur. So wird aus einzelnen Meldungen ein Ablauf, der live verfolgt und später als Replay geprüft werden kann.
Diagramm
Vom Nutzerauftrag über Hauptagent, Hooks und Subagenten bis zu Trace und Replay
Das Observatory setzt selbst keine Regeln durch. Es macht sichtbar, was geschehen ist; die verbindliche Reaktion liegt bei den Hooks.
05Regeln mit Rückmeldung
Regeln mit Rückmeldung
Warum Hooks und Observatory zusammengehören
Eine Regel ohne Rückmeldung bleibt unsichtbar. Eine Aktivitätsanzeige ohne Regeln setzt keine Grenze. Erst zusammen entsteht ein Weg, auf dem ein Ereignis erkannt, geprüft, beobachtet und anschließend verbessert werden kann.
Diagramm
Der geschlossene Kontrollweg von einem Ereignis bis zur verbesserten Regel
Diagramm
Die Kontrollschicht zwischen Gedächtnis, DCO und der geplanten Dual Bridge
06Ehrliche Abwägung
Ehrliche Abwägung
Stärken und Kosten
Die Kontrollschicht macht Agentenarbeit verlässlicher und verständlicher. Jede zusätzliche Kontrolle bringt aber auch Pflege, Fehlermöglichkeiten und eine klare Grenze ihres Geltungsbereichs mit.
Regeln greifen automatisch
Wiederkehrende Prüfungen hängen nicht davon ab, dass ich im richtigen Moment daran denke.
Preis: Jede automatische Regel braucht einen klaren Auslöser, eine enge Zuständigkeit und einen sicheren Fehlerweg.
Kontext kommt gezielt zum Agenten
Prompt Prelude kann passende Fähigkeiten vorschlagen, ohne das ganze Wissensarchiv in den Auftrag zu laden.
Preis: Die Suche kann einen wichtigen Treffer übersehen oder einen nur scheinbar passenden Hinweis zu hoch gewichten.
Agentenarbeit wird sichtbar
Sessions, Subagenten und Werkzeugaufrufe lassen sich als zeitlicher Ablauf prüfen.
Preis: Die aktuelle Beobachtung gilt für lokale Claude-Code-Sessions auf diesem Rechner, nicht für jeden Agenten im Stack.
Grenzen werden nachvollziehbar
Ein blockierter oder ergänzter Schritt ist an ein konkretes Ereignis und eine konkrete Regel gebunden.
Preis: Zu breite Hooks bremsen Arbeit aus; zu enge Hooks lassen relevante Fälle passieren.
Läufe bleiben als Replay prüfbar
Ein Fehler muss nicht allein aus Terminalfragmenten rekonstruiert werden.
Preis: Aufzeichnungen müssen gekürzt und vor einer Veröffentlichung konsequent bereinigt werden.
Diagramm
Der nächste Ausbau: Builder und Reviewer in einer beobachtbaren Dual Bridge
Der nächste größere Ausbau ist deshalb nicht noch eine weitere Anzeige, sondern die Dual Bridge: ein klarer Arbeitsweg zwischen Builder und Reviewer, der die vorhandenen Kontroll- und Beobachtungsflächen nutzt.
— Technische Vertiefung
Zum Nachprüfen
Die gemeinsame Geschichte erklärt die Rollen. Hier bleibt die vorhandene technische Vertiefung mit Replay, Ereignispipeline, Lane-Logik und ehrlichen Grenzen erhalten.
— Warum gebaut?
Agentenarbeit ist unsichtbar — bis man sie zum Kontrollraum macht.
Subagenten und Hook-Aktivität tauchen normalerweise nur verstreut in Terminal-Logs auf. Man sieht, dass etwas passiert — aber nicht als zusammenhängenden Strom, wer wann womit gearbeitet hat. Erfasst werden die ohnehin gefeuerten Hook-Typen: PreToolUse, PostToolUse, SubagentStop, UserPromptSubmit, Stop und SessionStart.
agent-observatory baut daraus einen einzigen lokalen Ereignisstrom: welche Session welches Tool nutzte, welche Subagenten parallel liefen, wann ein Aufruf begann und endete. Eine Lane je Session bzw. Subagent, und alles wird persistiert — für eine spätere Analyse oder einen Replay.
Ehrlich eingeordnet ist das Ganze bewusst klein und lokal gehalten. Es braucht keinen externen Dienst und kein Deployment — ein Diagnose- und Erzählwerkzeug, das Agentenarbeit aus der Black Box holt.
— Das visuelle Herzstück
Vier Spuren, ein Live-Strom von Tool-Events.
So sieht ein Lauf aus: oben die Hauptsession, darunter die Subagenten — auf jeder Spur laufen Tool-Chips zeitlich versetzt ein. Das ist eine echte, aufgezeichnete Session aus dem Tool selbst — jeder Pfad, jedes Kommando und jeder Prompt-Inhalt wurde vor der Veröffentlichung vollständig durch fiktive Platzhalter ersetzt.
— Die Pipeline
Von Hook-Event zu sichtbarer Spur — in einem geraden Lauf.
Die Pipeline ist bewusst klein und lokal gehalten. Ein Hook-Sender ohne externe Abhängigkeiten liest die Payload von stdin, kürzt sie, leitet die Lane ab und schickt sie per HTTP an einen FastAPI-Server; der normalisiert, schreibt nach SQLite und sendet live über WebSocket weiter. Das Dashboard läuft rein clientseitig, alles bleibt auf 127.0.0.1 — ohne externen Dienst und ohne Auth.
Ein gerader Lauf: der Hook liest die Payload von stdin, kürzt sie, leitet die Lane ab und schickt sie per HTTP an den Server — der normalisiert, persistiert und broadcastet live.
Replay aus SQLite: gespeicherte Läufe lassen sich über die Run-Endpunkte zurückspielen und in einem Scrubber durchscrubben — kein externer Dienst, kein Auth, nur Loopback.
— Die Kerneinsicht
Wie man Subagenten überhaupt auseinanderhält.
Der nicht offensichtliche Teil ist, dass alle Events eines Session-Baums dieselbe session_id teilen. Der einzige Diskriminator für einen Subagenten ist das Feld agent_id (beim Hauptagenten abwesend), agent_type liefert das lesbare Label. Der naive Default „eine Lane pro session_id“ hätte alle Subagenten in eine Spur kollabiert — das ist an echten Capture-Payloads empirisch verifiziert.
/01
Hauptagent → (session_id, None)
Der Hauptagent trägt kein agent_id-Feld. Genau diese Abwesenheit macht ihn erkennbar — er bekommt seine eigene Top-Lane.
/02
Subagent → (agent_type:agent_id, session_id)
Beim Subagenten ist agent_id der einzige Diskriminator, agent_type liefert das lesbare Label. Die geteilte session_id wird zum Parent.
/03
Eine Stelle, ein Ground-Truth
derive_lane ist die einzige Stelle für Lane-Anpassungen — kalibriert gegen die offizielle Hooks-Dokumentation, nicht gegen Vermutungen.
/04
Phase 0 empirisch abgeschlossen
Ein realer general-purpose-Subagent wurde gespawnt; agent_id und agent_type erschienen in PreToolUse UND SubagentStop. Der Capture-Hook fing nebenbei alle parallel laufenden Sessions ein.
— Beobachten ohne zu stören
Der Beobachter darf den Beobachteten nie ausbremsen.
Ein Beobachtungswerkzeug, das den überwachten Agenten blockieren oder zum Absturz bringen kann, ist schlimmer als gar keins. Der Hook-Sender ist deshalb durchgehend fail-soft ausgelegt: läuft der Server nicht, arbeitet Claude Code einfach weiter. Diese Entscheidungen sind die eigentliche Engineering-Substanz.
Fire-and-forget POST
Kein raise, kein stdout — bei jedem Fehler beendet der Sender mit exit 0. Der beobachtete Agent merkt nichts.
250 ms Timeout
Der Sender wartet nie lange auf den Server. Läuft der nicht, arbeitet Claude Code einfach weiter.
Payload-Truncation im Sender
Strings >500 Zeichen, Dicts >20 Keys und Listen >20 Items werden gekürzt — Schutz vor riesigen Payloads.
stdlib-only
Der Hook hat keine externen Dependencies und kann in jeder Claude-Umgebung laufen, ohne etwas zu installieren.
Test-DB-Isolation + Poison-Guard
conftest.py lenkt AGENT_OBS_DATA_DIR auf eine Temp-DB; ein Poison-Guard prüft nach jedem Test gegen die echte data/events.db.
— Ehrlicher Stand
Live — aber lokal, ohne offenen Code.
Das System läuft lokal auf 127.0.0.1:7171, mit grünen Tests und empirisch verifizierter Lane-Logik. Es ist bewusst Lab-Arbeit — rein lokal, ohne öffentliches Repository und ohne Live-URL. Was läuft, läuft echt; was offen ist, steht hier offen.
117
Tests grün — Hook-Sender, Ingest, DB, Hub, Stream, Lane-Logik, Poison-Guard
~150 ms
Latenz, bis ein neuer Tool-Call im Dashboard erscheint
250 ms
Hook-Timeout — fire-and-forget, exit 0 bei Fehler
200
Events im In-Memory-Ring-Buffer (Snapshot für neue Verbindungen)
7171
Port — gebunden ausschließlich an 127.0.0.1, kein Public-Zugang
Phase 0
empirisch abgeschlossen — derive_lane gegen echte Subagent-Payloads verifiziert
Stand 2026-07-14Quelle agent-observatory CHANGELOG + Projekt-Dossier
Offen / Lab
- Multi-Session-Parallel-Capture sauber trennen — der globale Hook fängt schon heute alle laufenden Sessions ein.
- Automatisierter Lane-Diskriminator und lesbarere Lane-Labels (last_assistant_message als Kandidat).
- Der Live-E2E-Smoke-Test ist bewusst zurückgestellt.
Kein Repo-Link, keine Live-URL. Anders als dual-bridge ist dieser Code nicht öffentlich. Ein Walkthrough ist auf Anfrage möglich.
— Die Schwester-Ansicht · separates lokales Repo
Was die Agenten über Zeit nutzen.
Das Replay oben zeigt den Live-Moment. Das unified-command-center — gleiche Farbsprache, ein Produktgedanke, aber ein eigenes Projekt — beantwortet die zweite Frage zum Nachvollziehen: was die Agenten über Wochen nutzen und kosten. Es fusioniert zwei Telemetrie-Quellen zu einer Mission-Control: die Kosten- und Token-Buchhaltung beider Agenten und jeden einzelnen Tool-Call aus dem Hook-Tracking.
Orbital-Core — die meistgenutzten Tools als Satelliten; Größe = Aufrufe, Farbe = Kategorie.
Cost Flight Recorder — der Tagesverlauf, gestapelt nach Agent (Cyan = Claude, Amber = Codex).
Activity & Workload — wann die Agenten arbeiten: Stunde × Wochentag als Heatmap, daneben die Projekt-Last.
unified-command-center
>110.000
Tool-Events bilanziert, über 43 aktive Tage (Stand: 14. Juli 2026)
unified-command-center
118
unterschiedliche Tools in der Telemetrie — vom Datei-Read bis zum MCP-Call
unified-command-center
98 %
Erfolgsrate über alle erfassten Tool-Spans
unified-command-center
76,7 Mrd.
Tokens bilanziert (inkl. Cache-Reads) — Claude und Codex zusammen
unified-command-center
2
Telemetrie-Quellen fusioniert: Kosten-/Token-Buchhaltung + Tool-Call-Tracking
unified-command-center
09:17
täglicher Auto-Refresh via Windows-Task — die Bilanz pflegt sich selbst
Stand Juli 2026Quelle unified-command-center TelemetrieScope echte Nutzungs-Aggregate, Screenshots synthetisch
Wie das Observatory: rein lokal, privates Repo. Die drei Screenshots zeigen durchweg Demo-Daten aus einem Generator; Kostenzahlen bleiben bewusst privat — öffentlich stehen hier nur Nutzungs-Aggregate. Walkthrough auf Anfrage.
— Nächste Iteration
Das Projekt lebt weiter.
- Replay-Bibliothek um weitere synthetische Läufe ergänzen
- Mobile-Rendering des Replays weiter verschlanken
— Walkthrough auf Anfrage
Ein Gang durch den Kontrollraum — auf Anfrage.
Die Hook-Pipeline, die Lane-Logik, der fail-soft Sender — wenn dich ein Mechanismus interessiert, schreib mir. Der Code ist lokal, ein Walkthrough ist jederzeit möglich.
Wo die Kontrollschicht im Gesamtbild der Werkstatt sitzt, zeigt die Systemkarte