session-orchestrator

Session Orchestrator

Give your agents a working rhythm.

You type three commands:

• /session reads your repository, your open issues and the last session, proposes what to work on, and waits for your correction.
• /go runs the agreed work in waves of parallel agents and runs your test, typecheck and lint commands between each wave. Work that fails a check goes back to be fixed before the next wave starts.
• /close checks every planned item against what actually happened, commits, and files the rest as issues for next time.

Session Orchestrator is a free, MIT-licensed workflow plugin for Claude Code, Codex CLI, Cursor IDE, or Pi. It runs on your machine and writes plain text into your repository. No account, no server, nothing to sign up for.

flowchart LR
    S["/session"] --> G["/go"]
    G --> Q{"quality gate"}
    Q -- "fails" --> G
    Q -- "passes" --> C["/close"]

Longer explanation, with examples and screenshots: session-orchestrator.com (auf Deutsch).

User guide · Install & upgrade · Changelog

Install

You need Node.js 24 or later, a git repository, and one of the four agents below. Full requirements, upgrade path and uninstall: docs/install.md.

Platform	Install
Claude Code	/plugin marketplace add Kanevry/session-orchestrator then /plugin install session-orchestrator@kanevry, then install its Node dependencies once.
Codex CLI	git clone the repo, npm install, then node scripts/codex-install.mjs (guide).
Cursor IDE	git clone the repo, npm install, then node scripts/cursor-install.mjs /path/to/your/project (guide).
Pi	pi install npm:session-orchestrator (guide).

After a clone-based install (Codex CLI, Cursor IDE, or contributing), run npx husky once: .npmrc sets ignore-scripts=true (SEC-020), which skips the prepare script that would otherwise activate the git hooks.

Quick Start

1. Run /bootstrap once in your project. It creates the minimum structure and writes .orchestrator/bootstrap.lock. /session refuses to start until that file exists.

2. Add a Session Config to your project's instruction file — CLAUDE.md on Claude Code and Cursor, AGENTS.md on Codex CLI and Pi (which file each platform reads). These seven fields are enough:

## 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

The first three are the commands /go runs between waves and /close runs at the end — use whatever your project actually uses. Everything else is opt-in: full template · every key, its type and default.

3. Run the loop.

/session feature    # read the repo, propose scope, wait for your correction
/go                 # execute in waves, check between each
/close              # verify, commit, file the rest as issues

On Codex the same three are $session-orchestrator:session feature, $session-orchestrator:go, $session-orchestrator:close (Codex usage). /plan and /evolve extend the loop; you can start with just these three.

In headless Claude Code (claude -p), /session and /plan are reserved terminal-only built-in names and the bare form is refused; use /session-orchestrator:session and /session-orchestrator:plan there. Every other command keeps its bare form.

How it works

When you type /session feature:

• It reads the project. Git state, open issues, recent commits, documentation, host resources and the records of previous sessions become a Session Overview with one recommendation.
• You correct the scope. Nothing is implemented until you agree to the plan.
• The work is split into waves. The session type decides how many: housekeeping 1, feature 3, deep 5, the ultradeep profile 7. Each wave gets a purpose, a list of file paths it may write to, and a result that can be checked.
• /go runs it. Agents whose file scopes do not overlap run at the same time on Claude Code and Codex; Cursor and Pi run them one after another. After each wave the quality gate runs, and anything it reports goes back for correction before the next wave starts.
• /close checks and records. It compares the plan against what happened, runs the full quality gate, commits file by file, and opens issues for whatever was not finished.

What it writes into your repository, and nothing else — all of it plain text, all of it local:

.orchestrator/bootstrap.lock        # written by /bootstrap, the gate for every later run
.orchestrator/current-session.json  # which session owns this working copy right now
.orchestrator/session.lock          # heartbeat lock; stops two sessions colliding in one checkout
.orchestrator/host.json             # host-local identity for peer-session detection
.orchestrator/metrics/*.jsonl       # append-only session, learning, event and subagent records
.orchestrator/steering/             # stable product/tech/structure context injected each session
.claude/STATE.md                    # wave progress and deviations (harness-specific directory)

The plugin is 51 skills, 27 slash commands, 14 typed subagents and 29 hook files across 10 event types. A slash command is a skill whose frontmatter says user-invocable: true (25 of them) or one of the two remaining commands/*.md files (/session, /templates-ack) — one definition per name, so nothing is listed twice in the / picker. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in scripts/lib/*.mjs and hooks/*.mjs. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: docs/components.md.

Why it is built this way

• The wave order is deliberate. Discovery runs first so every implementer starts from the same picture of the code. Impl-Core runs before Impl-Polish so the structure exists before anything integrates against it. The Quality wave simplifies generated code before tests are written — write the tests first and they assert whatever the model produced, so changing it later means rewriting the tests too.
• Checks run between waves, not only at the end. A mistake caught after wave 2 costs one wave. The same mistake found at /close has already been copied into every wave after it. Findings below the configured confidence threshold are not shown to you.
• A crash does not lose the session. STATE.md records which wave finished and what deviated from the plan. The next /session offers to continue from the last completed wave.
• Two sessions in one working copy is treated as a real risk. Two people, or two of your own sessions, in the same checkout share one git index, one filesystem and one STATE.md, and neither can see the other's uncommitted work. A heartbeat session lock, per-agent file-scope manifests, and the PSA rules in .claude/rules/parallel-sessions.md exist for exactly that case.
• Guards run where the harness supports them, and the table below says where it does not. A destructive-command policy — 12 rules block, 4 warn — and file-scope enforcement run as real hooks on Claude Code, as bridges on Cursor and Pi, and as instructions only on Codex. Details: docs/components.md.
• What it learns is opt-in and readable. Every session appends a record. After 5 or more sessions, /evolve analyze proposes patterns with a confidence score; you read them and delete the ones you disagree with. Nothing is applied without you.
• GitLab and GitHub, both fully. It detects which one your remote points at and drives issues and merge/pull requests for either.

How this compares to other orchestrators, with measured results kept separate from unmeasured claims: docs/components.md § Comparisons.

Platform support

Feature	Claude Code	Codex CLI	Cursor IDE	Pi
All 27 commands	Native slash commands	Generated skills ($session-orchestrator:<name>)	Native .cursor/commands slash commands	Prompt templates
Parallel agents	Agent tool	Multi-agent roles	Sequential only	Sequential (parallel planned)
Session persistence	.claude/STATE.md	.codex/STATE.md	.cursor/STATE.md	.pi/STATE.md
Scope enforcement	Active PreToolUse hook; blocking in strict, reporting in warn	Instructions only; no compatible apply_patch handler	preToolUse + beforeShellExecution bridge; scope blocking requires strict; afterFileEdit is post-hoc	tool_call bridge; scope blocking requires strict
Destructive-command guard	Active PreToolUse hook applies policy severity	Instructions only; no handler wired	beforeShellExecution bridge for supported commands	tool_call bridge for supported commands
AskUserQuestion	Native tool	Numbered-list fallback	Numbered-list fallback	Numbered-list fallback
Quality gates	Full	Full	Full	Full

All four platforms share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex leaves its PreToolUse handlers empty because these guards do not yet match its tool names and edit payloads (why). Cursor and Pi have known event-coverage limits — see docs/cursor-setup.md and docs/pi-setup.md.

Recent highlights (v5.5.0)

Highlights of the v5.5.0 line:

• Scope guards hold in worktrees, subdirectory launches and beside peer sessions. The guards read the session's own working copy, find this session's own wave-scope.json even when a peer session's manifest ranks higher, and the wave readers, staging fence and orphan reaper follow the same session root. blockedCommands carries only command patterns, so redirects inside bash -c payloads are no longer denied (#1492, #1493, #1504, #1509).
• Session locks are taken over by exactly one session. A stale or corrupt lock is reclaimed through a tombstone, a future-stamped lock or registry entry never counts as young, and leftovers of a killed reclaim are swept (#1494, #1505).
• vault-mirror never overwrites a note it does not own. The namespace follows the mirrored ledger, a note of another project or generator is skipped, and the vault writers honour the vault-integration off switch (#1496, #1503, #1506).
• The learnings store keeps every line. Unparseable lines survive each rewrite, sweep-expired-learnings --drop-malformed removes one on purpose, and a prune snapshots first and refuses on drift (#1486, #1489, #1500).
• Conventional commits on every path to main. CI lints each commit range and the squash title, and accepts merge or revert headers only from real merges and reverts (#1477, #1502, #1507).
• npm run update:local updates every local install, and Claude Code installs the plugin's dependencies again (the overrides block it refused is gone). The /session-orchestrator:navigator skill left the package; the fleet file contract stays (#1491).

Full changes and verification: CHANGELOG.md.

Documentation

• User guide — config reference, a walkthrough of one session, troubleshooting, FAQ
• Install, upgrade, uninstall — requirements, per-harness setup, migration paths
• Components & reference — every skill, command, agent and hook; the guards; comparisons
• Telemetry — what stays on your machine, what the optional anonymous telemetry would send, and every switch that turns it off
• Contributing · Plugin architecture · docs/ router

Scope and support

Provided as-is: a community project, best-effort maintenance, no SLA. Questions and ideas go to Discussions, bugs to Issues.

It is not an official product of any agent vendor — independent and community-maintained, not affiliated with, endorsed by or sponsored by Anthropic, OpenAI, Cursor or any agent it integrates with, and distributed through the Claude Code plugin marketplace without being an Anthropic product. It does not replace your agent; it runs on top of one, and you still need it installed. It is built for one operator: the parallel-session machinery protects your own concurrent sessions, not a shared team workspace.

The reasoning behind the method is taught at agenticbuilders.at. The plugin is free and MIT; the courses go deeper and are not required to use it.

License

MIT · Privacy policy · npm