KursinhaltModul 1 · Lektion 2
Installieren und einrichten
Du installierst das Plugin, legst das Übungsprojekt wortzaehler an und richtest es mit /bootstrap so ein, dass /session starten kann.
MODUL 1 / EINRICHTEN
Hinweis: Stand und Prüfgrundlage
Stand: session-orchestrator 5.20.0 vom 14. November 2026. Die Abläufe sind am Quelltext dieser Version geprüft, nicht in einer frischen Installation durchgespielt. Weicht dein Stand ab, gelten README und User Guide des Projekts (Repository auf GitHub).
Das Plugin installieren
Die Installation läuft über den Plugin-Mechanismus von Claude Code. Starte Claude Code in einem beliebigen Ordner und gib nacheinander diese beiden Befehle ein:
/plugin marketplace add Kanevry/session-orchestrator
/plugin install session-orchestrator@kanevry
Der erste Befehl trägt die Quelle ein, der zweite installiert das Plugin daraus. Ob es angekommen ist, prüfst du so:
- Im Terminal listet
claude plugin list --jsonden aktivierten Eintragsession-orchestrator@kanevry. Fehlt er oder ist er deaktiviert, klärst du das zuerst über/plugin. - Im
installPathdieses Eintrags liegtnode_modules/js-yaml. Fehlt es, führst du dortnpm installaus und startest Claude Code danach neu. - Der Startbanner enthält:
🎯 Session Orchestrator v5.20.0 — /session …
Wie du das Plugin später aktualisierst, steht in Lektion 5.
Das Übungsprojekt wortzaehler
Das Plugin braucht ein Projekt, an dem es arbeiten kann. Du baust dafür ein kleines Node-Programm, einen Wortzähler. Es ist klein genug, dass du jede Änderung der späteren Session nachlesen kannst.
Lege einen leeren Ordner wortzaehler an, wechsle hinein und starte dort Claude Code. Dann kopierst du diesen Prompt:
Lege ein kleines Node-Projekt an (Node 24, ESM, ohne Abhängigkeiten): `src/wortzaehler.js` exportiert `zaehle(text)` und liefert `{ woerter, zeilen, zeichen }`; `src/cli.js` liest Datei oder stdin; `test/wortzaehler.test.js` nutzt `node:test`; `package.json` mit `"type": "module"` und Skripten `typecheck` und `lint` (beide `node --check src/wortzaehler.js && node --check src/cli.js`, nur Syntaxprüfung, kein echter Linter) sowie `test` (`node --test`). Keine CLAUDE.md anlegen. Dann `git init`, `npm test`, committen.
Zwei Stellen sind Absicht. Die Skripte typecheck und lint prüfen hier nur die Syntax. Für ein Übungsprojekt reicht das, weil node --check bei einem Syntaxfehler mit einem Exit-Code ungleich 0 endet, und am Exit-Code hängt jedes Gate (Lektion 1). Die CLAUDE.md legst du nicht selbst an, das übernimmt gleich der Bootstrap.
Danach liegen diese Dateien im Ordner:
package.jsonsrc/wortzaehler.jssrc/cli.jstest/wortzaehler.test.js
Prüf selbst nach, was der Agent meldet: npm test läuft durch, und git log --oneline zeigt einen Commit.
Der Bootstrap richtet das Projekt für das Plugin ein
Das Plugin braucht CLAUDE.md, den Block ## Session Config darin und .orchestrator/bootstrap.lock. Fehlt etwas, führt es zuerst den Bootstrap aus und prüft danach erneut, ob alles da ist. Erst dann geht es weiter. /close prüft davor noch, ob dir die abzuschließende Session gehört. Der Bootstrap ergänzt, was fehlt. Tippe im Ordner wortzaehler in Claude Code:
/bootstrap --fast --no-interview
--fast überspringt die Stufenauswahl. --no-interview schaltet alle Fragen ab und setzt die Dispatcher-Autonomie auf off, eine Einstellung, die du in diesem Kurs nicht brauchst. Beim ersten vollständigen Bootstrap ohne diese Flags beantwortest du sieben bis neun Fragen.
Der Fast-Bootstrap ergänzt die folgenden Dateien, wenn sie fehlen. Deine vorhandenen Dateien bleiben erhalten:
CLAUDE.mdmit dem Abschnitt## Session Config.gitignoreundREADME.md.claude/loop.md.claude/rules/*.md, die universellen Regeln des Plugins.orchestrator/bootstrap.lock
Er committet das Ergebnis als chore: bootstrap (fast). Ein package.json, Tests oder eine CI-Konfiguration legt er nicht an.
Die drei Qualitätskommandos im Konfigurationsblock
In der neuen CLAUDE.md steht der Abschnitt ## Session Config. Für das Übungsprojekt soll er so aussehen:
## Session Config
test-command: npm test
typecheck-command: npm run typecheck
lint-command: npm run lint
agents-per-wave: 6
waves: 5
persistence: true
enforcement: warn
Was der Bootstrap bei dir einträgt, kann davon abweichen. Der Block braucht die drei Qualitätskommandos sowie agents-per-wave, waves, persistence und enforcement. Lass diese Pflichtfelder stehen. Der Bootstrap leitet die Kommandos aus deinem Projekt ab. Prüfe sie deshalb und passe sie für das Übungsprojekt an den Block oben an.
Hast du den Block geändert, ist dein Arbeitsbaum nicht mehr sauber, und vor der ersten Welle verlangt das Plugin einen sauberen Baum (Lektion 3). Committe die Änderung deshalb gleich:
git add CLAUDE.md
git commit -m "chore: set session config commands"
Am Exit-Code hängt jedes Gate, und das hat eine Kehrseite. Ein Kommando, das Fehler ausgibt und trotzdem mit 0 endet, gilt als bestanden. Das Gate meldet dann Grün, obwohl nichts geprüft wurde. Setz deshalb nie einen Platzhalter ein, der immer 0 liefert, etwa ein echo. Auch erkannte Platzhalter wie echo oder Befehle ohne Wirkung zählen beim Gate als bestanden. Bei /close greift eine zusätzliche Prüfung: strict blockiert solche Platzhalter. Mit warn bekommst du eine Warnung, die Ausnahme steht in STATE.md und der Abschluss geht weiter. Mit off erscheint nur eine Meldung auf stderr, der Fehlerausgabe im Terminal. Hast du in einem Projekt keinen Typecheck, trägst du skip ein.
Welche Einstellungen am ersten Tag zählen
Die folgende Auswahl trifft dieser Kurs, abgeleitet aus der Doku. Vom Projekt selbst stammt sie nicht.
- Die drei Qualitätskommandos. Sie legen fest, was ein Gate überhaupt prüft.
agents-per-wave. Wie viele Agenten pro Welle höchstens gleichzeitig arbeiten. 6 passt für den Anfang. Stößt du auf Zeitlimits, senkst du den Wert.enforcement. Wie streng die Pfadprüfung je Welle ist:warnerlaubt mit Warnung,strictverweigert. Wie die Prüfung arbeitet, steht in Lektion 4.
persistence: true lässt du stehen, davon hängt das Fortsetzen einer unterbrochenen Session ab (Lektion 5). waves kannst du ignorieren, die Typen feature und deep bringen ihre Wellenzahl mit und ignorieren abweichende Werte. Ebenso ignorieren kannst du isolation, max-turns, pencil, cross-repos, vault, discovery-* und mirror.
Wenn etwas klemmt
/session braucht zuerst Bootstrap. bootstrap.lock, CLAUDE.md oder der Block ## Session Config fehlt. Das Plugin führt zuerst die Einrichtung aus und prüft danach erneut, ob alles da ist. Fehlt noch etwas, liest du die Meldung. Für die Einrichtung von Hand nutzt du /bootstrap. Gibt es den Block schon, nimmst du /bootstrap --retroactive.
Das Plugin liest deine Config nicht. Die Überschrift muss genau stimmen. Schon ein angehängter Kommentar kann dazu führen, dass das Plugin den ganzen Block übersieht. Kann es eine Feldzeile nicht lesen, zeigt es bei warn einen Hinweis. Bei strict gibt der Parser, der die Config einliest, keine Config aus. Vergleiche deinen Block Zeichen für Zeichen mit dem Block oben und lies die Meldungen dazu.
Node wird im Hook nicht gefunden. Claude Code blockiert Edit, Write oder Bash. Ursache: Die Hooks des Plugins laufen über /bin/sh und lesen deine ~/.zshrc nicht, deshalb findet das System Node dort womöglich nicht. Lösung laut User Guide: die Umgebungsvariable SO_NODE_BIN auf den absoluten Pfad deines node setzen. Den Pfad zeigt dir command -v node. Wo du die Variable setzt, gibt der Kurs nicht vor, maßgeblich ist der User Guide.
Probe
Du kannst zu Lektion 3, wenn alles davon stimmt:
claude plugin list --jsonnenntsession-orchestrator@kanevry.- Im Ordner
wortzaehlerliegenCLAUDE.mdund.orchestrator/bootstrap.lock.grep -E "(test|typecheck|lint)-command" CLAUDE.mdzeigt die drei npm-Kommandos von oben. git log --onelinezeigtchore: bootstrap (fast), darüber höchstens deinen Commit für den Konfigurationsblock.git statusmeldet einen sauberen Arbeitsbaum.npm run typecheck && npm test && npm run lintendet mit Exit-Code 0. Prüf das mitecho $?direkt danach.
Wissenscheck