Claude Code in deiner eigenen Web-App · Teil 6 von 16 der Serie
Teil 6: Hooks melden sich zurück
Gib jeder Sitzung eine Einstellungsdatei mit Hooks: Ein kleines Skript schickt jedes Ereignis an den Server, der die Werkzeuge verfolgt, die Claude Code benutzt, aus seinem Transkript liest, was es sagt, und das genaue Ende jeder Runde erfährt.
Claude Code in deiner eigenen Web-AppTeil 6 von 16
Auf dieser Seite
Quest-Ziele
- Eine Einstellungsdatei mit Hooks vom Server schreiben lassen und jeder Sitzung mit --settings mitgeben
- Dem Hook über die Umgebung der Sitzung und server.json sagen, für welche Site er meldet und wo der Server ist
- Einen Hook schreiben, der Claude Code nie in die Quere kommt
- Aus den Ereignissen der Hooks einen Verlauf dessen machen, was Claude Code tut, mit seinen eigenen Worten aus dem Transkript
- Einen Lauf mit dem Stop-Hook beenden und für Sitzungen ohne Hooks auf den Bildschirm zurückfallen
Seit dem letzten Teil kann Sitesmith Claude Code einen Auftrag übergeben. Was zurückkommt, ist dünn: Der Bildschirm bewegt sich, oder er tut es nicht. Die Seite kann nicht sagen, was Claude Code gerade tut, sie merkt ein paar Sekunden zu spät, dass die Arbeit begonnen hat, und kann nur raten, wann eine Runde vorbei ist.
Claude Code hat dafür einen eigenen Kanal. Hooks sind Befehle, die es in bestimmten Momenten von selbst ausführt: wenn eine Sitzung startet, wenn eine Eingabe kommt, vor jedem Werkzeug, am Ende einer Runde. Jeder bekommt eine Beschreibung des Moments als JSON. In diesem Teil bekommt jede Sitzung, die Sitesmith startet, Hooks, die diese Beschreibungen an den Server weitergeben, und das Panel unter dem Auftragsfeld wird zu einem Verlauf dessen, was Claude Code tut.
Vier Hooks
Die Referenz der Hooks listet viele Ereignisse auf. Sitesmith nutzt in diesem Teil vier davon:
SessionStart: Claude Code ist gestartet.sourcesagt, wie:startupfür ein neues Gespräch,resumefür ein fortgesetztes,clearodercompactnach diesen Befehlen.UserPromptSubmit: Eine Nachricht ist hineingegangen, ihr Text steht inprompt. Ab hier arbeitet Claude Code.PreToolUse: Claude Code ist dabei, ein Werkzeug zu benutzen.tool_nameundtool_inputsagen, welches und womit, zum BeispielEditmit einemfile_path.Stop: Die Runde ist vorbei. Seine Eingabe enthält auchlast_assistant_message, das, was Claude Code zuletzt gesagt hat; Teil 7 macht etwas daraus.
Jedes Ereignis bringt außerdem session_id, cwd und transcript_path mit, die Datei, in der Claude Code das Gespräch aufhebt. Ein Hook kann mehr als zuhören: Was er ausgibt und sein Exit-Code können Dinge erlauben oder verhindern, und darauf bauen die Teile 8 und 9. Hier melden die Hooks nur. Ein Hook, der mit Code 0 endet und nichts ausgibt, trifft gar keine Entscheidung.
Eine Einstellungsdatei, die der Server schreibt
Hooks stehen in den Einstellungen von Claude Code. Du könntest sie in deine eigene ~/.claude/settings.json schreiben, aber dann würde sich jedes Claude Code, das du startest, bei Sitesmith melden. Stattdessen schreibt der Server eine eigene Einstellungsdatei und gibt sie den Sitzungen, die er startet, mit --settings mit. Claude Code legt so eine Datei über deine eigenen Einstellungen: Deine Berechtigungen, deine Statuszeile und deine eigenen Hooks bleiben alle.
server/agent.ts wächst in diesem Teil kräftig. Fang oben an: Ersetze alles bis live hierdurch, das danach zwei kleine Helfer ergänzt:
import crypto from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';
import type { Activity, AgentState, Run, ServerEvent } from '../shared/types.ts';
import { OWN } from './sites.ts';
import type { Target, Terminals } from './terminals.ts';
/** Where a request's text goes, in the site's folder. */
export const REQUEST = `${OWN}/request.md`;
/** The one short line typed into Claude Code for every request. */
const COMMAND = `Do what ${REQUEST} says.`;
/** How many lines of activity the server keeps per site. */
const ACTIVITY = 40;
/** What a hook sends: Claude Code's hook input (the fields Sitesmith reads). */
export interface HookEvent {
hook_event_name: string;
transcript_path?: string;
source?: string;
prompt?: string;
tool_name?: string;
tool_input?: Record<string, unknown>;
tool_use_id?: string;
last_assistant_message?: string;
}
/** A run, with what only the server needs. */
interface Job extends Run {
target: Target;
/** when its line was typed in (or its session started) */
sentAt: number;
}
interface SiteAgent {
/** the current run, or the last one */
run: Job | null;
/** runs waiting until Claude Code is free */
queue: Job[];
/** a run is being started or typed in right now */
delivering: boolean;
/** whether its session reports through the hooks */
hooked: boolean;
/** between a prompt and the end of its turn, as the hooks report it */
hookBusy: boolean;
/** the conversation's transcript, and how far it has been read */
transcript: string | null;
transcriptPos: number;
activity: Activity[];
/** the state last sent to the pages */
sent: string;
}
const pub = (j: Job): Run => ({ id: j.id, title: j.title, status: j.status, queued: j.queued, started: j.started, ended: j.ended, error: j.error });
const live = (r: Run | null) => Boolean(r && (r.status === 'starting' || r.status === 'working'));
const short = (s: string, n = 140) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
const oneLine = (s: string) => s.replace(/\s+/g, ' ').trim();HookEvent zählt die Felder der Eingabe eines Hooks auf, die Sitesmith liest; die anderen kommen mit und werden ignoriert. Eine Site hebt jetzt auch auf, ob ihre Sitzung über Hooks meldet (hooked), ob die Hooks sagen, dass Claude Code arbeitet (hookBusy), das Transkript und wie weit es gelesen ist, und ihre activity: bis zu 40 Zeilen für den Verlauf. short() und oneLine() kürzen Text für diese Zeilen.
Als Nächstes eine Funktion, die aus einem Werkzeug eine Zeile macht, die ein Mensch lesen kann. Sie kommt vor die Klasse:
/** One line for the page about a tool Claude Code uses. */
export function describeTool(tool: string, input: Record<string, unknown> = {}) {
const file = path.basename(String(input.file_path ?? input.path ?? ''));
switch (tool) {
case 'Read': return /\.(png|jpe?g|webp|gif|svg)$/i.test(file) ? `Looking at ${file}` : `Reading ${file}`;
case 'Write': return `Writing ${file}`;
case 'Edit': case 'MultiEdit': return `Editing ${file}`;
case 'Bash': return input.description ? short(String(input.description)) : `Running ${short(oneLine(String(input.command ?? 'a command')), 90)}`;
case 'Glob': case 'Grep': return 'Searching the folder';
case 'WebSearch': return `Searching the web: ${short(String(input.query ?? ''), 90)}`;
case 'WebFetch': return 'Reading a web page';
case 'TodoWrite': return 'Updating its plan';
case 'Agent': case 'Task': return `Handing off: ${short(String(input.description ?? 'a task'), 90)}`;
case 'AskUserQuestion': return 'Asking you something';
}
return tool;
}Dateien erscheinen mit ihrem Namen, Befehle mit der Beschreibung, die Claude Code ihnen gibt, was es meistens tut („List project files and read CLAUDE.md“, „Syntax-check the script and list files“), und die Werkzeuge für Fragen und Helfer bekommen eigene Worte. Ein Bild, das Claude Code liest, heißt „Looking at“, denn genau das tut es damit. Ein Werkzeug ohne eigenen Fall, etwa ein MCP-Werkzeug, zeigt seinen Namen.
Jetzt die Klasse. Ihr Konstruktor schreibt die Einstellungsdatei:
/**
* Claude Code at work for the page. A request becomes a run: its text goes into a file in the
* site's folder, and as soon as Claude Code is free, one short line is typed into the site's
* session. What happens then, Claude Code's hooks report (server/hook.ts); sessions without the
* hooks are read from the screen.
*/
export class Agent {
/** the settings file with the hooks, passed to every session with --settings */
readonly settingsFile: string;
private terminals: Terminals;
private emit: (ev: ServerEvent) => void;
private sites = new Map<string, SiteAgent>();
constructor(app: string, data: string, terminals: Terminals, emit: (ev: ServerEvent) => void) {
this.terminals = terminals;
this.emit = emit;
// the hook script runs on the Node that runs this server; quoted for the shell Claude Code uses
const quote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
const command = `${quote(process.execPath)} --disable-warning=ExperimentalWarning ${quote(path.join(app, 'server', 'hook.ts'))}`;
const hook = [{ type: 'command', command }];
const settings = {
hooks: {
SessionStart: [{ hooks: hook }],
UserPromptSubmit: [{ hooks: hook }],
PreToolUse: [{ matcher: '*', hooks: hook }],
Stop: [{ hooks: hook }],
},
};
this.settingsFile = path.join(data, 'claude-hooks.json');
fs.mkdirSync(data, { recursive: true });
fs.writeFileSync(this.settingsFile, `${JSON.stringify(settings, null, 2)}\n`);
terminals.setHooks(this.settingsFile, data);
// once a second, and never twice at the same time: a check that waits for tmux takes a moment
const loop = async () => { await this.tick().catch(() => undefined); setTimeout(loop, 1000).unref(); };
void loop();
}Alle vier Ereignisse führen denselben Befehl aus. Die Einzelheiten:
Welches Node.
process.execPathist das Node, das den Server ausführt, und der Hook läuft auf genau diesem, egal wasnodein der Login-Shell der Sitzung bedeutet. Ein Versionsmanager oder ein andererPATHkann ihn nicht aus dem Tritt bringen. Node führt die TypeScript-Datei direkt aus, wie den Server, und--disable-warning=ExperimentalWarningverhindert Warnungen über Dinge, die Node noch experimentell nennt, damit der Hook gar nichts ausgibt.Für die Shell gequotet. Claude Code führt den Befehl eines Hooks über eine Shell aus, deshalb stehen beide Pfade in einfachen Anführungszeichen, und ein einfaches Anführungszeichen darin wird maskiert. Ein Ordner mit Leerzeichen im Namen bricht den Befehl nicht.
Jedes Werkzeug. Der Matcher
*lässtPreToolUsebei jedem Werkzeug feuern. Die anderen drei Ereignisse brauchen keinen Matcher.Die Datei kommt als
.data/claude-hooks.jsonin den Datenordner des Servers und wird bei jedem Start neu geschrieben, so zeigt sie immer dorthin, wo die App gerade liegt.
Dann gibt der Konstruktor die Datei und den Datenordner an die Terminals, die beides ab jetzt in jede Sitzung stecken, die sie starten.
Jede Sitzung bekommt sie
In server/terminals.ts bekommt die Klasse ein Feld für die Hooks:
export class Terminals {
private conf: string;
private emit: (ev: ServerEvent) => void;
private states = new Map<string, TerminalState>();
private ticks = new Map<string, number[]>();
private sent = '';
private pty: typeof import('node-pty') | null = null;
private attached = new Set<IPty>();
private hooks: { settings: string; data: string } | null = null;
available = false;Nach hasConversation() kommen ein Setter und die Umgebung der Sitzung, gefolgt von command(), start() und respawn(), die sie jetzt benutzen. Ersetze diese drei hierdurch:
/** The hooks' settings file and the data folder: sessions started from now on report through them. */
setHooks(settings: string, data: string) {
this.hooks = { settings, data };
}
/** The session's environment: which site its hooks report for, and where they find the server. */
private env(t: Target) {
return this.hooks ? ['-e', `SITESMITH_SITE=${t.name}`, '-e', `SITESMITH_DATA=${this.hooks.data}`] : [];
}
/**
* What the session runs: Claude Code in a login shell, and when it exits, an interactive shell in
* the folder, so the session stays open. The shell gets the program and its arguments as "$0"
* and "$@", so no argument is ever parsed by the shell.
*/
private command(opts: { prompt?: string; resume?: boolean }) {
return [SHELL, '-lic', '"$0" "$@"; exec "$SHELL" -i', CLAUDE,
// file edits in the site's folder go ahead; commands still ask
'--permission-mode', 'acceptEdits',
// the hooks, on top of your own settings
...(this.hooks ? ['--settings', this.hooks.settings] : []),
...(opts.resume ? ['--continue'] : []),
...(opts.prompt ? [opts.prompt] : [])];
}
/** Starts Claude Code in a site's session: fresh, or continuing the folder's last conversation. */
async start(t: Target, opts: { prompt?: string; resume?: boolean } = {}) {
if (this.states.has(t.name)) return;
await this.tmux('new-session', '-d', '-s', t.name, '-x', '120', '-y', '36', '-c', t.dir, ...this.env(t), ...this.command(opts))
.catch((err: Error) => { if (!/duplicate session/.test(err.message)) throw err; });
await this.poll();
}
/** Claude Code again, in place of the shell it left behind. */
async respawn(t: Target, opts: { prompt?: string; resume?: boolean } = {}) {
await this.tmux('respawn-pane', '-k', '-t', pane(t.name), '-c', t.dir, ...this.env(t), ...this.command(opts));
await this.poll();
}Eine Einstellungsdatei dient allen Sites, also muss der Hook von irgendwoher erfahren, für welche Site er meldet. Die Umgebung der Sitzung ist der richtige Ort: new-session -e NAME=Wert setzt eine Variable für genau diese Sitzung (das braucht tmux 3.2 oder neuer), und Claude Code und seine Hooks erben sie. SITESMITH_SITE ist der Name der Site, SITESMITH_DATA der Datenordner des Servers. respawn-pane nimmt dasselbe -e, für ein Claude Code, das an Stelle seiner Shell neu startet.
Ein Claude Code, das du von Hand in einem eigenen Terminal startest, hat weder die Variablen noch die Einstellungsdatei und meldet sich deshalb nicht, auch nicht im Ordner einer Site.
server.json: Wo die Hooks den Server finden
Der Hook braucht auch die Adresse des Servers. Den Port könnte man ebenfalls in die Umgebung legen, aber eine Sitzung überlebt den Server: Du stoppst Sitesmith vielleicht und startest es mit einem anderen --port neu, während die Sitzung von vorher mit ihrer alten Umgebung weiterläuft. Deshalb schreibt der Server in eine Datei, wo er lauscht, und der Hook liest diese Datei bei jedem Lauf. Ersetze in server/main.ts den Anfang der Datei bis zur Zeile mit DIST hierdurch. Das ergänzt die Option --data und importiert den Typ eines Hook-Ereignisses:
/**
* Sitesmith's server: the API, live updates over server-sent events, the built page (dist/), and a
* second server on a port of its own that shows the sites. It listens on this machine only.
*
* node server/main.ts [--port 5400] [--sites ./sites] [--data ./.data]
*/
import fs from 'node:fs';
import http from 'node:http';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { WebSocketServer } from 'ws';
import type { Config, NewSite, RequestBody, ServerEvent } from '../shared/types.ts';
import { Agent, type HookEvent } from './agent.ts';
import { HttpError, fileIn, readJson, send, sendFile } from './http.ts';
import { requestText, runTitle } from './requests.ts';
import { NAME, OWN, Sites } from './sites.ts';
import { Terminals, type Target } from './terminals.ts';
const APP = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
function option(name: string, fallback: string) {
const i = process.argv.indexOf(name);
return i > 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
}
const PORT = Number(option('--port', '5400'));
const PREVIEW_PORT = PORT + 2;
/** Vite's dev server (`npm run dev`), which forwards /api here */
const DEV_PORT = 5401;
const DIST = path.join(APP, 'dist');
/** the server's own files: the hooks' settings, and server.json, through which the hooks find it */
const DATA = path.resolve(option('--data', path.join(APP, '.data')));Der Agent bekommt den Ordner der App und den Datenordner:
const terminals = new Terminals(APP, broadcast);
await terminals.init();
config.terminals = terminals.available;
config.pty = terminals.canAttach;
const agent = new Agent(APP, DATA, terminals, broadcast);Und die Zeilen von server.listen bis zum Ende der Datei werden zu:
const SERVER_FILE = path.join(DATA, 'server.json');
server.listen(PORT, '127.0.0.1', () => {
// the hooks of the sessions find the server through this file
fs.writeFileSync(SERVER_FILE, `${JSON.stringify({ port: PORT, pid: process.pid })}\n`);
console.log(`Sitesmith: http://localhost:${PORT}/`);
});
preview.listen(PREVIEW_PORT, '127.0.0.1');
function shutdown() {
// the hooks then know at once that nobody listens
try { if (JSON.parse(fs.readFileSync(SERVER_FILE, 'utf8')).pid === process.pid) fs.rmSync(SERVER_FILE); } catch { /* gone */ }
terminals.shutdown();
for (const c of clients) c.end();
server.close();
preview.close();
setTimeout(() => process.exit(0), 300).unref();
}
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);Sobald der Server lauscht, schreibt er .data/server.json mit seinem Port und seiner Prozess-ID. Fährt er herunter, löscht er die Datei, damit die Hooks sofort wissen, dass niemand zuhört, statt darauf zu warten, dass eine Verbindung scheitert. Die Prozess-ID sorgt dafür, dass ein Server nur seine eigene Datei löscht: Hat seitdem ein anderes Sitesmith mit demselben Datenordner gestartet, gehört die Datei diesem. Der Ordner .data/ steht seit Teil 2 in der .gitignore.
Der Hook
Leg server/hook.ts an:
/**
* What Claude Code runs for its hooks, in the sessions Sitesmith starts: it reads the event from
* stdin and posts it to the server. The session's environment names the site (SITESMITH_SITE) and
* the server's data folder (SITESMITH_DATA), where server.json says on which port it listens.
*
* A hook must never get in Claude Code's way: whatever goes wrong (no server, a timeout, odd
* input), it ends quietly with exit code 0 and no output, and Claude Code carries on.
*/
import fs from 'node:fs';
import path from 'node:path';
const site = process.env.SITESMITH_SITE;
const data = process.env.SITESMITH_DATA;
async function stdin() {
let raw = '';
for await (const chunk of process.stdin) raw += chunk;
return raw;
}
function serverUrl() {
try {
const { port } = JSON.parse(fs.readFileSync(path.join(data!, 'server.json'), 'utf8')) as { port: number };
return `http://127.0.0.1:${port}`;
} catch { return null; }
}
async function main() {
const raw = await stdin();
if (!site || !data) return;
const base = serverUrl();
if (!base) return;
const event = JSON.parse(raw) as { hook_event_name: string };
await fetch(`${base}/api/hooks/event`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ site, event }),
signal: AbortSignal.timeout(2000),
});
}
await main().catch(() => undefined);
process.exit(0);Die Regel für dieses Skript steht in seinem Kommentar: Es darf Claude Code nie in die Quere kommen. Claude Code wartet auf einen Hook, bevor es weitermacht, und ein Hook, der scheitert, etwas ausgibt oder hängt, stört genau die Sitzung, die er beobachten soll. Also:
Es liest zuerst seine ganze Eingabe, bevor es irgendetwas entscheidet.
Ohne
SITESMITH_SITEläuft es in einer Sitzung, die Sitesmith nicht gestartet hat, und tut nichts. Ohneserver.jsonläuft der Server nicht, und es tut ebenfalls nichts.Das Senden darf höchstens zwei Sekunden dauern. Ein Befehls-Hook darf standardmäßig bis zu zehn Minuten laufen, und ein Server, der hängt, soll Claude Code keine davon aufhalten.
Jeder Fehler landet im
catch, und das Skript endet immer mit Code 0 und ohne Ausgabe: keine Entscheidung, und Claude Code macht weiter, als gäbe es keinen Hook.
Es schickt an 127.0.0.1, die Adresse, auf der der Server lauscht, damit nichts davon abhängt, wie localhost auf deinem Rechner aufgelöst wird.
Die Route
Der Hook schickt an eine neue Route. Füg sie in main.ts nach der Route für Stop in die Liste ein:
// Claude Code's hooks (server/hook.ts) report here
['POST', /^\/api\/hooks\/event$/, async (req, res) => {
const { site, event } = await readJson<{ site: string; event: HookEvent }>(req);
if (site && sites.read(String(site)) && event?.hook_event_name) agent.hookEvent(String(site), event);
send(res, 200, {});
}],Sie nimmt ein Ereignis nur für eine Site, die es gibt, und nur mit einem Namen des Ereignisses an, und sie antwortet in jedem Fall mit 200: Der Hook schaut sich die Antwort ohnehin nicht an. Wie jede Route steht sie hinter allowed(). Die Anfrage des Hooks kommt von diesem Rechner, an die eigene Adresse des Servers und ohne Origin, also kommt sie durch; eine Webseite in deinem Browser, die denselben POST schickte, würde an ihrer Origin scheitern.
Was der Server daraus macht
Zurück in agent.ts. Nach dem Konstruktor füllt site() die neuen Felder, und danach kommen busy() und state():
private site(name: string) {
let s = this.sites.get(name);
if (!s) {
s = { run: null, queue: [], delivering: false, hooked: false, hookBusy: false, transcript: null, transcriptPos: 0, activity: [], sent: '' };
this.sites.set(name, s);
}
return s;
}
/** Working: the hooks say so (between a prompt and the end of its turn), or the screen moves. */
private busy(name: string) {
const term = this.terminals.get(name);
return Boolean(term?.claude && (term.busy || this.site(name).hookBusy));
}
state(name: string): AgentState {
const s = this.site(name);
// a queued run is the one that matters: there is one only when the last one is over
const run = s.queue[0] ?? s.run;
return { site: name, run: run ? pub(run) : null, hooked: s.hooked, busy: this.busy(name), activity: s.activity };
}busy() verbindet beide Quellen: Claude Code arbeitet, wenn sich sein Bildschirm bewegt oder wenn die Hooks es sagen, und das tun sie vom Moment an, in dem eine Eingabe hineingeht, bis zum Stop-Hook, ohne die paar Sekunden Verzögerung des Bildschirms. state() reicht hooked, busy und die Aktivität an die Seite weiter.
Nach changed() kommt die Methode, die dem Verlauf eine Zeile hinzufügt:
/** A line of activity, in its place in time; a line that was just noted is not noted again. */
private note(name: string, a: Omit<Activity, 't'>, t = Date.now()) {
const s = this.site(name);
if (s.activity.slice(-6).some((b) => b.kind === a.kind && b.text === a.text)) return;
// the transcript is written a moment after the hooks fire: its lines go back to where they belong
let i = s.activity.length;
while (i > 0 && s.activity[i - 1].t > t) i--;
s.activity.splice(i, 0, { t, ...a });
if (s.activity.length > ACTIVITY) s.activity.splice(0, s.activity.length - ACTIVITY);
}Eine Zeile, die schon unter den letzten sechs steht, kommt nicht noch einmal dazu, drei Änderungen an index.html hintereinander erscheinen also als eine. Und eine Zeile kommt nicht einfach ans Ende, sondern an ihren Platz in der Zeit. Das ist wichtig für den Text aus dem Transkript, weiter unten.
run() vermerkt, woher ein Lauf kam:
/** Asks Claude Code for something. One run at a time per site. */
run(t: Target, title: string, request: string): Run {
const on = this.active(t.name);
if (on) throw new Error(`Claude Code is still on “${on.title}”. Wait until it is done, or stop it.`);
fs.mkdirSync(path.join(t.dir, OWN), { recursive: true });
fs.writeFileSync(path.join(t.dir, REQUEST), `${request.trim()}\n`);
const job: Job = { id: crypto.randomUUID(), title, status: 'queued', queued: Date.now(), target: t, sentAt: 0 };
this.site(t.name).queue.push(job);
this.note(t.name, { kind: 'note', text: `Asked from the page: ${title}` });
void this.deliver(t.name);
this.changed(t.name);
return pub(job);
}In deliverNext() fragt die Prüfung vor dem Tippen jetzt busy(). In eine Sitzung, deren Hooks sagen, dass sie arbeitet, wird also nichts getippt, auch wenn ihr Bildschirm gerade zufällig still steht:
private async deliverNext(name: string, s: SiteAgent) {
const job = s.queue[0];
if (!job) return;
await this.terminals.poll();
const term = this.terminals.get(name);
const resume = this.terminals.hasConversation(job.target.dir);
try {
if (!term) await this.terminals.start(job.target, { prompt: COMMAND, resume });
else if (!term.claude) await this.terminals.respawn(job.target, { prompt: COMMAND, resume });
else {
if (this.busy(name) || !(await this.terminals.atEmptyPrompt(job.target))) return;
// it may have been taken while we looked
if (s.queue[0] !== job) return;
await this.terminals.type(job.target, COMMAND);
}
} catch (err) {
s.queue.shift();
s.run = job;
this.end(name, 'failed', (err as Error).message);
return;
}
s.queue.shift();
s.run = job;
job.status = 'starting';
job.started = job.sentAt = Date.now();
this.changed(name);
}end() vermerkt einen Stopp oder einen Fehlschlag im Verlauf:
private end(name: string, status: 'done' | 'stopped' | 'failed', error?: string) {
const run = this.site(name).run;
if (!run || run.ended) return;
run.status = status;
run.ended = Date.now();
if (error) run.error = error;
if (status !== 'done') this.note(name, { kind: 'note', text: status === 'stopped' ? 'Stopped' : `Failed: ${error ?? ''}` });
this.changed(name);
}Nach stop() kommt der neue Teil der Datei, die Hooks:
/* ---------------------------------------------------------------- */
/* the hooks */
/* ---------------------------------------------------------------- */
/** A hook reported something. */
hookEvent(name: string, ev: HookEvent) {
const s = this.site(name);
s.hooked = true;
if (ev.transcript_path && ev.transcript_path !== s.transcript) {
s.transcript = ev.transcript_path;
// a continued conversation: only what comes from now on
try { s.transcriptPos = fs.statSync(ev.transcript_path).size; } catch { s.transcriptPos = 0; }
}
this.readTranscript(name);
const run = s.run;
switch (ev.hook_event_name) {
case 'SessionStart':
if (ev.source === 'startup') this.note(name, { kind: 'note', text: 'Claude Code started' });
else if (ev.source === 'resume') this.note(name, { kind: 'note', text: 'Claude Code continued its conversation' });
else if (ev.source === 'compact') this.note(name, { kind: 'note', text: 'Claude Code compacted its conversation' });
break;
case 'UserPromptSubmit': {
s.hookBusy = true;
if (live(run)) run!.status = 'working';
// something typed in the terminal, not by Sitesmith
if (!String(ev.prompt ?? '').includes(REQUEST)) this.note(name, { kind: 'prompt', text: `You: ${short(oneLine(String(ev.prompt ?? '')))}` });
break;
}
case 'PreToolUse':
s.hookBusy = true;
if (live(run)) run!.status = 'working';
this.note(name, { kind: 'tool', tool: ev.tool_name, text: describeTool(String(ev.tool_name), ev.tool_input) });
break;
case 'Stop':
// the end of its turn: exact, where the screen could only guess
s.hookBusy = false;
if (live(run)) this.end(name, 'done');
break;
}
this.changed(name);
}Jedes Ereignis markiert die Site als hooked: Ihre Sitzung meldet sich. Der Pfad des Transkripts kommt mit jedem Ereignis, und ist er neu, beginnt das Lesen an seinem aktuellen Ende, damit ein fortgesetztes Gespräch nicht alles noch einmal abspielt, was vorher gesagt wurde. Dann, je nach Ereignis:
SessionStartvermerkt, wie Claude Code gestartet ist.UserPromptSubmitundPreToolUsebedeuten Arbeit:hookBusygeht an, und ein Lauf, derstartingwar, ist jetztworking, in dem Moment, in dem es passiert. Eine Eingabe, die nicht die Zeile von Sitesmith ist, hat jemand im Terminal getippt, und der Verlauf zeigt sie als „You: …“.PreToolUsefügt außerdem eine Zeile über das Werkzeug hinzu, ausdescribeTool().Stopbeendet den Lauf als erledigt. Das ist genau: Der Bildschirm konnte nur raten, aus Stille und einem leeren Feld.
Was Claude Code zwischen seinen Werkzeugen sagt, etwa welchen Teil des Auftrags es als Nächstes angeht, steht in keinem dieser Ereignisse. Es steht im Transkript, einer Datei mit einem JSON-Objekt pro Zeile. Die nächste Methode liest die Zeilen, die seit dem letzten Mal neu sind:
/**
* What Claude Code says between its tools: the hooks don't carry it, its transcript does (a
* JSON line per message, assistant text in `message.content[].text`). Read from where we left.
*/
private readTranscript(name: string) {
const s = this.site(name);
if (!s.transcript) return;
let size = 0;
try { size = fs.statSync(s.transcript).size; } catch { return; }
if (size < s.transcriptPos) s.transcriptPos = 0;
if (size === s.transcriptPos) return;
// a big jump (an image, a long tool result) is read only from its last 2 MB
const from = Math.max(s.transcriptPos, size - 2 * 1024 ** 2);
const buf = Buffer.alloc(size - from);
const fd = fs.openSync(s.transcript, 'r');
try { fs.readSync(fd, buf, 0, buf.length, from); } finally { fs.closeSync(fd); }
const text = buf.toString('utf8');
// only whole lines; the rest is read next time
const end = text.lastIndexOf('\n');
if (end < 0) return;
s.transcriptPos = from + Buffer.byteLength(text.slice(0, end + 1));
for (const line of text.slice(0, end).split('\n')) {
if (!line.includes('"assistant"')) continue;
try {
const entry = JSON.parse(line) as { type?: string; timestamp?: string; message?: { content?: { type: string; text?: string }[] } };
if (entry.type !== 'assistant') continue;
const t = Date.parse(entry.timestamp ?? '') || Date.now();
for (const c of entry.message?.content ?? []) {
if (c.type === 'text' && c.text?.trim()) this.note(name, { kind: 'say', text: short(oneLine(c.text), 300) }, t);
}
} catch { /* a line cut at the 2 MB mark */ }
}
}Sie liest von dort, wo sie aufgehört hat, bis zum aktuellen Ende der Datei, und nur ganze Zeilen: Eine Zeile, die gerade noch geschrieben wird, kommt beim nächsten Mal dran. Ein sehr großer Sprung, wie ihn ein langes Ergebnis eines Werkzeugs oder ein Bild im Gespräch verursachen kann, wird nur ab seinen letzten 2 MB gelesen. Von jeder Zeile behält sie den Text des Assistenten, und jedes Stück bekommt seine eigene Zeit, aus dem timestamp der Zeile.
Dieser Zeitstempel hat ein echtes Problem gelöst. Claude Code schreibt sein Transkript einen Moment nachdem die Hooks feuern, also kam das, was es vor einem Werkzeug gesagt hatte, erst nach der Zeile dieses Werkzeugs an, und der Verlauf stand in der falschen Reihenfolge. Nach seiner eigenen Zeit eingeordnet, landet jede Zeile dort, wo sie hingehört.
Zuletzt die Uhr. check() überlässt das Ende eines Laufs jetzt in Sitzungen, die sich melden, dem Stop-Hook und in allen anderen dem Bildschirm:
/** Once a second: queued runs go out, and the state of the current one is checked. */
private async tick() {
for (const [name, s] of this.sites) {
try { await this.check(name, s); } catch { /* a hiccup of tmux: next second */ }
this.changed(name);
}
}
private async check(name: string, s: SiteAgent) {
if (s.queue.length) await this.deliver(name);
const run = s.run;
const term = this.terminals.get(name);
if (!term?.claude) s.hookBusy = false;
if (!run || !live(run)) return;
const since = Date.now() - run.sentAt;
if (!term) { if (since > 5000) this.end(name, 'failed', 'The session ended.'); return; }
if (!term.claude) { if (since > 8000) this.end(name, 'failed', 'Claude Code exited.'); return; }
// with the hooks, the Stop hook ends the run; without them, only the screen can tell
if (s.hooked) return;
if (term.busy) { run.status = 'working'; return; }
// quiet again, at an empty prompt: the turn is over. A turn too short to count as busy ends
// the same way, once it has had time to start.
if ((run.status === 'working' || since > 15000) && await this.terminals.atEmptyPrompt(run.target)) this.end(name, 'done');
}Ist Claude Code aus der Sitzung verschwunden, geht hookBusy aus, denn es kommt kein Stop-Hook mehr. Eine Sitzung, die sich meldet, bekommt ihr Ende nie vom Bildschirm. Eine, die sich nicht meldet, eine Sitzung von vor diesem Teil, endet weiter so, wie Teil 5 es gezeigt hat.
Der Verlauf in der Seite
Die Seite braucht die neuen Felder. Füg in shared/types.ts Activity vor AgentState ein und gib AgentState drei weitere Felder:
/** One line of what Claude Code did: a tool, something it said, a prompt, or a note. */
export interface Activity {
t: number;
kind: 'tool' | 'say' | 'prompt' | 'note';
text: string;
tool?: string;
}
/** What Claude Code does for a site, as far as the page needs to know. */
export interface AgentState {
site: string;
/** the current run, or the last one */
run: Run | null;
/** whether its session reports through the hooks (one you started yourself does not) */
hooked: boolean;
/** working, by the hooks or by the screen */
busy: boolean;
/** the last things it did, oldest first */
activity: Activity[];
}In src/agentPanel.ts bekommt das Panel eine Liste. Ersetze die Klasse von ihrem Kommentar bis zum Ende von update():
/**
* The current (or last) run: what it is, how long Claude Code has worked on it, what it does
* (its tools and what it says between them, from the hooks), and Stop.
*/
export class AgentPanel {
readonly el: HTMLElement;
private url: string;
private title = h('h2', { class: 'agent-title' });
private status = h('p', { class: 'agent-status' });
private stopBtn = h('button', { type: 'button', class: 'small ghost' }, 'Stop');
private feed = h('ol', { class: 'feed', 'aria-label': 'What Claude Code does', 'aria-live': 'polite' });
private msg = h('p', { class: 'hint bad', 'aria-live': 'polite' });
private timer = 0;
constructor(site: string) {
this.url = `/api/sites/${site}/stop`;
this.stopBtn.onclick = () => void this.stop();
this.el = h('section', { class: 'panel agent', 'aria-label': 'Claude Code', hidden: true },
h('header', { class: 'agent-head' }, h('div', {}, this.title, this.status), this.stopBtn),
this.feed, this.msg);
}
update(state: AgentState | undefined) {
const run = state?.run ?? null;
clearInterval(this.timer);
this.el.hidden = !run;
if (!run) return;
this.el.dataset.status = run.status;
this.title.textContent = run.title;
this.status.textContent = statusText(run, Date.now());
if (run.status === 'working') this.timer = window.setInterval(() => { this.status.textContent = statusText(run, Date.now()); }, 1000);
this.stopBtn.hidden = !isLive(run) || run.status === 'queued';
// what it did for this run, the last few lines
const mine = state!.activity.filter((a) => a.t >= run.queued - 1000).slice(-9);
this.feed.replaceChildren(...mine.map((a) => h('li', { class: a.kind }, a.text)));
this.feed.hidden = !mine.length;
}Der Verlauf zeigt die Zeilen des aktuellen Laufs: ab einer Sekunde, bevor er in die Schlange kam, die letzten neun. Jede Zeile bekommt ihre Art als Klasse, und das Stylesheet macht daraus ein Zeichen davor: einen Punkt für Vermerke, eine Pfeilspitze für Werkzeuge, Anführungszeichen für das, was Claude Code sagt, einen Pfeil für deine eigenen Eingaben.
Probier es aus
Starte den Server neu, beende die Sitzung einer Site, falls sie von vorher ist, und schick eine Änderung. Das hier hatte der Server während einer Änderung am Lumen Café an die Seiten geschickt, alle paar Sekunden nachgesehen:
# A change request to Lumen Café, in a session started with the hooks. Every few seconds, what the# server had sent the pages: the run's status, hooked, busy, and the newest lines of the feedcheck 1: working hooked=True busy=True | Asked from the page: Changing the site / Claude Code continued its conversationcheck 2: working hooked=True busy=True | Re-read the request file and list project files / Editing index.html / Editing style.csscheck 3: done hooked=True busy=False | Editing index.html / Editing style.css / The request now asks for opening hours in the visit section.# On the way, what Claude Code said between its tools first arrived after the tools it came# before: the transcript is written a moment after the hooks fire. A line of the transcript:{"type":"assistant","timestamp":"2026-11-19T12:36:22.025Z","message":{"content":[{"type":"text","text":"…"}]}}
Die Site hatte ein Gespräch, also startete ihre Sitzung mit --continue, und SessionStart meldete resume. Beim ersten Blick ist der Lauf schon working: UserPromptSubmit sagt es in dem Moment, in dem die Zeile hineingeht, wo der Bildschirm erst ein paar Sekunden Bewegung braucht. Die Werkzeuge erscheinen, während Claude Code sie benutzt, seine Worte aus dem Transkript landen dazwischen, und in dem Moment, in dem der Stop-Hook ankommt, ist der Lauf erledigt, ohne darauf zu warten, dass der Bildschirm zur Ruhe kommt. busy kann dem etwas hinterherhinken, weil es in diesem Teil auch noch auf den Bildschirm hört; Teil 7 zeigt, warum das zählt.
Die Seite weiß jetzt, was Claude Code tut, während es das tut, und wann eine Runde endet, auf die Sekunde. Das alles kommt von Claude Code selbst und bricht deshalb nicht, wenn sein Bildschirm nach einem Update anders aussieht. Eines, das der Stop-Hook mitbringt, ist noch ungenutzt: die letzte Nachricht von Claude Code. Im nächsten Teil wird sie zur Zusammenfassung jedes Laufs, und du kannst ihr aus der Seite heraus antworten.
Kommentare
Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.
Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.
