Session Orchestrator

Give your agents a working rhythm.

Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. On their own, coding agents drift from the plan, overwrite each other's files and call work done before it is checked; Session Orchestrator closes those gaps.

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. After each implementation wave your tests and typecheck run, and failures become fix tasks for the next wave. The full test, typecheck and lint gate runs before /close commits.
• /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 the quality gate runs: tests and typecheck after each implementation wave, all three after the Quality wave and before /close commits — 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.

What you get

Each item: what it does for you, then how it works.

You get	How
Know what to work on. Every session starts from the real state of your project, not from a prompt you rewrite.	/session reads git, open issues, recent commits and the last session record, recommends one scope and waits for your correction. /plan, /brainstorm and /grill help while an idea is still vague.
Errors stop at the next check. A broken test is found right after the work that caused it, not after more work is built on top.	/go checks each wave with your tests and typecheck and turns failures into fix tasks; lint and the full suite run before the commit. /close checks every planned item against what happened. /debug looks for the root cause before a fix.
Agents keep to their files. Parallel agents do not overwrite each other, and destructive commands do not slip through.	Each agent gets a declared list of files it may change; overlapping lists are rejected before dispatch. A guard blocks 12 destructive command patterns (hard reset, rm -rf, force-push, DROP TABLE, …) and warns on 4. Hooks on Claude Code, bridges on Cursor and Pi, instructions only on Codex.
Pick up where you stopped. A crash or a second session in the same folder does not cost you the work.	STATE.md (a progress file in your repo) records each finished wave, and the next /session offers to resume. A session lock with a heartbeat keeps two sessions apart in one checkout. /close files what is left as GitLab or GitHub issues.
It improves with your sessions. Patterns from your own work become rules, once you approve them.	Every session appends a record. `/evolv