# session-orchestrator (full description for LLMs)

Loop engineering for AI coding agents: a session-orchestration plugin that turns ad-hoc agent sessions into a repeatable research, plan, wave-execute, close loop with verification gates. It is a workflow layer that runs on top of the coding agent you already have (Claude Code, Codex CLI, Cursor IDE, or Pi), not a replacement for it. Maintained by one person, Bernhard Götzendorfer, Vienna; shipped as-is with best-effort maintenance. Not affiliated with or endorsed by Anthropic, OpenAI, or Cursor. MIT license, local by default, no account required, telemetry strictly opt-in.

Version 4.0.0 · npm package: session-orchestrator · requires Node.js >= 24 · https://session-orchestrator.com

Cost: free, MIT licence. You still pay whatever your coding tool costs; that part is not affected.

Windows: runs natively but is not covered by CI; macOS and Linux are.

## The loop

- /session [housekeeping|feature|deep] - research and Q&A: inspects git state, open issues, CI status, prior-session records, then presents one structured summary with a recommendation. Scope is agreed with the operator before any code.
- /go - executes the agreed scope in five typed waves (Discovery, Impl-Core, Impl-Polish, Quality, Finalization) with parallel sub-agents and a quality gate (typecheck, test, lint) between waves. For work that outgrows five waves there is a named ultradeep profile - a profile over session-type deep, not a fourth enum value - running seven waves: Research plus Code-Discovery, a blocking coordinator Synthesis-Gate, Impl-Core, Impl-Polish, a read-only Review-Panel, Quality, Release.
- /close - verifies every planned item against evidence, runs the full gate one last time, files carryover issues for unfinished work, commits cleanly, mirrors to GitHub when configured, writes session records and learnings.

## Why waves and parallel sub-agents

Containment, not raw speed: (a) file-scope deconfliction by construction - two agents in the same wave never write the same file; (b) context isolation per agent - one agent's confusion cannot leak into another's context window; (c) inter-wave review stops a bad pattern from propagating into later work; (d) the Quality wave runs a simplification pass on AI-generated code before tests are written, otherwise tests pin the AI patterns into place.

## Guardrails (mechanisms, not assertions)

- Destructive-command guard: 14 rules over git reset/checkout-discard/clean/stash, rm -rf, force-push, SQL DROP - 10 of them block outright and 4 warn (hooks/pre-bash-destructive-guard.mjs, policy in .orchestrator/policy/blocked-commands.json)
- Scope enforcement: PreToolUse hook blocks writes outside an agent's declared file scope (hooks/enforce-scope.mjs)
- Verification Iron Law: no completion claims without fresh verification evidence (.claude/rules/verification-before-completion.md)
- Full Gate: typecheck + tests + lint + debug-artifact scan, mechanically un-skippable at the Quality wave and session end
- Session lock with heartbeat liveness per repo working copy (scripts/lib/session-lock.mjs)
- Sub-agents may never run git add/commit/stash/push; the coordinator owns all VCS operations (PSA-007)
- 10 autopilot kill-switches in a frozen enum; echo-stub detection catches a test command that is secretly a no-op
- Honest platform note: hard enforcement is full on Claude Code; Cursor is post-hoc; Pi is bridged; Codex CLI scope enforcement is currently unavailable. Quality gates run fully on all four.

## Memory and self-improvement

Nothing is learned silently. Sessions append plain-text JSONL records (sessions, learnings with confidence scores and expiry). /evolve extracts patterns after 5+ sessions; a reconcile engine turns eligible learnings into PROPOSED rules that the operator approves one by one - it structurally cannot emit always-on rules. Failed approaches are recorded as "What Not To Retry" and force-read at the next session start.

## Cross-repo (single operator, many repos)

/portfolio aggregates issues/MRs/CI health across all registered repos; /dispatcher ranks free repos by backlog, staleness and readiness, then claims a lease atomically before launching; a vault live-status board shows in-progress/force-closed sessions across every repo on the host. GitLab and GitHub are both first-class (auto-detected; glab and gh drive the full issue/MR lifecycle).

## Eval standard

aiat-llm-eval v1: an open standard for honest LLM session evaluation. Pre-registered rubric, deterministic checks before any LLM judge, three-state verdicts with explicit abstention (cannot-determine instead of fake zeros), no global score (the validator rejects overall/total/mean fields), no superlatives in conforming reports, reproducibility as an executable proof (--verify). A session scoring itself is labelled a self-evaluation. Spec: docs/eval/aiat-llm-eval-v1.md in the repository.

## Numbers

<!-- census:start -->
Version 4.0.0 · counted 2026-09-07 at a4315993 · skills 43 · commands 25 · agents 14 · hooks 27 · test files 664 · sessions 289 · learnings 201 · npm downloads (30d) 1165 · GitHub stars 50
<!-- census:end -->

Generated by `node scripts/site-numbers.mjs --write`; the machine-readable receipt is site/_census.json. Facts outside the census, measured 2026-09-06 at bc49301b: 18 ADRs, 45 modules under scripts/lib/validate/ (`find scripts/lib/validate -name '*.mjs' ! -name '*.test.mjs' | wc -l`), 14 destructive-command rules (10 blocking, 4 warning), 26 always-on rule files, 26 of the hook files plugin-wired across 10 event types, and 13,529 top-level it()/test() call sites (`rg -c '^\s*(it|test)\(' tests --glob '*.test.mjs'` summed per file; the runtime total is higher because of parameterised blocks that expand at run time). The v4.0.0 release REMOVES public surfaces, so counts from the preceding 3.24 line (49 skills / 28 commands / 16 agents / 61 rules) are stale by construction.

## Install

- Claude Code: /plugin marketplace add Kanevry/session-orchestrator then /plugin install session-orchestrator@kanevry - afterwards run npm install once inside the plugin directory (hooks import zx) and restart Claude Code.
- Codex CLI: git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs
- Cursor IDE: same clone, then node scripts/cursor-install.mjs /path/to/your/project
- Pi: pi install npm:session-orchestrator

Portable cross-harness surface: a root AGENTS.md generated byte-identical from CLAUDE.md, a root plugin.json following the agent-plugins.org 1.0.0 schema, and a .agents/skills/<name>/SKILL.md mirror of every skill carrying only spec-legal frontmatter plus a pointer body. All three are generated by scripts/generate-agents-skills.mjs and drift-checked in scripts/validate-plugin.mjs; none is hand-edited.

Upgrade: /plugin update session-orchestrator@kanevry then restart; on Codex CLI, Cursor and Pi it is git pull plus the same installer. Session-start compares the version of the code that is RUNNING against the published npm version and fails silent rather than claiming "up to date" from a failed lookup. Uninstall removes the plugin from the harness; .orchestrator/ (bootstrap.lock, metrics JSONL, policy, steering), STATE.md and the Session Config block stay in the user's repo as plain text.

Minimum config: a "## Session Config" section in CLAUDE.md (or AGENTS.md on Codex CLI) declaring test-command, typecheck-command, lint-command, agents-per-wave, waves, persistence, enforcement. Everything else is opt-in.

## Common questions

- Is this itself an AI that writes code? No. It is an add-on that organises how an AI coding tool works. The tool still writes the code; this decides what it reads first, what it may touch, and when it has to stop and be checked.
- Which tools does it work with? Claude Code fully. Codex CLI, Cursor IDE and Pi run it with limits: on Codex CLI the short list of files a step may touch is not enforced, on Cursor IDE it is checked after the work is done, and Pi runs through a bridge. The install section lists the path for each.
- What is different from just using Claude Code? Four things: the reading step before any change, a plan you agree to, a short list of files per step, and an automatic check between the steps. Without them the tool starts typing on the first sentence it reads.
- Does it send data anywhere? No account and no server. Everything runs on your own machine. Usage data is sent only if you switch it on, and it is off until you do. This website loads nothing from another site.
- Does it work on Windows? It runs natively on Windows, but Windows is not covered by the automated test runs. macOS and Linux are, so those two are the paths that get checked on every change.
- What does it cost? Nothing. It is free and open source under the MIT licence. You still pay whatever your coding tool costs; that part is not affected.
- Can it break my project? Commands that would delete or overwrite work are blocked by a policy file, not by a polite instruction. It never overwrites the shared history of your project. It records the changes at the end of a session, after the checks have run, and it tells you what it recorded.
- Who maintains it? One person, Bernhard Götzendorfer. Questions filed on GitHub are answered by him. It is shipped as-is, with best-effort maintenance and no service level agreement.

## Links

- Source, docs, issues: https://github.com/Kanevry/session-orchestrator
- npm: https://www.npmjs.com/package/session-orchestrator
- Methodology courses (optional, not required to use the plugin): https://agenticbuilders.at