session-orchestrator
Advanced tools
Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementati
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
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.
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.
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. /evolve proposes learnings with a confidence score, /reconcile drafts rules from them; you approve or delete each one. Optional mirror into a Markdown notes vault. |
| Audit, test and review on demand. Find problems you did not ask about, and show the app works. | A discovery scan at /close turns confirmed findings into issues. /test drives web and macOS flows end to end, /ux-grill audits a running web app, /test-audit removes tests that catch nothing. /repo-audit and /harness-audit score a repository against a checklist, and /persona-panel has several reviewer personas read the same output in parallel. |
| Longer runs, more repositories. | /autopilot chains sessions and stops on any of 10 kill-switches. /dispatcher recommends the next free repository and claims it once you confirm, and /portfolio summarises issues, MRs and CI across the repositories registered in your notes vault. |
When you type /session feature:
/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 implementation wave your tests and typecheck run, and failures become fix tasks for the next wave. The full test, typecheck and lint gate runs after the Quality wave./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, 30 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 (28 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.
/close has already been copied into every wave after it. Findings below the configured confidence threshold are not shown to you.STATE.md records which wave finished and what deviated from the plan. The next /session offers to continue from the last completed wave.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.docs/components.md./evolve analyze proposes patterns with a confidence score; you read them and delete the ones you disagree with. Nothing is applied without you.How this compares to other orchestrators, with measured results kept separate from unmeasured claims: docs/components.md § Comparisons.
| Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
|---|---|---|---|---|
| All 30 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.
Highlights of the v5.10.0 line:
Full changes and upgrade notes: CHANGELOG.md.
session-orchestrator makes one session reliable. When several sessions run in parallel across repositories, a lead session can coordinate them: who runs next, what each may do, one queue for your decisions, one stop for everything. That is the sibling project lead-session-orchestrator (GitHub, npm lead-session-orchestrator). Each works alone; together they use the shared fleet contract in skills/_shared/fleet-protocol.md.
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.
MIT · Privacy policy · npm
FAQs
Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementati
The npm package session-orchestrator receives a total of 777 weekly downloads. As such, session-orchestrator popularity was classified as not popular.
We found that session-orchestrator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
arXiv now limits authors to two submissions a month as AI slop overwhelms moderators, delays good papers, and sparks debate over applying the limit to everyone.
Research
/Security News
A new GhostAction wave hits hundreds of GitHub repos, expanding CI/CD secret theft to cloud and AI credentials in source code and git history.
Research
/Security News
Tensorlake npm SDK version 0.5.144 was compromised in a ChainDrop / Shai-Hulud attack, delivering credential-stealing malware.