Course contentModule 1 · Lesson 2
Install and set up
You install the plugin, create the wortzaehler practice project, and set it up with /bootstrap so that /session can start.
MODULE 1 / SETUP
Note: Version and verification basis
Version: session-orchestrator 5.20.0 from November 14, 2026. The workflows were checked against this version's source code, not tried out in a fresh installation. If your version differs, the project's README and User Guide take precedence (repository on GitHub).
Install the plugin
Installation runs through Claude Code's plugin mechanism. Start Claude Code in any folder and enter these two commands one after the other:
/plugin marketplace add Kanevry/session-orchestrator
/plugin install session-orchestrator@kanevry
The first command registers the source, the second installs the plugin from it. You check that it arrived like this:
- In the terminal,
claude plugin list --jsonlists the enabled entrysession-orchestrator@kanevry. If it is missing or disabled, resolve that through/pluginfirst. - That entry's
installPathcontainsnode_modules/js-yaml. If it's missing, runnpm installthere, then restart Claude Code. - The startup banner contains:
🎯 Session Orchestrator v5.20.0 — /session …
How to update the plugin later is covered in Lesson 5.
The practice project wortzaehler
The plugin needs a project to work on. For that you build a small Node program, a word counter. It's small enough that you can read through every change of the later session.
Create an empty folder wortzaehler, change into it and start Claude Code there. Then copy this prompt:
Create a small Node project (Node 24, ESM, no dependencies): `src/wortzaehler.js` exports `zaehle(text)` and returns `{ woerter, zeilen, zeichen }`; `src/cli.js` reads a file or stdin; `test/wortzaehler.test.js` uses `node:test`; `package.json` with `"type": "module"` and scripts `typecheck` and `lint` (both `node --check src/wortzaehler.js && node --check src/cli.js`, syntax check only, not a real linter) and `test` (`node --test`). Don't create a CLAUDE.md. Then `git init`, `npm test`, commit.
Two things here are deliberate. The typecheck and lint scripts only check syntax. For a practice project that's enough, because node --check ends with an exit code other than 0 on a syntax error, and every gate hangs on the exit code (Lesson 1). You don't create the CLAUDE.md yourself, the bootstrap takes care of that in a moment.
Afterward these files are in the folder:
package.jsonsrc/wortzaehler.jssrc/cli.jstest/wortzaehler.test.js
Check for yourself what the agent reports: npm test runs through, and git log --oneline shows one commit.
The bootstrap sets the project up for the plugin
The plugin needs CLAUDE.md, its ## Session Config block and .orchestrator/bootstrap.lock. If anything is missing, it runs bootstrap first and checks again that everything is there. Only then does it continue. Before that, /close also checks whether the session to close belongs to you. Bootstrap adds what's missing. In the wortzaehler folder, type in Claude Code:
/bootstrap --fast --no-interview
--fast skips tier selection. --no-interview turns off all questions and sets dispatcher autonomy to off, a setting you don't need in this course. On your first full bootstrap without these flags, you answer seven to nine questions.
Fast bootstrap adds the following files if they're missing. Your existing files stay as they are:
CLAUDE.mdwith the section## Session Config.gitignoreandREADME.md.claude/loop.md.claude/rules/*.md, the plugin's universal rules.orchestrator/bootstrap.lock
It commits the result as chore: bootstrap (fast). It doesn't create a package.json, tests or a CI configuration.
The three quality commands in the config block
The new CLAUDE.md contains the section ## Session Config. For the practice project it should look like this:
## 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
What bootstrap enters for you can differ from this. The block needs the three quality commands plus agents-per-wave, waves, persistence and enforcement. Keep these required fields. Bootstrap works out the commands from your project, so check them and match them to the block above for the practice project.
Once you've changed the block, your working tree is no longer clean, and before the first wave the plugin requires a clean tree (Lesson 3). So commit the change right away:
git add CLAUDE.md
git commit -m "chore: set session config commands"
Every gate hangs on the exit code, and that has a flip side. A command that prints errors and still ends with 0 counts as passed. The gate then reports green although nothing was checked. So never enter a placeholder that always returns 0, such as an echo. Even recognized placeholders like echo or commands that do nothing count as passed at the gate. At /close, an extra check applies: strict blocks such placeholders. With warn, you get a warning, the exception is recorded in STATE.md and the close continues. With off, a message appears only on stderr, the terminal's error output. If a project has no typecheck, you enter skip.
Which settings matter on day one
The following selection is this course's own, derived from the docs. It doesn't come from the project itself.
- The three quality commands. They determine what a gate checks at all.
agents-per-wave. How many agents at most work at the same time per wave. 6 is a good start. If you run into time limits, lower the value.enforcement. How strict the path check is per wave:warnallows with a warning,strictrefuses. How the check works is covered in Lesson 4.
You leave persistence: true as it is, since resuming an interrupted session depends on it (Lesson 5). You can ignore waves: the types feature and deep bring their own wave count and ignore differing values. You can equally ignore isolation, max-turns, pencil, cross-repos, vault, discovery-* and mirror.
When something sticks
/session needs bootstrap first. bootstrap.lock, CLAUDE.md or the ## Session Config block is missing. The plugin runs setup first, then checks again that everything is there. If something is still missing, read the message. To run setup yourself, use /bootstrap. If the block already exists, use /bootstrap --retroactive.
The plugin doesn't read your config. The heading must match exactly. Even an appended comment can make the plugin miss the entire block. If it can't read a field line, it shows a notice in warn mode. In strict mode, the parser that reads the config outputs no config. Compare your block character by character with the example above and read the messages about it.
Node isn't found in the hook. Claude Code blocks Edit, Write or Bash. Cause: the plugin's hooks run through /bin/sh and don't read your ~/.zshrc, so the system may not find Node there. Fix according to the User Guide: set the environment variable SO_NODE_BIN to the absolute path of your node. command -v node shows you the path. Where you set the variable isn't something the course dictates, the User Guide is authoritative.
Check yourself
You can move on to Lesson 3 once all of this is true:
claude plugin list --jsonnamessession-orchestrator@kanevry.- In the
wortzaehlerfolder there areCLAUDE.mdand.orchestrator/bootstrap.lock.grep -E "(test|typecheck|lint)-command" CLAUDE.mdshows the three npm commands from above. git log --onelineshowschore: bootstrap (fast), above it at most your commit for the config block.git statusreports a clean working tree.npm run typecheck && npm test && npm run lintends with exit code 0. Check that withecho $?right afterward.
Knowledge Check