Zum Inhalt springen

Claude Code in deiner eigenen Web-App · Teil 3 von 16 der Serie

Teil 3: Eine tmux-Sitzung für jede Site

Gib jeder Site eine eigene Sitzung von Claude Code: einen tmux-Server, der fürs Steuern eingerichtet ist, Sitzungen, die über deine Login-Shell im Ordner der Site starten, und einen Kopf, der zeigt, ob Claude Code läuft, arbeitet oder beendet ist.

Quest-Ziele

  • Einen tmux-Server einrichten, der Claude Code nicht in die Quere kommt
  • API-Keys und die Variablen anderer Claude-Code-Sitzungen aus den Sitzungen heraushalten
  • Claude Code in einer Login-Shell starten und seine Argumente unangetastet weitergeben
  • Allein an tmux ablesen, ob Claude Code läuft und ob es arbeitet
  • Sitzungen von der Seite aus starten, fortsetzen und beenden
  • Von deinem eigenen Terminal aus in eine Sitzung schauen und sie weiterlaufen lassen

In Teil 1 hast du Claude Code von Hand in einer tmux-Sitzung laufen lassen. Jetzt übernimmt das der Server: Jede Site bekommt eine Sitzung, die nach ihr benannt ist und in der Claude Code im Ordner der Site arbeitet. Der Kopf der Site zeigt den Zustand der Sitzung und hat die Buttons, um sie zu starten und zu beenden.

Die Sitzungen gehören tmux, nicht dem Server. Hältst du den Server an, arbeitet Claude Code weiter; startest du ihn wieder, findet er die Sitzungen, wo sie sind. Dadurch ist ein Neustart des Servers harmlos, und du wirst ihn in dieser Serie oft neu starten.

Ein tmux-Server, eine Sitzung für jede Site, und in jeder arbeitet Claude Code in seinem eigenen Ordner.
Ein tmux-Server, eine Sitzung für jede Site, und in jeder arbeitet Claude Code in seinem eigenen Ordner.

Ein tmux-Server zum Steuern

Sitesmith betreibt seinen eigenen tmux-Server, -L sitesmith, mit einer eigenen Konfiguration. Leg server/tmux.conf an:

server/tmux.conf
# The tmux server behind Sitesmith's sessions (tmux -L sitesmith): one session per site, each running
# Claude Code. tmux stays out of the way: no prefix key and no status bar, so every key reaches Claude
# Code and the page shows a plain terminal.
set -g prefix None
set -g status off
set -g escape-time 10
set -g history-limit 50000
set -g default-terminal tmux-256color
set -ga terminal-overrides ',xterm-256color:RGB'
set -g focus-events on
set -g window-size latest

# Sessions run on your Claude Code login, as in any terminal of yours. What the process that started
# this tmux server had in its environment would reach every session: an API key would bill per token
# instead of using your plan, and the variables of a Claude Code session around Sitesmith would make
# Claude Code think it runs inside another one.
set-environment -gu ANTHROPIC_API_KEY
set-environment -gu ANTHROPIC_AUTH_TOKEN
set-environment -gu ANTHROPIC_BASE_URL
set-environment -gu CLAUDECODE
set-environment -gu CLAUDE_CODE_ENTRYPOINT
set-environment -gu CLAUDE_CODE_SSE_PORT

Der erste Block hält tmux aus dem Weg:

  • prefix None: Normalerweise behält tmux Strg+b für sich, wie du in Teil 1 gesehen hast. In den Sitzungen von Sitesmith gehört jede Taste Claude Code. Der Preis: Strg+b und d lösen die Sitzung nicht mehr; weiter unten siehst du, wie du stattdessen herauskommst.

  • status off: keine Statusleiste am unteren Rand. Eine Sitzung zeigt Claude Code und sonst nichts, in deinem Terminal und ab Teil 4 auf der Seite.

  • escape-time 10: Nach einem Escape wartet tmux, ob noch Tasten folgen, denn mit Escape beginnen auch viele Tastenfolgen. Ältere tmux-Versionen warten standardmäßig 500 Millisekunden, lang genug, dass man es merkt; tmux 3.6, das hier lief, wartet schon von sich aus nur 10, und die Zeile sorgt dafür, dass jede Version es so hält. Mit Escape unterbrichst du Claude Code, und der Stop-Knopf aus Teil 5 schickt es; 10 Millisekunden reichen, um beides auseinanderzuhalten.

  • history-limit 50000: Zeilen zum Zurückscrollen pro Sitzung, statt 2.000. Ein langer Build scrollt viel.

  • default-terminal tmux-256color: der Terminaltyp, den Programme in der Sitzung in TERM sehen: tmux, mit 256 Farben.

  • terminal-overrides ',xterm-256color:RGB': sagt tmux, dass ein Terminal vom Typ xterm-256color draußen, was die meisten Terminal-Apps und das Terminal der Seite aus Teil 4 sind, 24-Bit-Farben darstellen kann. Die Farben von Claude Code kommen dann unverändert durch.

  • focus-events on: der Hinweis aus Teil 1. tmux gibt weiter, wenn ein Terminal den Fokus bekommt oder verliert.

  • window-size latest: Zeigen mehrere Terminals verschiedener Größe dieselbe Sitzung, dein eigenes und später das der Seite, nimmt die Sitzung die Größe des zuletzt benutzten an.

Im zweiten Block geht es um die Umgebung. Ein tmux-Server kopiert die Umgebung des Prozesses, der ihn startet, hier also des Servers von Sitesmith, und gibt sie an jede Sitzung weiter. set-environment -gu entfernt eine Variable wieder aus dieser globalen Umgebung (-g global, -u unset):

  • ANTHROPIC_API_KEY und ANTHROPIC_AUTH_TOKEN: Mit einem Key oder Token kann sich Claude Code damit anmelden statt mit deinem Login und jedes Token abrechnen. Die Sitzungen sollen über dein Abo laufen.

  • ANTHROPIC_BASE_URL würde die Anfragen von Claude Code an einen anderen Server schicken. Teil 15 setzt die Variable mit Absicht, für jeweils eine Site, um ein lokales Modell zu nutzen.

  • CLAUDECODE, CLAUDE_CODE_ENTRYPOINT und CLAUDE_CODE_SSE_PORT sind innerhalb einer Sitzung von Claude Code gesetzt. Startest du Sitesmith aus einer heraus, zum Beispiel indem du Claude Code npm start ausführen lässt, hielte sich jede Sitzung für einen Teil davon. In Teil 1 hat eine Sitzung auf diesem Weg sogar die Verbindung zum Editor übernommen.

tmux liest die Datei nur, wenn sein Server startet. Nach einer Änderung wendet tmux -L sitesmith source-file server/tmux.conf die Optionen auf den laufenden Server an; Änderungen an der Umgebung erreichen nur Sitzungen, die danach starten.

Die Sitzungen

Leg server/terminals.ts an. Die Datei beginnt mit ein paar Konstanten:

server/terminals.ts
import { execFile } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import type { ServerEvent, TerminalState } from '../shared/types.ts';

/** Sitesmith's own tmux server; SITESMITH_TMUX=<name> uses another one (tests next to a running Sitesmith). */
const SOCKET = process.env.SITESMITH_TMUX ?? 'sitesmith';
/** The program to run; SITESMITH_CLAUDE=<program> runs a stand-in or a wrapper instead. */
const CLAUDE = process.env.SITESMITH_CLAUDE ?? 'claude';
/** Claude Code runs inside your login shell (bash or zsh), so it finds what your terminal finds. */
const SHELL = /\/(bash|zsh)$/.test(process.env.SHELL ?? '') ? process.env.SHELL! : 'bash';
const SHELLS = ['bash', 'zsh', 'sh', 'fish'];
/** The screen changed in at least BUSY_TICKS of the last WINDOW seconds: Claude Code's spinner turns. */
const BUSY_TICKS = 3;
const WINDOW = 5;

export interface Target { name: string; dir: string }

/** tmux's target for a session's pane: `=` asks for this exact name, not one that starts with it. */
const pane = (name: string) => `=${name}:`;
  • SOCKET benennt den tmux-Server. SITESMITH_TMUX wählt einen anderen, damit eine zweite Kopie von Sitesmith, etwa für Tests, deine Sitzungen nie anfasst.

  • CLAUDE ist das Programm, das eine Sitzung ausführt: claude, oder was SITESMITH_CLAUDE sagt. Das kann ein Wrapper sein, der Claude Code mit einem günstigeren Modell startet, oder ein Platzhalter, ein kleines Skript, solange du an der Seite arbeitest und nichts gebaut werden muss.

  • SHELL ist deine Login-Shell, wenn sie bash oder zsh ist, sonst bash. SHELLS zählt die Namen auf, die „eine Shell ist im Vordergrund“ bedeuten; mehr dazu bei poll.

  • BUSY_TICKS und WINDOW gehören ebenfalls zu poll.

  • pane baut das Ziel von tmux für das Pane einer Sitzung. tmux nimmt einen Sitzungsnamen als Anfang, wenn keine Sitzung genau so heißt: -t maras würde maras-bakery finden. Das = verlangt genau diesen Namen, und der Doppelpunkt danach meint das aktuelle Fenster und Pane der Sitzung.

Dann die Klasse, mit der Art, wie sie mit tmux redet:

server/terminals.ts
/**
 * Claude Code in a tmux session per site. The sessions belong to tmux, not to this process: they
 * keep running when the server stops, and the server finds them again when it starts. Everything
 * it knows about them, it asks tmux.
 */
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 = '';
  available = false;

  constructor(app: string, emit: (ev: ServerEvent) => void) {
    this.conf = path.join(app, 'server', 'tmux.conf');
    this.emit = emit;
  }

  /** Checks that tmux is there, then follows the sessions once a second. */
  async init() {
    this.available = await this.tmux('-V').then(() => true, () => false);
    if (!this.available) return;
    await this.poll();
    setInterval(() => void this.poll(), 1000).unref();
  }

  /** Runs a tmux command against our own server (-L) with our config (-f, read when that server starts). */
  private tmux(...args: string[]) {
    return new Promise<string>((resolve, reject) => {
      execFile('tmux', ['-u', '-L', SOCKET, '-f', this.conf, ...args], { timeout: 5000 }, (err, out) => {
        if (err) reject(err); else resolve(out);
      });
    });
  }

  list() { return [...this.states.values()]; }

  get(name: string) { return this.states.get(name); }

Terminals behält nichts Eigenes außer dem letzten Bild, das tmux ihr geliefert hat. init fragt nach der Version von tmux: Ist tmux nicht installiert, bleibt available false, und die Seite sagt es. Sonst schaut die Klasse einmal pro Sekunde nach den Sitzungen. unref sorgt dafür, dass dieser Timer den Prozess nicht am Leben hält, wenn alles andere beendet ist.

Jeder Befehl an tmux geht durch tmux:

  • -u lässt tmux UTF-8 benutzen, egal was die Locale des Serverprozesses sagt. Claude Code zeichnet seinen Bildschirm mit ❯, ─ und Verwandten.

  • -L wählt den tmux-Server von Sitesmith, -f seine Konfiguration. tmux liest die Datei nur bei dem Aufruf, der den tmux-Server startet; bei jedem anderen ändert sie nichts.

  • execFile, nicht exec: Die Argumente gehen so an tmux, wie sie sind, ohne eine Shell dazwischen, die sie auslegen könnte.

  • Ein Timeout von fünf Sekunden, damit ein hängendes tmux nicht den Server hängen lässt.

Das Herz der Klasse verfolgt die Sitzungen:

server/terminals.ts
/**
 * The sessions, what runs in them and whether their screen moves. `pane_current_command` is the
 * program in front: a shell means Claude Code has exited. `window_activity` is the last second
 * anything was drawn; Claude Code's spinner draws all the time while it works.
 */
async poll() {
  // without sessions there is no tmux server, and tmux exits with an error
  const out = await this.tmux('list-panes', '-a', '-F', '#{session_name}\t#{pane_current_command}\t#{window_activity}').catch(() => '');
  const now = Math.floor(Date.now() / 1000);
  const states = new Map<string, TerminalState>();
  for (const line of out.split('\n')) {
    const [site, command, activity] = line.split('\t');
    if (!site) continue;
    const ticks = (this.ticks.get(site) ?? []).filter((t) => t > now - WINDOW);
    const last = Number(activity);
    if (last > now - WINDOW && !ticks.includes(last)) ticks.push(last);
    this.ticks.set(site, ticks);
    const claude = !SHELLS.includes(command);
    states.set(site, { site, claude, busy: claude && ticks.length >= BUSY_TICKS });
  }
  for (const site of this.ticks.keys()) if (!states.has(site)) this.ticks.delete(site);
  this.states = states;
  const sent = JSON.stringify(this.list());
  if (sent !== this.sent) {
    this.sent = sent;
    this.emit({ type: 'terminals', terminals: this.list() });
  }
}

Ein list-panes für alle Sitzungen, mit drei durch Tabs getrennten Werten: dem Namen der Sitzung und den beiden Werten, die du in Teil 1 kennengelernt hast.

Läuft Claude Code? pane_current_command nennt das Programm im Vordergrund. Beendet sich Claude Code, übernimmt die Shell aus dem Befehl weiter unten, und der Name lautet bash oder zsh. Die Prüfung fragt „ist eine Shell im Vordergrund?“ und nicht „ist claude im Vordergrund?“, weil das Programm ein Wrapper mit eigenem Namen sein kann.

Arbeitet es? window_activity ist die letzte Sekunde, in der irgendetwas gezeichnet wurde. Eine einzelne Änderung sagt wenig: Du hast etwas getippt, oder eine Zeile wurde neu gezeichnet. Während Claude Code arbeitet, zeichnet sich sein Spinner aber ständig neu. Also sammelt poll die verschiedenen Sekunden mit Aktivität innerhalb der letzten fünf (WINDOW) und hält eine Sitzung ab dreien davon (BUSY_TICKS) für beschäftigt. Das ist ein grobes Maß, aber es braucht nichts als tmux und hängt nicht davon ab, was der Bildschirm zeigt. Ab Teil 6 übernehmen Hooks den größten Teil dieser Aufgabe.

Ohne jede Sitzung gibt es gar keinen tmux-Server, und list-panes scheitert; das catch macht daraus eine leere Liste. Am Ende schickt poll die Liste nur an die Seite, wenn sie sich von der zuletzt geschickten unterscheidet. Sonst bekäme jede Seite einmal pro Sekunde dieselbe Nachricht.

Als Nächstes eine Frage, die die Seite stellen wird: Gibt es ein Gespräch, das sich fortsetzen lässt?

server/terminals.ts
/** Claude Code keeps each folder's conversations in ~/.claude/projects/<the path, with - for other characters>. */
hasConversation(dir: string) {
  try {
    const folder = path.join(os.homedir(), '.claude', 'projects', dir.replace(/[^a-zA-Z0-9]/g, '-'));
    return fs.readdirSync(folder).some((f) => f.endsWith('.jsonl'));
  } catch { return false; }
}

Claude Code bewahrt seine Gespräche in ~/.claude/projects auf, in einem Ordner pro Projektordner. Der Ordner heißt nach dem vollen Pfad, in dem jedes Zeichen, das kein Buchstabe und keine Ziffer ist, durch einen Bindestrich ersetzt wird: Aus /home/you/sitesmith/sites/maras-bakery wird -home-you-sitesmith-sites-maras-bakery. Jedes Gespräch ist eine .jsonl-Datei darin, und gibt es eine, ergibt „Continue last conversation“ Sinn.

Jetzt der Befehl, den eine Sitzung ausführt:

server/terminals.ts
/**
 * 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',
    ...(opts.resume ? ['--continue'] : []),
    ...(opts.prompt ? [opts.prompt] : [])];
}

Zusammengesetzt führt eine Sitzung etwa bash -lic '"$0" "$@"; exec "$SHELL" -i' claude --permission-mode acceptEdits aus. Stück für Stück:

  • -l und -i machen die Shell zu einer Login-Shell und zu einer interaktiven, sie liest also zuerst dein Profil und deine .bashrc oder .zshrc. Dort bekommt dein PATH ~/.local/bin, nvm oder Homebrew. Was dein Terminal findet, findet Claude Code auch: dasselbe claude, dasselbe node, dieselben Werkzeuge für die Befehle, die es ausführt.

  • "$0" "$@" ist das ganze Skript. Mit -c werden die Wörter nach dem Skript zu seinen Argumenten: $0 ist das Programm, $@ der Rest. Die Shell führt sie aus, wie sie sind, in Anführungszeichen, nie zerlegt und nie expandiert. Eine erste Nachricht mit Anführungszeichen, einem $ oder einem ; darin, ab Teil 5 Text, den du auf der Seite tippst, kann nicht zu einem Befehl werden.

  • exec "$SHELL" -i: Beendet sich Claude Code, tritt eine interaktive Shell an seine Stelle, im Ordner der Site. Die Sitzung bleibt offen, und die Seite kann Claude Code zurückholen.

  • --permission-mode acceptEdits: Claude Code ändert Dateien in seinem Ordner, ohne jedes Mal zu fragen. Befehle, die nur lesen, wie ls, laufen auch einfach; Befehle, die ins Netz gehen, wie curl, oder bestimmte Shell-Operatoren benutzen, fragen weiterhin. Teil 9 holt diese Fragen auf die Seite; bis dahin beantwortest du sie im Terminal.

  • --continue lädt das letzte Gespräch des Ordners, und ein prompt wird ab Teil 5 zur ersten Nachricht an Claude Code.

Zuletzt Starten, Neustarten und Beenden:

server/terminals.ts
  /** 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.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.command(opts));
    await this.poll();
  }

  /** Ends the session and whatever runs in it. */
  async end(t: Target) {
    await this.tmux('kill-session', '-t', `=${t.name}`).catch(() => undefined);
    await this.poll();
  }
}

start ist das new-session aus Teil 1: losgelöst, nach der Site benannt, 120 mal 36, im Ordner der Site gestartet (-c), mit dem Befehl. Als mehrere Argumente übergeben, führt tmux den Befehl direkt aus, ohne eigene Shell, die Login-Shell oben ist also die einzige beteiligte Shell, und sie bekommt die Argumente als $0 und $@. Kommen sich zwei Klicks in die Quere, scheitert das zweite new-session mit „duplicate session“, und das ist in Ordnung.

respawn ersetzt, was in der Sitzung läuft, durch einen frischen Befehl (-k beendet den alten zuerst): wieder Claude Code, anstelle der Shell, die es hinterlassen hat. end beendet die Sitzung, wieder mit dem = für den genauen Namen. Nach jedem davon läuft ein poll, damit die Seite sofort von der Änderung erfährt und nicht erst bis zu einer Sekunde später.

Routen

Die Seite muss wissen, ob es überhaupt Sitzungen geben kann und in welchem Zustand sie sind. Ersetz in shared/types.ts alles ab Config:

shared/types.ts
export interface Config {
  /** the preview server's port: the sites are shown from there, never from the page's own address */
  previewPort: number;
  /** whether tmux was found: without it there are no sessions */
  terminals: boolean;
}

/** A site's tmux session, as tmux reports it. */
export interface TerminalState {
  site: string;
  /** Claude Code runs in it (false: it exited, and a shell waits in the folder) */
  claude: boolean;
  /** its screen keeps changing: Claude Code is working */
  busy: boolean;
}

/** What the server tells every open page, over server-sent events. */
export type ServerEvent =
  | { type: 'sites'; sites: Site[] }
  | { type: 'files'; site: string }
  | { type: 'terminals'; terminals: TerminalState[] };

Config.terminals sagt, ob tmux gefunden wurde. Ein TerminalState beschreibt eine Sitzung: Läuft Claude Code darin, und arbeitet es? Ein neues Ereignis trägt die Liste davon.

Importier in server/main.ts die Klasse:

server/main.ts
import fs from 'node:fs';
import http from 'node:http';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import type { Config, NewSite, ServerEvent } from '../shared/types.ts';
import { HttpError, fileIn, readJson, send, sendFile } from './http.ts';
import { NAME, OWN, Sites } from './sites.ts';
import { Terminals } from './terminals.ts';

Die Konfiguration beginnt ohne Terminals:

server/main.ts
const sites = new Sites(path.resolve(option('--sites', path.join(APP, 'sites'))));
const config: Config = { previewPort: PREVIEW_PORT, terminals: false };

Unter der Ordnerüberwachung legst du die Terminals an und wartest auf den ersten Blick auf tmux:

server/main.ts
const terminals = new Terminals(APP, broadcast);
await terminals.init();
config.terminals = terminals.available;

/** A site's name and folder: what the terminals need, after checking the site exists. */
function target(name: string) {
  const site = sites.get(name);
  return { name: site.name, dir: sites.dir(site.name) };
}

Ein await auf oberster Ebene ist in einem ES-Modul erlaubt. Der Server lauscht erst nach dem ersten poll, also bekommt die erste Seite, die sich verbindet, den echten Zustand. target gibt den Namen und den Ordner einer Site heraus, aber nur für eine Site, die existiert: Sonst wirft sites.get eine 404. Nichts als ein geprüfter Site-Name erreicht je tmux.

Dann ersetz die Liste der Routen:

server/main.ts
const routes: Route[] = [
  ['GET', /^\/api\/config$/, (_req, res) => send(res, 200, config)],
  ['GET', /^\/api\/sites$/, (_req, res) => send(res, 200, sites.list())],
  ['POST', /^\/api\/sites$/, async (req, res) => {
    const site = sites.create(await readJson<NewSite>(req));
    broadcast({ type: 'sites', sites: sites.list() });
    send(res, 201, site);
  }],
  ['GET', /^\/api\/sites\/([^/]+)$/, (_req, res, m) => send(res, 200, sites.get(m[1]))],

  // a site's session: Claude Code in tmux
  ['GET', /^\/api\/sites\/([^/]+)\/session$/, (_req, res, m) => {
    send(res, 200, { conversation: terminals.hasConversation(target(m[1]).dir) });
  }],
  ['POST', /^\/api\/sites\/([^/]+)\/session\/start$/, async (req, res, m) => {
    if (!terminals.available) throw new HttpError(409, 'Sessions need tmux.');
    const t = target(m[1]);
    const { resume } = await readJson<{ resume: boolean }>(req);
    if (terminals.get(t.name)?.claude) throw new HttpError(409, 'Claude Code is already running for this site.');
    // a session whose Claude Code has exited gets it back in place of the shell
    if (terminals.get(t.name)) await terminals.respawn(t, { resume: resume === true });
    else await terminals.start(t, { resume: resume === true });
    send(res, 200, {});
  }],
  ['POST', /^\/api\/sites\/([^/]+)\/session\/end$/, async (_req, res, m) => {
    await terminals.end(target(m[1]));
    send(res, 200, {});
  }],

  // live updates: one long response per open page, an event per `data:` line
  ['GET', /^\/api\/events$/, (req, res) => {
    res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store' });
    res.write(`data: ${JSON.stringify({ type: 'sites', sites: sites.list() } satisfies ServerEvent)}\n\n`);
    res.write(`data: ${JSON.stringify({ type: 'terminals', terminals: terminals.list() } satisfies ServerEvent)}\n\n`);
    clients.add(res);
    // a comment now and then, so no proxy on the way closes a quiet connection
    const ping = setInterval(() => res.write(': ping\n\n'), 20000);
    req.on('close', () => { clearInterval(ping); clients.delete(res); });
  }],
];

Drei neue Routen. GET …/session sagt, ob der Ordner ein Gespräch hat. POST …/session/start antwortet ohne tmux mit 409, und ebenso, wenn Claude Code in der Sitzung der Site schon läuft: Ein zweiter Tab oder ein später zweiter Klick käme sonst beim Neustart an, und respawn-pane -k beendet, was im Pane läuft, mitten in seiner Arbeit. Sonst liest die Route resume aus dem Body und startet entweder eine neue Sitzung oder, wenn die Site eine hat, deren Claude Code beendet ist, startet sie neu. POST …/session/end beendet die Sitzung. Und der Event-Stream schickt die Sitzungen gleich nach den Sites, damit eine Seite, die sich verbindet, beides auf einmal kennt.

Der Kopf

Die Sitzung bekommt eine Zeile im Kopf der Site. Leg src/session.ts an:

src/session.ts
import { api } from './api.ts';
import { h } from './dom.ts';
import type { TerminalState } from '../shared/types.ts';

/** The state of a site's session in its header, and the buttons that start and end it. */
export class SessionControls {
  readonly el: HTMLElement;
  private url: string;
  private state: TerminalState | undefined;
  /** the session's state when the server was last asked about a conversation */
  private asked = '';
  private dot = h('span', { class: 'dot', 'aria-hidden': 'true' });
  private text = h('span');
  private start = h('button', { type: 'button', class: 'small primary' }, 'Start Claude Code');
  private resume = h('button', { type: 'button', class: 'small', hidden: true }, 'Continue last conversation');
  private end = h('button', { type: 'button', class: 'small ghost danger' }, 'End session');
  private msg = h('span', { class: 'hint bad', 'aria-live': 'polite' });

  constructor(site: string, available: boolean) {
    this.url = `/api/sites/${site}/session`;
    this.start.onclick = () => void this.call('start', { resume: false });
    this.resume.onclick = () => void this.call('start', { resume: true });
    this.end.onclick = () => {
      if (this.state?.claude && !confirm('End the session? Claude Code stops, also in the middle of its work.')) return;
      void this.call('end');
    };
    this.el = h('div', { class: 'head-acts' },
      h('span', { class: 'session-line' }, this.dot, this.text),
      ...(available ? [this.start, this.resume, this.end] : []),
      this.msg);
    if (!available) this.text.textContent = 'Sessions need tmux: install it and restart the server.';
    else this.update(undefined);
  }

  update(state: TerminalState | undefined) {
    this.state = state;
    this.dot.className = `dot${state?.busy ? ' busy' : state?.claude ? ' on' : ''}`;
    this.text.textContent = !state ? 'No session' : state.busy ? 'Claude Code is working' : state.claude ? 'Claude Code is open' : 'Claude Code has exited';
    this.start.hidden = Boolean(state?.claude);
    this.end.hidden = !state;
    // "Continue" only when the folder has a conversation to continue (asked when the session changes)
    const key = `${Boolean(state)}-${Boolean(state?.claude)}`;
    if (key === this.asked) return;
    this.asked = key;
    this.resume.hidden = true;
    if (!state?.claude) void api<{ conversation: boolean }>('GET', this.url).then((r) => { this.resume.hidden = !r.conversation || Boolean(this.state?.claude); }, () => undefined);
  }

  private async call(action: 'start' | 'end', body?: unknown) {
    this.msg.textContent = '';
    try { await api('POST', `${this.url}/${action}`, body); } catch (err) { this.msg.textContent = (err as Error).message; }
  }
}

Ein Punkt, eine Zeile Text, drei Buttons und ein Platz für einen Fehler. update bekommt den Zustand dieser Site oder nichts:

  • Keine Sitzung: ein grauer Punkt, „No session“ und Start Claude Code.

  • Claude Code läuft: ein grüner Punkt und „Claude Code is open“, oder, solange sich der Bildschirm bewegt, ein pulsierender Punkt und „Claude Code is working“.

  • Eine Shell ist im Vordergrund: „Claude Code has exited“ und wieder Start Claude Code, was der Server in einen Neustart der Sitzung umsetzt.

Continue last conversation erscheint nur, wenn Claude Code nicht läuft und der Ordner ein Gespräch hat. Ob es eins gibt, fragt die Steuerung den Server nur, wenn sich der Zustand der Sitzung ändert, nicht bei jedem Ereignis: asked merkt sich, in welchem Zustand sie zuletzt gefragt hat (gibt es eine Sitzung, läuft Claude Code darin), und eine Sitzung, die nur beschäftigt und wieder ruhig wird, zählt nicht. End session fragt nach, solange Claude Code läuft, denn das Beenden der Sitzung stoppt alles, was es gerade tut. Ohne tmux gibt es keine Buttons, nur eine Zeile, die sagt, was fehlt.

In src/sitePage.ts kommt die Steuerung in den Kopf, zwischen den Text und den Link. Der Anfang der Datei, bis zum Ende des Konstruktors:

src/sitePage.ts
import { h } from './dom.ts';
import { SessionControls } from './session.ts';
import type { Config, Site, TerminalState } from '../shared/types.ts';

/** One site: what it is about, and the site itself in a frame. */
export class SitePage {
  readonly el: HTMLElement;
  readonly name: string;
  private config: Config;
  private site: Site | null = null;
  private heading = h('h1', { class: 'site-heading' });
  private about = h('p', { class: 'site-about' });
  private frame = h('iframe', { class: 'preview-frame', title: 'The site', sandbox: 'allow-scripts allow-same-origin allow-forms allow-popups' });
  private empty = h('div', { class: 'preview-empty' }, h('p', {}, 'Nothing built yet.'));
  private session: SessionControls;

  constructor(name: string, config: Config) {
    this.name = name;
    this.config = config;
    this.session = new SessionControls(name, config.terminals);
    this.el = h('section', { class: 'site-page' },
      h('header', { class: 'site-head' },
        h('div', { class: 'site-head-text' }, this.heading, this.about),
        this.session.el,
        h('a', { class: 'button small', href: this.previewUrl, target: '_blank', rel: 'noopener' }, 'Open in a new tab')),
      h('div', { class: 'preview' }, this.frame, this.empty));
  }

Nach update kommt eine Methode, die der Steuerung den Zustand dieser Site gibt:

src/sitePage.ts
/** The sessions changed: this site's, or none. */
terminals(list: TerminalState[]) {
  this.session.update(list.find((t) => t.site === this.name));
}

src/main.ts hält die neueste Liste fest und gibt sie weiter: an eine Site, wenn sie sich öffnet, und an die geöffnete bei jedem Ereignis.

src/main.ts
import './style.css';
import { api, events } from './api.ts';
import { h } from './dom.ts';
import { newSiteForm } from './newSite.ts';
import { Sidebar } from './sidebar.ts';
import { SitePage } from './sitePage.ts';
import type { Config, ServerEvent, Site, TerminalState } from '../shared/types.ts';

/**
 * The page: the sites on the left, the open one on the right. Addresses: #new, #site/<name>.
 * Everything that changes comes from the server's events, whoever changed it.
 */
async function start() {
  const config = await api<Config>('GET', '/api/config');
  const sidebar = new Sidebar();
  const main = h('main', { class: 'main' });
  const offline = h('p', { class: 'offline', hidden: true }, 'The server is not answering. Waiting for it…');
  document.querySelector('#app')!.append(sidebar.el, main, offline);

  let sites: Site[] = [];
  let terminals: TerminalState[] = [];
  let page: SitePage | null = null;

  function route() {
    const hash = decodeURIComponent(location.hash.slice(1));
    const name = hash.startsWith('site/') ? hash.slice(5) : '';
    if (page && page.name === name) return;
    page?.dispose();
    page = null;
    if (hash === 'new') main.replaceChildren(newSiteForm((site) => { location.hash = `site/${site.name}`; }));
    else if (name) {
      page = new SitePage(name, config);
      page.update(sites);
      page.terminals(terminals);
      main.replaceChildren(page.el);
    } else {
      main.replaceChildren(h('div', { class: 'welcome' },
        h('h1', {}, 'Describe a site, Claude Code builds it.'),
        h('p', {}, 'Pick a site on the left, or start a new one.'),
        h('a', { class: 'button primary', href: '#new' }, 'New site')));
    }
    sidebar.render(sites, name);
  }

  function onEvent(ev: ServerEvent) {
    if (ev.type === 'sites') {
      sites = ev.sites;
      sidebar.render(sites, page?.name ?? '');
      page?.update(sites);
    } else if (ev.type === 'terminals') {
      terminals = ev.terminals;
      page?.terminals(terminals);
    } else if (ev.type === 'files' && ev.site === page?.name) page.filesChanged();
  }

  events(onEvent, () => { offline.hidden = false; }, () => { offline.hidden = true; });
  window.addEventListener('hashchange', route);
  route();
}

void start();

Probier es aus

Starte den Server neu, öffne eine Site und klick auf Start Claude Code. Innerhalb einer Sekunde ändert sich der Kopf:

Der Kopf einer Site mit ihrer Sitzung: „Claude Code is open“ mit dem grünen Punkt, daneben End session. Während Claude Code arbeitet, steht das in der Zeile.Den Screenshot in voller Größe öffnen
Der Kopf einer Site mit ihrer Sitzung: „Claude Code is open“ mit dem grünen Punkt, daneben End session. Während Claude Code arbeitet, steht das in der Zeile.

Hinter der Seite hat tmux eine neue Sitzung. Schau sie dir von einem Terminal aus an, mit den Befehlen aus Teil 1, jetzt auf -L sitesmith:

~/sitesmith
$ tmux -L sitesmith lsmaras-bakery: 1 windows (created Thu Nov 19 13:25:27 2026)$ tmux -L sitesmith list-panes -a -F '#{session_name} #{pane_current_command} #{window_activity}'maras-bakery claude 1795091127$ tmux -L sitesmith capture-pane -p -t =maras-bakery: Accessing workspace: ~/sitesmith/sites/maras-bakery Quick safety check: Is this a project you created or one you trust? (Like your own code, a well-known open source project, or work from your team). If not, take a moment to review what's in this folder first. Claude Code'll be able to read, edit, and execute files here. Security guide ❯ No, exit   Yes, I trust this folder Enter to confirm · Esc to cancel# what the page heard over its server events at that moment:data: {"type":"terminals","terminals":[{"site":"maras-bakery","claude":true,"busy":false}]}

Wieder der Vertrauensdialog. Claude Code hat diesen Ordner nie gesehen, also wartet es vor allem anderen auf eine Antwort. Die Seite meldet die Sitzung als offen und nicht beschäftigt, was stimmt, aber von dem Dialog weiß sie nichts: Kein Hook meldet ihn. Die Seite lernt in Teil 10, ihn zu beantworten. Bis dahin beantwortest du ihn vom Terminal aus, mit den Tasten aus Teil 1:

~/sitesmith
$ tmux -L sitesmith send-keys -t =maras-bakery: Down Enter

Jeder Ordner fragt einmal; danach merkt Claude Code sich die Antwort.

Vom eigenen Terminal aus hineinschauen

Oder geh in die Sitzung und beantworte ihn dort:

~/sitesmith
$ tmux -L sitesmith attach -t maras-bakery# no prefix key in these sessions: close the window to leave, or from another terminal:$ tmux -L sitesmith detach-client

Das ist Claude Code selbst, dieselbe Sitzung, die die Seite startet und beendet. Tipp darin wie in jedem Terminal. Weil der Prefix abgeschaltet ist, gehen Strg+b und d jetzt an Claude Code, nicht an tmux. Zum Verlassen schließt du das Terminalfenster oder den Tab: tmux löst dieses Terminal, und die Sitzung läuft weiter. Oder du führst detach-client in einem anderen Terminal aus. Solange du verbunden bist, hat die Sitzung wegen window-size latest die Größe deines Terminals.

Wenn sich Claude Code beendet

Tipp /exit in die Sitzung, oder lass Claude Code auf andere Weise enden. Die Sitzung bleibt:

~/sitesmith
# after /exit in Claude Code: the shell stays, pane_current_command says bash$ tmux -L sitesmith list-panes -a -F '#{session_name} #{pane_current_command}'maras-bakery bash# what GET /api/sites/maras-bakery/session answers now:{"conversation":false}# "Continue last conversation" anyway (sent with curl, resume: true); the pane then shows:No conversation found to continueyou@laptop:~/sitesmith/sites/maras-bakery$

Jetzt ist eine Shell im Vordergrund, der Kopf sagt also „Claude Code has exited“ und bietet an, es wieder zu starten. Ein Gespräch gibt es noch nicht: Claude Code legt erst eins an, wenn eine Nachricht geschickt wurde, und es wurde keine geschickt. Erzwungen zeigt --continue, warum die Seite den Button dann versteckt: Claude Code sagt, dass es nichts fortzusetzen gibt, und beendet sich, und die Shell übernimmt wieder.

Sitzungen überleben den Server

~/sitesmith
# stop the server with Ctrl+C, then:$ tmux -L sitesmith ls# the session is still listed; start the server again, and the page finds it$ npm run server

Strg+C ruft shutdown auf, das die Event-Streams und die beiden Server beendet, tmux aber in Ruhe lässt. Die Sitzungen laufen im eigenen Serverprozess von tmux weiter. Startet Sitesmith wieder, findet sie das erste poll, und die Seite, die sich von selbst neu verbunden hat, zeigt sie wie vorher.

Was du jetzt hast

Jede Site kann eine eigene Sitzung von Claude Code haben: in ihrem Ordner gestartet, über deine Login-Shell, über dein Abo, in einem tmux-Server, der sich heraushält und fremde Variablen draußen lässt. Die Seite weiß allein aus tmux, ob Claude Code läuft und ob es arbeitet, und die Sitzungen laufen weiter, was immer mit dem Server passiert.

Um zu sehen, was Claude Code tut, brauchst du aber noch ein eigenes Terminal. Im nächsten Teil kommt das Terminal auf die Seite: xterm.js im Browser, verbunden mit derselben Sitzung.

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.