Agent Profiler: Ein Claude Code Profiler, der zeigt, wohin die Sitzungszeit geht

Agent Profiler ist ein Claude Code Profiler von YeonwooSung und Teil der Sammlung my-claude-code-mods. Er beantwortet eine Frage: Wenn sich eine Sitzung langsam anfühlt, wohin ist die Zeit gegangen? Er teilt die Zeit jedes Turns in Warten auf das Modell, Tool-Ausführung, blockierende Subagenten und Engine-Overhead und zeigt das Ergebnis an drei Stellen.

• Eine Statuszeile, die sich aktualisiert, während Claude arbeitet, zum Beispiel model 100% · tools 0% · ▶ model claude-haiku-5-5 12.5s.
• /profile, ein Textbericht über die ganze Sitzung, oder /profile turn für den letzten Turn. Er listet Zeitkategorien, Zeit bis zum ersten Token, Token-Zahlen, langsame Tools, wiederholt gelesene Dateien, Subagenten und eine kurze Liste von Befunden auf.
• /profile-pane, ein Live-Panel mit laufenden Anfragen und Tools. /profile-export schreibt die Sitzung als OTLP-JSON.

Die Mod ist vorsichtig mit ihren Aussagen. Sie meldet nie eine „Inferenzzeit“. Jeder Wert trägt eine Stufe: measured (von Claude Code geliefert, etwa die Tool-Dauer), observed (von der Mod an Ereignisgrenzen selbst gemessen), reported (Token-Verbrauch laut API) oder inferred (ein errechneter Rest). Die README des Autors verlangt Claude Code 2.1.287 oder neuer.

Die Aufnahme startet Claude Code mit geladener Mod im kleinen Demo-Projekt und bittet Claude, README.md zu lesen und das Projekt in einem Satz zu beschreiben. Während der Turn läuft, zählt die Statuszeile über der Fußzeile live mit: zuerst model 92% · tools 0%, dann model 100% mit der laufenden Anfrage ▶ model claude-haiku-5-5 und ihren vergangenen Sekunden. Nach dem Turn führt der Clip /profile aus. Der Bericht zeigt 29,0 s Wartezeit auf die Modellantwort, 5 ms Tool-Zeit, die Zeit bis zum ersten Token, 82,3k Eingabe-Tokens, den einen Read-Aufruf und den Befund, dass das Warten auf das Modell 100 % der Agentenzeit ausmachte.

Nutze eine der Methoden im Installationsblock; sie installieren direkt aus dem eigenen Marketplace des Autors. Dieser listet viele Plugins, wähle also agent-profiler. Statuszeile und Befehle erscheinen beim nächsten Sitzungsstart.

Das Modul hooks/register.tsx hält ein Profiler-Objekt im Speicher und füttert es an Ereignisgrenzen: turn.start und turn.complete, jeden Modellaufruf über turn.step, jedes Tool über tool.call sowie die eigene Tool-Dauer von Claude Code aus classic.PostToolUse. Der tool.call-Hook beobachtet nur. Er wartet mit await next(e) auf das Tool und gibt die Antwort unverändert zurück, aus hooks/register.tsx:

on('tool.call', async ($, e, next) => {
  anonymous += 1
  const id = e.tool_use_id ?? `anonymous-${anonymous}`
  const tool = String(e.tool)
  safe(() => profiler.toolStart(Date.now(), { id, tool, agentId: e.agentId, input: summarizeInput(tool, e as unknown as Record<string, unknown>) }))
  paint($)
  try {
    const answer = await next(e)
    safe(() => profiler.toolEnd(Date.now(), id, toolOutcome(answer)))
    return answer
  } // ...
}).catch(($, e, next) => next(e))

Jeder Protokollschritt läuft über safe(), sodass ein Fehler im Profiler verworfen wird, statt die Sitzung zu stören. Die Statuszeile wird höchstens zweimal pro Sekunde neu gezeichnet. Nach jedem Turn schreibt die Mod die neu abgeschlossenen Spans nach <outputDir>/<sessionId>/<loadId>-<seq>.otlp.json, am Sitzungsende den Rest samt Wurzel-Span der Sitzung. Die Span-Namen folgen den GenAI-Konventionen (chat <model>, execute_tool <tool>, invoke_agent <type>). Span- und Trace-IDs sind deterministisch, ein zweimal gesendeter Sitzungsverlauf ergibt also dieselben Spans. Der Speicher ist auf 20.000 Anfragen und Tool-Aufrufe begrenzt; darüber hinaus fallen die ältesten abgeschlossenen Turns weg.

Drei Optionen stehen im /plugin-Einstellungsmenü oder in pluginConfigs:

Um einen Trace in Jaeger anzusehen, starte examples/jaeger/docker-compose.yml aus dem Repo, setze otlpEndpoint auf http://localhost:4318 und öffne http://localhost:16686. Grafana Tempo nimmt denselben OTLP/HTTP-Endpunkt.

Wir haben vor dem Ausführen die Dateien gelesen, die das Plugin ausführen kann: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.tsx und die Jaeger-Compose-Datei vollständig. Von den elf Modulen in hooks/core/ haben wir export.ts, otlp.ts, redact.ts und die Eingabe-Zusammenfassung in profiler.ts vollständig gelesen und alle nach Netzwerk-, Prozess-, Datei-, eval-, import()- und Umgebungsaufrufen durchsucht (Treffer gibt es nur in register.tsx). Die Testdateien haben wir aufgelistet, nicht gelesen. Es gibt keine package.json, kein Installationsskript, keine Binärdatei, keinen gebündelten oder minifizierten Code, kein eval und kein dynamisches import(). Der Quelltext in hooks/ enthält keine Zeichen ohne Breite oder versteckten Zeichen; die einzigen Nicht-ASCII-Zeichen sind sichtbare Status- und Berichtssymbole wie █, ░, · und ⏱. Die Mod schleust keinen Text in Prompts oder Tool-Ergebnisse ein.

Auffälligkeiten:

• Schreibt standardmäßig Dateien. Sie ruft nach jedem Turn und am Sitzungsende $.fs.write auf, nach ~/.claude/agent-profiler/<sessionId>/, solange du outputDir nicht setzt. Das ist der eigene Ordner des Plugins, nicht settings.json oder eine Shell-Datei, aber er wird ohne Rückfrage beschrieben. Die Dateien enthalten Zeiten, Token-Zahlen, Modellnamen, Tool-Namen, Dateipfade von Read/Edit/Write und eine Kategorie pro Bash-Befehl (etwa test oder build). Dateipfade werden immer exportiert. Prompts, Bash-Befehle und Suchmuster nur mit exportCommandText.
• Netzwerk nur, wenn du zustimmst. $.http.fetch wird nur aufgerufen, wenn otlpEndpoint nicht leer ist, und schickt nur dasselbe Trace-JSON per POST an <endpoint>/v1/traces. Der Host ist, was du einträgst. Zeigst du auf einen entfernten Collector, verlassen Dateipfade und, mit exportCommandText, geschwärzte Befehle deinen Rechner. Die README warnt, dass die Schwärzung nur nach bestem Bemühen erfolgt.
• Liest eine Umgebungsvariable, HOME, um ~ in outputDir aufzulösen.
• Fängt Tool-Aufrufe ab, ohne sie zu ändern. tool.call und tool.check werden beobachtet und unverändert durchgereicht, beide mit .catch-Absicherung. Nichts wird abgelehnt oder umgeschrieben. claude plugin validate listet auch die classic.*-Hooks als Gating-Hooks ohne .catch; es sind Beobachter, die next(e) zurückgeben. Laut validate laufen die classic.*-Hooks nicht, wenn eine Organisation Claude Code verwaltet, dort kann der Bericht also unvollständig sein.
• Keine Prozesse, keine Daemons, keine Modellaufrufe. Sie führt keine Befehle aus und hält keinen Hintergrunddienst. Die einzigen Timer laufen innerhalb der Sitzung.
• Optionaler externer Dienst. Jaeger oder Tempo braucht man nur, um Traces anzusehen. Die Compose-Datei zieht jaegertracing/all-in-one:latest und wird von der Mod nie gestartet.
• Lizenz. Apache-2.0 (die LICENSE im Repo-Stammverzeichnis).

claude plugin validate meldete keine Fehler und keine Warnungen, nur die genannten Hinweise. Die 67 Tests des Autors in 11 Dateien liefen mit claude plugin test auf Claude Code 2.1.303 alle durch.

Geprüft mit Claude Code 2.1.303 unter macOS: validate, die Tests des Autors und die Demo-Aufnahme. Laut README lief der eigene End-to-End-Test des Autors auf 2.1.280, und die Ereignisformen folgen den Typdeklarationen von 2.1.292. Panel und Statuszeile werden im Terminal und im Code-Tab der Desktop-App gezeichnet, nicht aber im VS-Code-Chatpanel oder in claude -p; der Text von /profile funktioniert überall.

• Keine Statuszeile oder Befehle. Prüfe, dass claude --version 2.1.287 oder neuer ist, und führe nach der Installation in eine laufende Sitzung /reload-plugins aus.
• Keine Trace-Dateien. Es wird nichts geschrieben, bis die Sitzungs-ID bekannt ist. Ein fehlgeschlagener Schreibvorgang erscheint einmal als Toast; prüfe, ob outputDir beschreibbar ist.
• Zahlen starten nach Hot-Reload neu. Der Zustand im Speicher beginnt von vorn, bereits geschriebene Blöcke bleiben aber unter der alten Lade-ID auf der Platte.
• Über Bash geänderte Dateien. Die Erkennung wiederholter Lesezugriffe sieht sie nicht.
• Zeit im Modellserver (Warteschlange, Prefill, Decoding) lässt sich mit keinem clientseitigen Werkzeug aufteilen; die Zeit bis zum ersten Token fasst sie zusammen.