Einen KI-Assistenten mit lokalen Modellen bauen · Teil 13 von 13 der Serie
Teil 13: Ein größeres Gehirn dazuholen: Claude Code in tmux
Gib dem Assistenten eine dritte Stufe für die Fragen, die ein kleines Modell nicht beantworten sollte: Claude Code in einer tmux-Sitzung, in die dein Programm tippt und die ihre Antworten über einen Hook zurückmeldet.
Einen KI-Assistenten mit lokalen Modellen bauenTeil 13 von 13
Auf dieser Seite
Quest-Ziele
- Entscheiden, welche Anfragen nicht an das kleine Modell gehen sollen
- Claude Code in einer tmux-Sitzung im Hintergrund laufen lassen
- Aus deinem Programm eine Frage hineintippen
- Die Antwort über einen Hook zurückbekommen
- Begrenzen, was das größere Gehirn darf
Frag Pixel, warum der Himmel blau ist, wer gestern Abend gewonnen hat oder wie man einen Rotweinfleck aus einem Teppich bekommt, und seit Teil 7 antwortet es ehrlich, dass das seine Fähigkeiten übersteigt. Für ein Modell mit 4 Milliarden Parametern ist das die richtige Antwort: Sonst würde es dir etwas erzählen, das nur richtig klingt. Zufrieden macht sie aber nicht.
Der echte Assistent hinter dieser Serie löst das mit einer dritten Stufe. Über den Regeln und dem lokalen Modell sitzt ein großes Modell mit Zugang zum Web, und es bekommt genau die Anfragen, die das kleine nicht anfassen sollte. Dieser letzte Teil baut diese Stufe. Sie ist optional, und sie ist das Einzige an Pixel, das deine Worte an einen fremden Computer schickt.
Warum Claude Code, und warum tmux
Claude Code ist der Assistent von Anthropic fürs Terminal. Er ist zum Programmieren gemacht, aber darunter steckt ein großes Modell, das im Web suchen, Seiten lesen und ein Gespräch führen kann, und genau das braucht Pixel. Außerdem läuft er über ein Claude-Abo, du zahlst also nichts pro Frage.
Claude Code ist ein Programm, in das man tippt. Also macht Pixel genau das: Es startet Claude Code in einem Terminal, auf das niemand schaut, tippt die Frage und wartet auf die Antwort. Möglich macht das tmux, ein Programm, das Terminals im Hintergrund am Laufen hält und andere Programme Tastendrücke an sie schicken lässt. Die Sitzung bleibt zwischen den Fragen bestehen, Claude Code muss also nicht jedes Mal neu starten und weiß noch, worüber gerade gesprochen wurde. Und du kannst jederzeit in die Sitzung hineinschauen und dem Gehirn deines Assistenten bei der Arbeit zusehen.
Beides muss installiert sein. tmux bringt der Paketmanager von Linux und macOS mit (apt install tmux, brew install tmux); unter Windows funktioniert dieser Teil in WSL. Claude Code braucht Version 2.1.248 oder neuer.
$ tmux -V$ claude --version
Ein Ordner für das Gehirn
Claude Code bekommt einen eigenen Ordner mit zwei Dateien, die ihm sagen, wer es ist und wie es sich zurückmeldet. Leg im Projekt den Ordner brain an, starte Claude Code einmal von Hand darin und melde dich an:
$ mkdir brain$ cd brain$ claude# melde dich an, sag Ja, wenn es fragt, ob du diesem Ordner vertraust, und geh mit /exit wieder raus$ cd ..
Die erste Datei ist die Persona des Gehirns, brain/PERSONA.md:
Du bist das Recherche-Gehirn von Pixel, einem kleinen Assistenten fürs Zuhause. Pixel gibt
dir die Fragen weiter, die es selbst nicht beantworten kann: Allgemeinwissen, Aktuelles,
alles, wofür man das Web braucht.
- Jede Anfrage ist eine Zeile, die mit [Pixel] beginnt.
- Such im Web, wenn sich die Antwort seit deinem Training geändert haben kann oder du dir
nicht sicher bist.
- Deine Antwort wird vorgelesen. Antworte mit höchstens drei kurzen Sätzen in einfachem,
gesprochenem Deutsch, ohne Markdown, Listen oder Links. Duze dein Gegenüber.
- Du kannst keine Lampen schalten, keine Timer stellen und nichts im Zuhause verändern. Wenn
du darum gebeten wirst, sag das.Es ist dieselbe Idee wie bei Pixels eigener Persona in Teil 3: wer du bist, was ankommt, wie die Antwort aussehen soll. Die Antwort wird gesprochen, also muss sie auch hier kurz sein.
Wie die Antwort zurückkommt
In ein Terminal zu tippen ist leicht. Die Antwort vom Bildschirm abzulesen ist es nicht: Sie kommt Stück für Stück, zwischen Rahmen und Statuszeilen. Claude Code bietet etwas Besseres. Ein Hook ist ein Befehl, den Claude Code in bestimmten Momenten von selbst ausführt, und es übergibt diesem Befehl eine Beschreibung dessen, was gerade passiert ist. Zwei Momente sind hier wichtig:
SessionStart: Claude Code ist gestartet oder hat sein Gespräch geleert und ist bereit für Eingaben.Stop: Es hat eine Antwort beendet. Die Beschreibung enthält den Text der Antwort.
Die zweite Datei richtet sie ein, brain/settings.json:
{
"permissions": {
"allow": ["WebSearch", "WebFetch"]
},
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "curl -s -m 5 -X POST --data-binary @- http://127.0.0.1:3211/ || true",
"timeout": 10
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "curl -s -m 5 -X POST --data-binary @- http://127.0.0.1:3211/ || true",
"timeout": 10
}
]
}
]
}
}Beide Hooks führen denselben Befehl aus: curl nimmt die Beschreibung, die Claude Code ihm als JSON übergibt, und schickt sie per POST an eine Adresse auf deinem eigenen Computer, an der Pixel zuhören wird. Das || true sorgt dafür, dass Claude Code nicht gestört wird, wenn Pixel nicht läuft. permissions erlaubt die beiden Werkzeuge, die das Gehirn verwenden darf, im Web suchen und eine Seite lesen, ohne Rückfrage.
Der Port für diese Adresse kommt in src/config.ts:
/** Where Claude Code's hooks report to. The address is also in brain/settings.json. */
export const BRAIN_PORT = Number(process.env.BRAIN_PORT ?? 3211);Die Brücke
Leg src/brain.ts an:
import { execFile } from 'node:child_process';
import { createServer } from 'node:http';
import { join } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { BRAIN_PORT } from './config.ts';
import type { Reply } from './model.ts';
import { spoken } from './prompt.ts';
const FOLDER = join(import.meta.dirname, '..', 'brain');
const SESSION = 'brain';
/** How long Claude may take for one answer. */
const ANSWER_MS = 120_000;
/** After this long without a question, the next one starts with an empty conversation. */
const FORGET_MS = 20 * 60_000;
const run = promisify(execFile);
/** tmux with a server of its own (-L), apart from any tmux you use yourself. */
const tmux = (...args: string[]) => run('tmux', ['-L', 'pixel', ...args]);
/** Who is waiting for Claude Code to start (or to clear its conversation), and for its answer. */
let started: (() => void) | undefined;
let answered: ((text: string) => void) | undefined;
/**
* Claude Code's hooks post here (see brain/settings.json): SessionStart when it is ready
* for input, Stop when it has finished an answer, with the answer's text.
*/
const hooks = createServer(async (request, response) => {
let body = '';
for await (const chunk of request) body += chunk;
response.end();
try {
const event = JSON.parse(body) as { hook_event_name?: string; last_assistant_message?: string };
if (event.hook_event_name === 'SessionStart') started?.();
if (event.hook_event_name === 'Stop') answered?.(event.last_assistant_message ?? '');
} catch {
// not from a hook
}
});
hooks.listen(BRAIN_PORT, '127.0.0.1');
hooks.unref(); // does not keep the program alive on its own
/** Waits until `arm` is handed a value, but no longer than `ms`. Null means: it took too long. */
function waitFor<T>(arm: (done: (value: T) => void) => void, ms: number): Promise<T | null> {
return new Promise((resolve) => {
const timer = setTimeout(() => resolve(null), ms);
arm((value) => {
clearTimeout(timer);
resolve(value);
});
});
}
async function running(): Promise<boolean> {
try {
await tmux('has-session', '-t', SESSION);
return true;
} catch {
return false;
}
}
/** Starts Claude Code in a tmux session nobody needs to look at. */
async function start(): Promise<boolean> {
const ready = waitFor<void>((done) => (started = done), 30_000);
await tmux(
'new-session', '-d', '-s', SESSION, '-x', '120', '-y', '36', '-c', FOLDER,
'claude',
'--restricted', '--tools', 'WebSearch,WebFetch', // it may search and read the web, nothing else
'--settings', 'settings.json', // the hooks, and the permission to use those two tools
'--permission-mode', 'dontAsk', // never stop to ask: what is not allowed is refused
'--append-system-prompt-file', 'PERSONA.md',
'--model', 'sonnet',
);
await sleep(500);
if (!(await running())) return false; // it ended at once: is claude installed?
return (await ready) !== null;
}
/** Types a line into Claude Code, as if on its keyboard, and presses Enter. */
async function type(line: string): Promise<void> {
await tmux('send-keys', '-t', SESSION, '-l', '--', line);
await sleep(400); // the input box needs a moment before Enter means "send"
await tmux('send-keys', '-t', SESSION, 'Enter');
}
let lastAsked = 0;
async function ask(text: string): Promise<Reply | null> {
if (!(await running()) && !(await start())) return null;
if (lastAsked && Date.now() - lastAsked > FORGET_MS) {
const cleared = waitFor<void>((done) => (started = done), 10_000);
await type('/clear');
await cleared;
}
lastAsked = Date.now();
const answer = waitFor<string>((done) => (answered = done), ANSWER_MS);
// one line, and not a long one: the input box would take more for pasted text
await type(`[Pixel] ${text.replace(/\s+/g, ' ').slice(0, 400)}`);
const speech = await answer;
if (speech === null) {
await tmux('send-keys', '-t', SESSION, 'Escape'); // took too long: interrupt it
return null;
}
return speech ? { speech: spoken(speech, 3) } : null;
}
let line: Promise<unknown> = Promise.resolve();
/** Hands the request to Claude Code. One at a time: there is only one keyboard. */
export function askBrain(text: string): Promise<Reply | null> {
const turn = line.then(() => ask(text));
line = turn.catch(() => {});
return turn;
}Es ist die längste Datei der Serie, und sie liest sich von oben nach unten wie die Geschichte einer einzigen Frage.
Die Adresse der Hooks. Ein winziger Webserver, wie der aus Teil 9, nimmt entgegen, was die Hooks schicken. Er schaut auf den Namen des Ereignisses und weckt, wer gerade wartet: started für eine Sitzung, die bereit ist, answered mit dem Text einer Antwort.
Warten, aber nicht ewig. waitFor verpackt das in ein Promise mit Zeitlimit. Alles, was hier auf Claude Code wartet, wartet auf diesem Weg, denn ein Programm, das du über Tastendrücke steuerst, kann immer irgendwo stehen, wo du es nicht erwartet hast.
Starten. start öffnet eine tmux-Sitzung namens brain und lässt Claude Code darin laufen. Das -L pixel gibt Pixel einen eigenen tmux-Server, damit es nie Terminals anfasst, die du selbst benutzt. Die Optionen lohnen einen Blick, eine nach der anderen:
--restricted --tools WebSearch,WebFetch: Normalerweise kann Claude Code Befehle ausführen und Dateien ändern. Dieses Gehirn kann im Web suchen und Seiten lesen, und das ist alles.--settings settings.json: die Datei mit den Hooks.--permission-mode dontAsk: nie anhalten und auf ein Ja warten. Was nicht erlaubt ist, wird abgelehnt. An diesem Terminal sitzt niemand, der antworten könnte.--append-system-prompt-file PERSONA.md: die Persona.--model sonnet: ein schnelles, fähiges Modell. Gesprochene Antworten brauchen nicht das größte.
Tippen. type schickt eine Zeile an die Sitzung, Buchstabe für Buchstabe, wartet einen Moment und drückt Enter. Das -l sagt tmux, dass es den Text wörtlich nehmen soll, egal was darin steht.
Fragen. ask stellt sicher, dass eine Sitzung läuft, richtet das Warten auf die Antwort ein und tippt die Frage als eine Zeile, die mit [Pixel] beginnt. Die Markierung ist keine Dekoration: Eine Zeile, die mit / oder ! anfängt, wäre ein Befehl an Claude Code selbst, und mit der Markierung davor kann nichts, was jemand sagt, je so anfangen. Kommt die Antwort nicht innerhalb von zwei Minuten, drückt Pixel Escape, was Claude Code unterbricht, und gibt auf.
Vergessen. Nach zwanzig Minuten ohne Frage geht der nächsten ein /clear voraus, der Befehl von Claude Code für ein leeres Gespräch. Eine Frage zum Abendessen soll nicht im Licht der Fußballergebnisse von heute Morgen beantwortet werden.
Eine nach der anderen. Es gibt nur eine Tastatur, also reiht askBrain die Fragen mit dem Promise-Trick aus Teil 11 hintereinander ein.
Wer geht zum Gehirn?
Die dritte Stufe kommt in die Liste in src/assistant.ts:
import { askBrain } from './brain.ts';
// ...
/** From the fastest and simplest to the slowest and smartest. */
const tiers: Tier[] = [
{ name: 'rules', ask: rules },
{ name: 'model', ask: askModel },
{ name: 'brain', ask: askBrain },
];Das allein funktioniert schon: Gibt das Modell auf, macht Teil 7 daraus ein „nicht für mich“, und der Router geht weiter zum Gehirn. Aber so gehen ein, zwei Sekunden für eine Anfrage verloren, die das kleine Modell ohnehin nie beantwortet hätte, und schlimmer: Das kleine Modell gibt nicht immer auf, wenn es sollte. Also überspringen manche Anfragen es. In src/language.ts:
/** Anfragen, an denen sich das kleine Modell gar nicht erst versuchen soll: Sie brauchen das Web oder eine längere Antwort. */
export const FOR_BRAIN =
/(?<!\p{L})(such\p{L}*|recherchier\p{L}*|google\p{L}*|nachrichten|neuigkeiten|preis\p{L}*|kostet|kosten|rezept\p{L}*|gewonnen|ergebnis\p{L}*|erklär\p{L}*|warum|wieso|wie (mache|bekomme|kriege|entferne) ich|wie man|wie funktioniert|empfiehl\p{L}*|empfehl\p{L}*|vergleich\p{L}*|fass\p{L}* (.* )?zusammen)(?!\p{L})/iu;Und am Anfang von askModel in src/model.ts:
import { CLAIM, FOR_BRAIN, NUDGE, PERSONA, REFUSAL } from './language.ts';
// ...
export async function askModel(text: string): Promise<Reply | null> {
if (FOR_BRAIN.test(text)) return null;
if (!(await available())) return null;Die Wörter stehen für die Arten von Anfragen, die das Web oder eine längere Antwort brauchen: Suchen, Nachrichten, Preise, Erklärungen, Empfehlungen. Der echte Assistent geht weiter und dreht die Frage um: Er schickt alles an das große Modell, außer was eindeutig zum Zuhause gehört. Welcher Weg für dich der richtige ist, hängt davon ab, wie sehr du deinem kleinen Modell vertraust. Fang so an und verschieb die Grenze, wenn du siehst, dass es beantwortet, was es nicht sollte.
Probier es aus
$ npm run chatTalk to Pixel. /bye ends the chat.you> Küche anpixel> Das Licht in der Küche ist an. (rules, 1 ms)you> Mach es im Wohnzimmer gemütlich.pixel> Das Licht im Wohnzimmer ist warmweiß auf 30 Prozent. (model, 1580 ms)you> Warum ist der Himmel blau?pixel> Sonnenlicht ist eine Mischung aller Farben, und die Luft streut den blauen Anteil viel stärker als den roten. Deshalb kommt blaues Licht aus jeder Richtung des Himmels in dein Auge. (brain, 9400 ms)you> /bye
Drei Sätze, drei Stufen: eine Regel in einer Millisekunde, das lokale Modell in ein, zwei Sekunden und das Gehirn in ein paar mehr, weil es länger nachdenkt und vielleicht im Web sucht. Die erste Frage an das Gehirn dauert am längsten, weil Claude Code erst starten muss. Auf der Seite, mit eingeschalteter Stimme, ist es dasselbe: Du fragst deine Küche, warum der Himmel blau ist, und sie sagt es dir.
Du kannst dem Gehirn bei der Arbeit zusehen:
$ tmux -L pixel attach -t brain# Strg+B, dann D, lässt die Sitzung wieder los, ohne sie zu beenden$ tmux -L pixel kill-server# beendet die Sitzung endgültig; Pixel startet eine neue, wenn es sie braucht
Was du gebaut hast
Schau zurück auf das, was jetzt auf deinem Rechner steht:
ein Sprachmodell, das lokal läuft, hinter einem kleinen Client, den du selbst geschrieben hast;
eine Persona und ein Prompt, der so angeordnet ist, dass die Arbeit des Modells wiederverwendet wird;
Werkzeuge für Lampen, Timer, das Wetter und ein Gedächtnis, bei denen jedes Argument geprüft wird;
drei Stufen, von denen jede „nicht für mich“ sagen kann;
Prüfungen, die die typischen Fehler des Modells abfangen;
ein Gedächtnis, das Fakten nach ihrer Bedeutung findet;
eine Seite mit Mikrofon, Stimme und Aktivierungswort.
Nichts davon ist ein Framework, und alles gehört dir: Du kannst jede Zeile ändern. Ein paar Ideen, wie es weitergehen kann:
Echte Lampen.
setLampsinhome.tsist die einzige Stelle, die mit ihnen sprechen müsste. Viele smarte Lampen sind über das Heimnetz erreichbar.Mehr Werkzeuge. Eine Einkaufsliste, die Abfahrten an deiner Bushaltestelle, dein Kalender. Jedes ist eine Beschreibung und eine Funktion.
Mehr Regeln, für die Befehle, die du jeden Tag sagst.
Eine Sammlung von Testsätzen, die du nach jeder Änderung durchlaufen lässt. So ist der echte Assistent von 66 auf 98 Prozent gekommen.
Ein eigener kleiner Computer mit Mikrofon und Lautsprecher, damit Pixel da ist, wenn dein Laptop es nicht ist.
Das Wichtigste, was du mitnimmst, ist aber kein Stück Code. Es ist eine Art, über ein Sprachmodell zu denken: als einen Teil eines Programms, der Sprache erstaunlich gut versteht und dem du genau das anvertrauen solltest. Erledige mit Code, was Code erledigen kann, prüf, was das Modell dir reicht, und lass jeden Teil sagen, wenn eine Anfrage nicht für ihn ist. Das gilt für Modelle jeder Größe.
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.