Claude Code in deiner eigenen Web-App · Teil 4 von 16 der Serie
Teil 4: Das Terminal in der Seite
Hol die tmux-Sitzung jeder Site in die Seite: node-pty hängt sich auf dem Server an, ein WebSocket trägt die Bytes, und xterm.js zeichnet sie in einem Tab Terminal neben der Vorschau.
Claude Code in deiner eigenen Web-AppTeil 4 von 16
Auf dieser Seite
Quest-Ziele
- node-pty, ws und xterm.js installieren und node-pty am Compiler und an der Freigabe für Install-Skripte von npm vorbeibringen
- Die Maus in tmux scrollen und kopieren lassen, mit dem Kopierten über OSC 52 in der Zwischenablage
- Eine Seite mit tmux attach in einem Pseudo-Terminal an eine Sitzung hängen, ohne dass die Sitzung endet, wenn die Seite geht
- Fremde Websites von einem Socket fernhalten, der in eine Shell tippt
- Die Sitzung in einem Tab Terminal zeigen, der nur verbunden ist, solange du hinsiehst
Seit Teil 3 hat jede Site ihr eigenes Claude Code in einer tmux-Sitzung. Die Seite kann sie starten und beenden und zeigt, ob Claude Code arbeitet. Um die Sitzung selbst zu sehen, brauchst du aber noch ein eigenes Terminal und tmux -L sitesmith attach.
Dieser Teil holt die Sitzung in die Seite. Neben Preview bekommt jede Site einen Tab Terminal mit dem laufenden Bildschirm ihres Claude Code, und was du dort tippst, geht an Claude Code, als säßest du davor. Du wirst diesen Tab öfter brauchen, als du vielleicht denkst: In den nächsten Teilen ist er der einzige Ort, an dem du den Vertrauensdialog eines neuen Ordners oder eine Berechtigungsabfrage beantworten kannst, und später ist er der Ausweg für alles, was die Seite nicht beantworten kann.
Wie ein Bildschirm in eine Seite kommt
Ein Browser kann sich nicht an tmux hängen, aber er kann ein Terminal zeichnen: xterm.js ist der Terminal-Emulator in VS Code und läuft in jeder Seite. Er will einen Strom von Bytes, dieselben Bytes, die ein Programm in ein echtes Terminal schreibt, und er gibt die Tasten zurück, die du drückst.
Auf dem Server kommen diese Bytes von tmux attach, demselben Befehl, den du in deinem eigenen Terminal tippst. tmux hängt sich allerdings nur an ein echtes Terminal, deshalb startet der Server es in einem Pseudo-Terminal: einem Terminal ohne Bildschirm, das das Betriebssystem bereitstellt und dessen Ausgabe ein Programm lesen kann. node-pty öffnet eines aus Node heraus. Dazwischen trägt ein WebSocket die Bytes in beide Richtungen.
Jede Seite, die ein Terminal zeigt, ist also ein weiterer tmux-Client, genau wie dein eigenes Terminalfenster. Schließt sich die Seite, geht nur dieser Client. Die Sitzung und das Claude Code darin laufen weiter.
Drei Pakete und ein Compiler
Installiere den WebSocket-Server, xterm.js mit dem Addon, das ein Terminal in seine Box einpasst, die Typen für ws und node-pty:
$ npm install ws @xterm/xterm @xterm/addon-fitadded 3 packages in 1s$ npm install -D @types/wsadded 1 package in 275ms$ npm install --save-optional node-ptynpm warn install-scripts node-pty@1.1.0 (install: node scripts/prebuild.js || node-gyp rebuild; postinstall: node scripts/post-install.js)npm warn install-scriptsnpm warn install-scripts Run `npm install-scripts ls` to review, or `npm install-scripts approve <pkg>` to allow.# npm 11.20 ran the script anyway and built node-pty. Approve it, so that it runs on every npm:$ npm install-scripts approve node-pty --no-allow-scripts-pinApproved node-pty: added node-pty
node-pty ist ein natives Modul: Ein Teil davon ist C++, das für dein Node gebaut werden muss. Fertige Builds bringt es nur für macOS und Windows mit, unter Linux wird es also bei der Installation kompiliert. Dafür braucht es einen C++-Compiler, make und Python; unter Debian und Ubuntu bringt sudo apt install build-essential python3 alle drei.
Der Build läuft als Install-Skript, und neuere npm-Versionen sind bei solchen Skripten vorsichtig, aus gutem Grund: Ein Paket von irgendwo tief in deinen Abhängigkeiten könnte bei der Installation alles Mögliche auf deinem Rechner ausführen. npm nennt das Skript und bittet dich, es freizugeben. Mit dem npm, das hier lief (11.20), lief das Skript trotzdem, aber laut npms eigener Hilfe sind Install-Skripte von Abhängigkeiten standardmäßig blockiert. Gib es also ausdrücklich frei, dann ist es egal, was dein npm tut. Die Freigabe landet in der package.json, die jetzt so aussieht:
{
"name": "sitesmith",
"private": true,
"version": "1.0.0",
"description": "Describe a website, Claude Code builds it, the page shows it and asks you what Claude Code asks",
"type": "module",
"engines": {
"node": ">=24"
},
"scripts": {
"server": "node server/main.ts",
"dev": "vite",
"build": "vite build",
"start": "vite build && node server/main.ts",
"typecheck": "tsc --noEmit"
},
"devDependencies": {
"@types/node": "^24.10.1",
"@types/ws": "^8.18.2",
"typescript": "^7.0.2",
"vite": "^8.3.5"
},
"dependencies": {
"@xterm/addon-fit": "^0.11.0",
"@xterm/xterm": "^6.0.0",
"ws": "^8.23.0"
},
"optionalDependencies": {
"node-pty": "^1.1.0"
},
"allowScripts": {
"node-pty": true
}
}Der Eintrag unter allowScripts lautet "node-pty": true, gilt also für node-pty an sich und nicht für eine bestimmte Version. Das ist es, worum --no-allow-scripts-pin gebeten hat.
node-pty ist mit Absicht eine optionale Abhängigkeit. Lässt es sich nicht bauen, klappt npm install trotzdem, und Sitesmith läuft ohne das Terminal in der Seite: Alles andere funktioniert, und der Tab Terminal sagt, was fehlt. Eine kurze Probe, ob der native Teil lädt:
$ node -e "const p=require('node-pty'); const t=p.spawn('bash',['-c','echo hi from pty'],{}); t.onData(d=>process.stdout.write(d)); t.onExit(()=>process.exit(0))"hi from pty
Die Maus gehört tmux
In einem Terminalfenster gehören das Mausrad und das Markieren durch Ziehen dem Fenster selbst: Es hat einen eigenen Scrollback und eine eigene Auswahl. Hier liegt der Scrollback aber in tmux, das 50.000 Zeilen davon aufhebt (Teil 3), also soll tmux die Maus bekommen. Häng das hier ans Ende von server/tmux.conf:
# The wheel scrolls back, a drag copies (to the page's clipboard, through OSC 52), and any key goes
# back to the live screen
set -g mouse on
set -g set-clipboard on
unbind -a -T copy-mode
bind -T copy-mode Any send -X cancel
bind -T copy-mode WheelUpPane send -N 3 -X scroll-up
bind -T copy-mode WheelDownPane send -N 3 -X scroll-down
bind -T copy-mode MouseDown1Pane select-pane
bind -T copy-mode MouseDrag1Pane select-pane \; send -X begin-selection
bind -T copy-mode MouseDragEnd1Pane send -X copy-pipe-and-cancelmouse on: tmux übernimmt die Maus. Das Mausrad schaltet den Bereich in den Copy-Modus, den Scroll-Modus von tmux, und bewegt sich durch den Scrollback.set-clipboard on: Was du in tmux kopierst, geht auch in die Zwischenablage des Terminals, auf dem tmux zeichnet. Dafür schickt tmux eine Escape-Sequenz, OSC 52, die den kopierten Text in Base64 enthält. Dieses Terminal ist hier xterm.js, und die Seite gibt den Text an die Zwischenablage des Browsers weiter.unbind -a -T copy-modeentfernt alle Tasten des Copy-Modus, und die Zeilen danach belegen nur, was die Seite braucht: Jede Taste verlässt den Copy-Modus und kehrt zum laufenden Bildschirm zurück, das Mausrad scrollt drei Zeilen auf einmal, und Ziehen markiert und kopiert beim Loslassen.
Die Regel für jede Taste hat einen Haken, der im nächsten Teil wichtig wird: Im Copy-Modus holt eine Taste den Bereich nur zum laufenden Bildschirm zurück und geht nicht weiter. Ein Programm, das in eine Sitzung tippt, die jemand zurückgescrollt hat, verliert seinen ersten Buchstaben.
tmux liest die mit -f angegebene Datei nur, wenn sein Server startet, und der tmux-Server von Sitesmith läuft womöglich schon seit Teil 3, mit deinen Sitzungen darin. Deshalb sagt der Sitesmith-Server tmux ab jetzt bei jedem Start, dass es die Datei noch einmal lesen soll.
Anhängen vom Server aus
In server/terminals.ts kommen oben zwei Importe dazu. Beide holen nur Typen, die Datei lädt also auch dort, wo node-pty fehlt:
import { execFile } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import type { IPty } from 'node-pty';
import type { WebSocket } from 'ws';
import type { ServerEvent, TerminalState } from '../shared/types.ts';Ersetze den Anfang der Klasse bis zum Ende von init(). Die Klasse bekommt zwei Felder, für node-pty (falls es geladen wurde) und für die offenen Verbindungen, und init() lädt node-pty und lässt tmux die Konfiguration noch einmal lesen:
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>();
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, loads node-pty (optional: it compiles at install), and follows the
* sessions once a second. A tmux server that is already running reads the config again.
*/
async init() {
this.available = await this.tmux('-V').then(() => true, () => false);
if (!this.available) return;
this.pty = await import('node-pty').catch(() => null);
await this.tmux('source-file', this.conf).catch(() => undefined);
await this.poll();
setInterval(() => void this.poll(), 1000).unref();
}import('node-pty') ist ein dynamischer Import mit catch: Fehlt das Modul oder lädt sein nativer Teil nicht, bleibt pty null, und sonst geht nichts kaputt. Unter tmux() kommt ein Getter, den der Server an die Seite weitergibt:
/** Whether the page can show the sessions: that needs node-pty as well. */
get canAttach() { return this.available && this.pty !== null; }Und ans Ende der Klasse das Anhängen selbst und ein shutdown():
/**
* One page's view of a session: `tmux attach` in a pseudo-terminal, its output to the page, the
* page's keys and size to it. When the page goes, only this view ends: tmux detaches it, and the
* session runs on.
*/
attach(ws: WebSocket, t: Target, cols: number, rows: number) {
if (!this.pty || !this.states.has(t.name)) { ws.close(4404, 'no session'); return; }
// inside tmux itself (a server started in a tmux window), tmux would refuse to attach
const { TMUX: _nested, ...env } = process.env;
const term = this.pty.spawn('tmux', ['-u', '-L', SOCKET, '-f', this.conf, 'attach-session', '-t', `=${t.name}`],
{ name: 'xterm-256color', cols, rows, cwd: t.dir, env, encoding: null });
this.attached.add(term);
// bytes, not text: a character can be split between two chunks
term.onData((data) => { if (ws.readyState === ws.OPEN) ws.send(data); });
term.onExit(() => { this.attached.delete(term); ws.close(); });
ws.on('message', (raw) => {
try {
const m = JSON.parse(String(raw)) as { d?: string; cols?: number; rows?: number };
if (typeof m.d === 'string') term.write(m.d);
else if (m.cols && m.rows) term.resize(Math.min(500, m.cols), Math.min(200, m.rows));
} catch { /* not one of the page's messages, or the pty just ended */ }
});
ws.on('close', () => term.kill());
}
/** The server stops: the pages' views end, the sessions go on. */
shutdown() {
for (const term of this.attached) term.kill();
}attach() startet tmux attach-session für die Sitzung der Site in einem Pseudo-Terminal in der Größe, um die die Seite gebeten hat, mit denselben -L und -f wie jeder andere tmux-Befehl von Sitesmith. Was tmux zeichnet, geht über den WebSocket hinaus, und was hereinkommt, geht an tmux. Die Einzelheiten:
Kein
TMUX. Startest du den Server aus einem Fenster deines eigenen tmux, stehtTMUXin seiner Umgebung, und tmux weigert sich, sich aus tmux heraus anzuhängen. Das Anhängen bekommt die Umgebung des Servers ohne diese Variable.Bytes, kein Text. Mit
encoding: nullgibt node-pty rohe Bytes heraus. Der Bildschirm von Claude Code ist voller Zeichen, die in UTF-8 zwei oder drei Bytes brauchen, wie❯und─, und ein Stück Ausgabe kann mitten in einem davon enden. Stück für Stück dekodiert, würde aus so einem Zeichen Zeichensalat. xterm.js nimmt die Bytes und dekodiert sie als einen Strom.Zwei Arten von Nachrichten kommen von der Seite, beide kleines JSON:
{ d }mit Tasten zum Tippen und{ cols, rows }, wenn ihr Terminal die Größe geändert hat. Das Pseudo-Terminal übernimmt die neue Größe, tmux merkt es, und Claude Code zeichnet sich für die neue Breite neu. Alles andere wird ignoriert.Das Ende. Schließt sich der Socket der Seite, wird der attach-Prozess beendet. Für tmux geht damit ein Client, wie wenn du ein Terminalfenster schließt, und die Sitzung läuft weiter. Endet das Anhängen von selbst, weil die Sitzung beendet wurde, schließt sich der Socket.
shutdown()beendet alle Verbindungen, wenn der Server stoppt.
Jede Seite ist ein eigener Client, und dein eigenes Terminal kann gleichzeitig angehängt sein. Alle sehen denselben Bildschirm und tippen in dasselbe Claude Code. Das Fenster nimmt die Größe des Clients an, der zuletzt benutzt wurde (window-size latest aus Teil 3). Die anderen sehen es deshalb womöglich abgeschnitten oder mit leerem Rand, bis du sie benutzt.
Wer den Socket öffnen darf
Bisher sprechen Seite und Server über einfaches HTTP, bewacht von allowed() aus Teil 2. Auch ein WebSocket beginnt mit einer HTTP-Anfrage, einem Upgrade, aber Browser behandeln ihn in einem Punkt anders, und der zählt hier: Die Same-Origin-Regeln, die eine fremde Seite davon abhalten, die Antworten deiner API zu lesen, gelten für WebSockets nicht. Browser lassen seit Langem jede Website, die du besuchst, einen WebSocket zu localhost öffnen, ohne dich zu fragen. Neuere fangen an, vorher zu fragen (Chrome fragt inzwischen, bevor eine öffentliche Seite dein lokales Netz erreicht), aber darauf kann sich der Server nicht verlassen: Ein älterer Browser oder ein Klick auf Zulassen, und eine fremde Seite, die mit diesem Socket verbunden ist, könnte in eine Shell auf deinem Rechner tippen.
Was der Browser tut: Er schickt die Origin der Seite mit, und die kann eine Seite nicht ändern. Also prüft der Server sie. Füg in server/main.ts unter allowed() das hier ein:
/**
* A terminal socket types into a shell. Browsers have long let any web site open a WebSocket to
* localhost without asking (newer ones begin to ask first): only our own page may, by its exact origin.
*/
function allowedSocket(req: http.IncomingMessage) {
return HOSTS.has(req.headers.host ?? '') && ORIGINS.has(req.headers.origin ?? '');
}Anders als allowed() lässt sie keine Anfrage ohne Origin durch: Browser schicken bei einem WebSocket immer eine mit, und außer unserer Seite braucht niemand diesen Socket. Die Prüfung des Hosts ist die aus Teil 2: Sie hält einen fremden Namen auf, der plötzlich auf 127.0.0.1 zeigt (DNS-Rebinding).
Der Rest von main.ts. Die Importe bekommen den WebSocket-Server und den Typ Target dazu:
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, ServerEvent } from '../shared/types.ts';
import { HttpError, fileIn, readJson, send, sendFile } from './http.ts';
import { NAME, OWN, Sites } from './sites.ts';
import { Terminals, type Target } from './terminals.ts';Die Konfiguration, die die Seite lädt, bekommt ein Feld pty, das false ist, bis die Terminals eingerichtet sind:
const sites = new Sites(path.resolve(option('--sites', path.join(APP, 'sites'))));
const config: Config = { previewPort: PREVIEW_PORT, terminals: false, pty: false };Unter der Ordnerüberwachung, wo die Terminals eingerichtet werden, bekommt es seinen Wert:
const terminals = new Terminals(APP, broadcast);
await terminals.init();
config.terminals = terminals.available;
config.pty = terminals.canAttach;
/** A site's name and folder: what the terminals need, after checking the site exists. */
function target(name: string): Target {
const site = sites.get(name);
return { name: site.name, dir: sites.dir(site.name) };
}Der Typ Config in shared/types.ts lernt das neue Feld:
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;
/** whether node-pty was found: without it the page can't show the sessions */
pty: boolean;
}Nach dem API-Server und vor dem Vorschau-Server kommt der Handler für Upgrades:
/* ------------------------------------------------------------------ */
/* the terminals in the page */
/* ------------------------------------------------------------------ */
const sockets = new WebSocketServer({ noServer: true, maxPayload: 1024 ** 2 });
// /api/sites/<name>/session/socket?cols=..&rows=..: the session on a page's screen
server.on('upgrade', (req, socket, head) => {
const url = new URL(req.url ?? '/', 'http://localhost');
const m = url.pathname.match(/^\/api\/sites\/([^/]+)\/session\/socket$/);
let t: Target | null = null;
try { if (m && allowedSocket(req)) t = target(m[1]); } catch { /* no such site */ }
if (!t) { socket.destroy(); return; }
const size = (key: string, fallback: number) => Math.min(500, Math.max(10, Number(url.searchParams.get(key)) || fallback));
sockets.handleUpgrade(req, socket, head, (ws) => terminals.attach(ws, t, size('cols', 120), size('rows', 36)));
});Der WebSocket-Server hat keinen eigenen Port (noServer): Er übernimmt die Verbindungen, die ihm der HTTP-Server reicht. Der Handler prüft den Pfad, die Origin und die Site, und stimmt etwas nicht, zerstört er die Verbindung ohne Antwort, damit eine fremde Seite nichts erfährt; in den Tests der fertigen App sah so ein Client nur einen abgebrochenen Socket. Die Größe aus der Adresse wird zwischen 10 und 500 gehalten, und maxPayload begrenzt eine einzelne Nachricht auf 1 MB, reichlich für ein Einfügen. Fragt unsere eigene Seite nach einer Site ohne Sitzung, bekommt sie ihren Socket, und attach() schließt ihn sofort mit dem Code 4404.
Auch der Dev-Server von Vite reicht WebSockets weiter (ws: true in vite.config.ts seit Teil 2), und seine Origin auf Port 5401 steht in ORIGINS. Das Terminal funktioniert also auch mit npm run dev.
Zuletzt beendet shutdown() zuerst die Verbindungen:
function shutdown() {
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);xterm.js in der Seite
Leg src/terminalView.ts an. Sie beginnt mit zwei Helfern:
import type { FitAddon } from '@xterm/addon-fit';
import type { Terminal } from '@xterm/xterm';
import { h } from './dom.ts';
import type { TerminalState } from '../shared/types.ts';
/** xterm.js is big: it loads when the first terminal comes on screen. */
async function loadXterm() {
const [{ Terminal }, { FitAddon }] = await Promise.all([
import('@xterm/xterm'), import('@xterm/addon-fit'), import('@xterm/xterm/css/xterm.css'),
]);
return { Terminal, FitAddon };
}
/** OSC 52: tmux hands over what a drag selected, base64-encoded, for the clipboard. */
function copyToClipboard(data: string) {
const bytes = Uint8Array.from(atob(data.slice(data.indexOf(';') + 1)), (c) => c.charCodeAt(0));
// the clipboard needs a secure page (https, or localhost): elsewhere there is none
void navigator.clipboard?.writeText(new TextDecoder().decode(bytes)).catch(() => undefined);
return true;
}xterm.js ist mit Abstand das Größte in der Seite, und viele Besuche öffnen nie ein Terminal. Mit einem dynamischen import() legt Vite es in eigene Dateien, die der Browser erst lädt, wenn zum ersten Mal ein Terminal auf den Bildschirm kommt. copyToClipboard ist das andere Ende von set-clipboard in tmux: Der kopierte Text kommt in Base64 an, hinter einem kurzen Präfix, das mit einem Semikolon endet, und geht in die Zwischenablage des Browsers. Der Umweg über Bytes und einen TextDecoder ist nötig, weil atob ein Zeichen pro Byte liefert, was alles verstümmeln würde, was kein reines ASCII ist. Eine Zwischenablage hat eine Seite nur in einem sicheren Kontext, unter https oder auf localhost. Über einfaches http von einem anderen Gerät aus geöffnet, wie von deinem Handy in Teil 16, fehlt navigator.clipboard, und das ?. lässt das Kopieren aus, statt einen Fehler zu werfen.
Dann die Klasse:
/**
* A site's session in the page: xterm.js on a WebSocket to the server, which attaches to the tmux
* session for as long as the socket lives. It is attached only while it is on screen.
*/
export class TerminalView {
readonly el: HTMLElement;
private url: string;
private state: TerminalState | undefined;
private shown = false;
/** whether the server can attach a page to a session (it has node-pty) */
private available: boolean;
private term: Terminal | null = null;
private fit: FitAddon | null = null;
private ws: WebSocket | null = null;
private opening = false;
private retry = 0;
private screen = h('div', { class: 'term-screen' });
private empty: HTMLElement;
constructor(site: string, available: boolean) {
this.url = `/api/sites/${site}/session/socket`;
this.available = available;
this.empty = h('div', { class: 'term-empty' },
h('h2', {}, available ? 'No session' : 'The terminal needs node-pty'),
h('p', {}, available
? 'Start Claude Code above. The session keeps running when you close this page or stop the server.'
: 'npm install builds it (it needs a C++ compiler on Linux). Restart the server afterwards.'));
this.el = h('div', { class: 'term' }, this.screen, this.empty);
}
/** The terminal tab came on screen, or left it. */
setShown(shown: boolean) {
this.shown = shown;
this.sync();
if (shown) requestAnimationFrame(() => { this.fit?.fit(); this.term?.focus(); });
}
update(state: TerminalState | undefined) {
this.state = state;
// without node-pty there is nothing to attach to: the box says what is missing
const live = Boolean(state) && this.available;
this.screen.hidden = !live;
this.empty.hidden = live;
this.sync();
}
/** The page shows another site: this view is gone for good. */
dispose() {
this.shown = false;
this.sync();
this.term?.dispose();
}
/** Attached exactly while there is a session and it is on screen. A lost connection comes back. */
private sync() {
const wanted = this.shown && Boolean(this.state) && this.available;
clearTimeout(this.retry);
if (wanted && !this.ws && !this.opening) void this.open();
if (!wanted && this.ws) {
const ws = this.ws;
this.ws = null;
ws.close();
}
}Die Ansicht ist genau dann angehängt, wenn sie auf dem Bildschirm ist und es eine Sitzung gibt (und der Server node-pty hat), und sync() setzt das durch, sobald sich eins davon ändert. Wechselst du zum Tab Preview, schließt sich der Socket, und diese Seite löst sich von tmux; wechselst du zurück, hängt sie sich wieder an. Gibt es keine Sitzung, sagt die Box, wie du eine startest; auf einem Server ohne node-pty sagt sie, was fehlt, mit oder ohne Sitzung, und die Seite öffnet nie einen Socket, den sie nicht nutzen kann.
private async open() {
this.opening = true;
const term = this.term ?? await this.create();
this.opening = false;
if (!this.shown || !this.state || this.ws) return;
// tmux draws the whole screen when it attaches: start from an empty one
term.reset();
this.fit?.fit();
const proto = location.protocol === 'https:' ? 'wss' : 'ws';
const ws = new WebSocket(`${proto}://${location.host}${this.url}?cols=${term.cols}&rows=${term.rows}`);
ws.binaryType = 'arraybuffer';
// the window may have changed size while connecting
ws.onopen = () => ws.send(JSON.stringify({ cols: term.cols, rows: term.rows }));
ws.onmessage = (e) => term.write(new Uint8Array(e.data as ArrayBuffer));
ws.onclose = () => {
if (this.ws !== ws) return;
this.ws = null;
this.retry = window.setTimeout(() => this.sync(), 1000);
};
this.ws = ws;
term.focus();
}Wenn tmux sich anhängt, zeichnet es den ganzen Bildschirm neu. Deshalb leert open() das Terminal zuerst, passt es in seine Box ein und schreibt diese Größe in die Adresse. Sobald der Socket offen ist, schickt es die Größe noch einmal, falls sich das Fenster inzwischen geändert hat. Der Socket liefert ArrayBuffers, die als Bytes an xterm.js gehen, wie auf dem Server. Bricht die Verbindung ab, während die Ansicht angehängt sein sollte, etwa weil der Server neu gestartet ist, versucht sie es eine Sekunde später noch einmal.
private async create() {
const { Terminal, FitAddon } = await loadXterm();
const term = new Terminal({
fontFamily: getComputedStyle(document.documentElement).getPropertyValue('--mono'),
fontSize: 13,
cursorBlink: true,
// tmux keeps the history (the wheel scrolls it), xterm.js only the screen
scrollback: 0,
theme: { background: '#110f0c', foreground: '#f1ece4', cursor: '#ff8a3d', selectionBackground: 'rgba(255, 138, 61, 0.35)' },
});
const fit = new FitAddon();
term.loadAddon(fit);
term.open(this.screen);
term.parser.registerOscHandler(52, copyToClipboard);
const send = (m: unknown) => { if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(m)); };
term.onData((d) => send({ d }));
term.onResize(({ cols, rows }) => send({ cols, rows }));
term.attachCustomKeyEventHandler((e) => {
// Shift+Enter: a new line in Claude Code's input box (Ctrl+J), for keydown and the keypress after it
if (e.shiftKey && e.key === 'Enter') {
if (e.type === 'keydown') send({ d: '\n' });
return false;
}
if (e.type !== 'keydown') return true;
// Ctrl+C copies a selection made with Shift+drag; without one it goes to Claude Code (interrupt)
if (e.ctrlKey && e.key === 'c' && term.hasSelection()) {
void navigator.clipboard?.writeText(term.getSelection()).catch(() => undefined);
term.clearSelection();
return false;
}
// Ctrl+V: the browser pastes, xterm.js sends it on
return !(e.ctrlKey && e.key === 'v');
});
new ResizeObserver(() => { if (this.shown && this.screen.offsetWidth) fit.fit(); }).observe(this.screen);
this.term = term;
this.fit = fit;
return term;
}
}Das Terminal nimmt die Monospace-Schrift und die Farben der Seite. scrollback: 0, weil der Scrollback tmux gehört, und das Mausrad scrollt den. Dann die Tasten, bei denen ein Terminal im Browser ein paar Entscheidungen treffen muss:
Umschalt+Enter macht eine neue Zeile im Eingabefeld von Claude Code. Ein Terminal schickt für Enter und Umschalt+Enter dasselbe Zeichen, Claude Code kann sie also nicht unterscheiden. Die Ansicht schickt stattdessen
\n(Strg+J), das Claude Code als Zeilenumbruch nimmt, und schluckt den Tastendruck, der auf das Keydown folgt.Strg+C kopiert, wenn xterm.js eine eigene Auswahl hat, gezogen mit gedrückter Umschalttaste (und bleibt, wie das Kopieren über OSC 52, still, wo die Seite keine Zwischenablage hat). Einfaches Ziehen geht an tmux, das selbst kopiert. Ohne Auswahl geht Strg+C an Claude Code und unterbricht es.
Strg+V bleibt dem Browser: Er fügt ein, und xterm.js schickt den eingefügten Text weiter.
Ein ResizeObserver passt das Terminal neu ein, wenn seine Box die Größe ändert, und onResize sagt es dem Server.
Tabs auf der Seite einer Site
src/sitePage.ts bekommt die beiden Tabs. Ersetze die Datei:
import { h } from './dom.ts';
import { SessionControls } from './session.ts';
import { TerminalView } from './terminalView.ts';
import type { Config, Site, TerminalState } from '../shared/types.ts';
type Tab = 'preview' | 'terminal';
/** One site: what it is about, and on the right the site itself or its terminal. */
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 preview = h('div', { class: 'preview' }, this.frame, this.empty);
private session: SessionControls;
private terminal: TerminalView;
private tabs: Record<Tab, HTMLButtonElement>;
constructor(name: string, config: Config) {
this.name = name;
this.config = config;
this.session = new SessionControls(name, config.terminals);
this.terminal = new TerminalView(name, config.pty);
this.tabs = {
preview: h('button', { type: 'button', class: 'tab', role: 'tab', onclick: () => this.show('preview') }, 'Preview'),
terminal: h('button', { type: 'button', class: 'tab', role: 'tab', onclick: () => this.show('terminal') }, 'Terminal'),
};
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: 'view' },
h('div', { class: 'tabs', role: 'tablist' }, this.tabs.preview, this.tabs.terminal),
this.preview, this.terminal.el));
this.show('preview');
}
/**
* The site on the preview server: the same host name as the page (so it also works when the
* page is opened from another machine later), but its own port.
*/
get previewUrl() {
return `${location.protocol}//${location.hostname}:${this.config.previewPort}/${this.name}/`;
}
/** The site or its terminal on the right. */
show(tab: Tab) {
for (const [key, button] of Object.entries(this.tabs)) button.setAttribute('aria-selected', String(key === tab));
this.preview.hidden = tab !== 'preview';
this.terminal.el.hidden = tab !== 'terminal';
this.terminal.setShown(tab === 'terminal');
}
/** The list of sites changed (or arrived). */
update(sites: Site[]) {
const site = sites.find((s) => s.name === this.name) ?? null;
const wasBuilt = this.site?.built;
this.site = site;
this.heading.textContent = site?.title ?? this.name;
this.about.textContent = site ? site.description : 'There is no site of this name.';
this.frame.hidden = !site?.built;
this.empty.hidden = Boolean(site?.built);
if (site?.built && !wasBuilt) this.frame.src = this.previewUrl;
}
/** The sessions changed: this site's, or none. */
terminals(list: TerminalState[]) {
const state = list.find((t) => t.site === this.name);
this.session.update(state);
this.terminal.update(state);
}
/** Files of this site changed on disk: show the new state. */
filesChanged() {
// setting src again navigates the frame again, even to the same address
if (this.site?.built) this.frame.src = this.previewUrl;
}
/** The page shows another site. */
dispose() {
this.terminal.dispose();
}
}Die rechte Seite ist jetzt eine view mit zwei Tabs, der Vorschau aus Teil 2 und dem Terminal. show() wechselt zwischen ihnen und sagt dem Terminal, ob es auf dem Bildschirm ist; mehr braucht es nicht, um sich anzuhängen oder loszulassen. Der Zustand der Sitzung, den schon der Kopf zeigt, geht auch an das Terminal. So hängt es sich an, wenn eine Sitzung erscheint, und zeigt seine leere Box, wenn sie endet. dispose(), bisher leer, schließt das Terminal, wenn du eine andere Site öffnest.
Probier es aus
Bauen und starten (npm start), eine Site öffnen, Claude Code starten, falls es nicht läuft, und zum Tab Terminal wechseln:
Das ist der Bildschirm, den du in Teil 3 mit tmux attach gesehen hast, und er ist live. Tipp eine Frage und drück Enter, und Claude Code antwortet. Scroll mit dem Mausrad nach oben und drück eine beliebige Taste, um zurückzukommen. Zieh über etwas Text, und er liegt in deiner Zwischenablage. Öffne dieselbe Site in einem zweiten Fenster, und beide zeigen dieselbe Sitzung.
Die Sitzung nimmt die Größe des Terminals in der Seite an. Mit dem Browserfenster bei 1280 mal 800 Pixeln:
# The page's terminal in a browser window of 1280 × 800: the size tmux gives the session$ tmux -L sitesmith display -p -t =lumen-cafe: '#{window_width}x#{window_height}'146x49
Schließ den Browser-Tab oder stopp den Server, und Claude Code merkt nichts davon: Ein tmux-Client ist gegangen, mehr nicht.
Die Seite zeigt jetzt jede Sitzung und lässt dich hineintippen, und nur die Seite selbst kann diese Tür öffnen. Noch tippst aber du. Im nächsten Teil übernimmt das die Seite: Du beschreibst in einem Feld, was du willst, und Sitesmith tippt es in Claude Code, in einem Moment, in dem das sicher ist.
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.
