Current Claude Code installs the Node dependencies itself. Only if a command fails, use the dependency check.
Set up once Chat in your coding tool
/bootstrap --fast --no-interview
No questions, sensible defaults. If you want to choose the settings yourself, run /bootstrap and answer the interview.
Your first session Chat in your coding tool
/session feature add a CSV export
Then /go, then /close.
What the three commands do
/session
reads your repository and proposes what to work on; nothing changes until you agree
/go
does the agreed work in rounds (waves) and checks each round with your tests
/close
runs the full check, commits, and writes down what is left as issues
What success looks like
You see a short report and a proposed plan. Nothing in your code has changed yet. You answer with /go or correct the plan.
After /close you see what was done, what was checked and which issues were opened for the rest.
Last documented install run: 2026-10-28, plugin 5.14.0, Claude Code 2.1.312 on macOS (Node 24.22.1), from the public GitHub mirror in an empty profile. marketplace add and install exit 0, 11 of 11 runtime dependencies resolve, and bootstrap --fast --no-interview wrote the Session Config block. A feature session (model gpt-6-sol on an Anthropic-compatible endpoint) ended at a plan offering /go after one or two answered questions (scope, CI), with no project file changed. In 2 of 5 runs a model-chosen command printed the session's own messaging token, which the plugin's secret detector flagged (#1873). Re-run 2026-10-29 on plugin 5.16.0: install and readiness passed (11 of 11), bootstrap and session not measurable because the model endpoint answered 429.
Codex CLI
Everything works here, with one difference: the file list is an instruction. Codex edits files through apply_patch, which the file-scope guard does not read. The destructive-command guard blocks.
You need Terminal
Node.js 24 or later, a Git repository and Codex CLI 0.160 or later (check with codex --version).
cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs
Keep the clone in ~/Projects/session-orchestrator. To update later, run git pull && npm install && node scripts/codex-install.mjs there, then start a fresh task.
What the installer changes:
For your user, in every project: a packed copy of the plugin in ~/.cache/session-orchestrator/plugin-package/, added to Codex as session-orchestrator@kanevry. Codex copies it into its plugin cache under ~/.codex/plugins/cache/.
Removed: an older session-orchestrator@local or session-orchestrator@openai-curated install, if you have one.
Not touched: your projects, and the approval of the hooks.
Approve the hooks Chat in your coding tool
Start a fresh Codex task, or restart Codex. Type /hooks, read the Session Orchestrator hooks and approve them. The installer never does this for you.
Until you approve them, the hooks do not run, so no Session Orchestrator guard blocks a destructive command. If the hooks seem silent later, open /hooks again and check that they are approved.
Run it in the Codex chat inside your project. It writes .orchestrator/ and a ## Session Config block in AGENTS.md. It may still ask for the setup tier and the project type; then answer those two questions. To choose every setting yourself, run $session-orchestrator:bootstrap and answer the interview.
Your first session Chat in your coding tool
$session-orchestrator:session feature add a CSV export
Then $session-orchestrator:go, then $session-orchestrator:close. These are skill picks in the Codex chat. Plain /go and /close do not work in Codex.
What success looks like
You see a short report and a proposed plan. Nothing in your code has changed yet. You answer with $session-orchestrator:go or correct the plan.
After $session-orchestrator:close you see what was done, what was checked and which issues were opened for the rest.
Last documented install run: 2026-10-28, plugin 5.14.0, Codex CLI 0.160.1 on macOS (Node 24.22.1), from the public GitHub mirror in an empty profile. The clone installer exits 0 with 11 of 11 runtime dependencies; the short marketplace form exits 0 but its new cache had 0 of 11 (measured six times) until the repair step brought it to 11 of 11. With model gpt-5.6-sol 3 of 4 runs (both paths) ended a feature session at a plan after two or three answered questions, with no project file changed; in 2 of the 4 runs bootstrap --fast --no-interview asked for the tier and archetype instead of completing. With gpt-6-sol the session wrote the file without a plan (3 of 3 runs), a model behaviour. Re-run 2026-10-29 on plugin 5.16.0: both installs and the repair (0 → 11 of 11) passed, both model sessions with gpt-6-sol failed, and after the first codex exec the short-form cache had lost its dependencies again (#1878).
Cursor IDE
The same workflow, but agents run one after another. The guards run through a bridge.
You need Terminal
Node.js 24 or later, a Git repository and Cursor IDE.
Give the absolute path of your project. Without it, the installer uses the current directory.
Set up once Chat in your coding tool
/bootstrap
Your first session Chat in your coding tool
/session feature add a CSV export
Then /go, then /close.
What success looks like
You see a short report and a proposed plan. Nothing in your code has changed yet. You answer with /go or correct the plan.
After /close you see what was done, what was checked and which issues were opened for the rest.
Last documented install run: 2026-10-26, cursor-agent 2026.10.22 on macOS. The project install wrote the rules, commands, skills and hooks. Not re-run on 2026-10-28: a model session needs a Cursor login, and the empty profile answers status with Not logged in.
Pi
The same slash commands, as prompt templates. Agents run one after another. The guards run through a bridge.
You see a short report and a proposed plan. Nothing in your code has changed yet. You answer with /go or correct the plan.
After /close you see what was done, what was checked and which issues were opened for the rest.
No documented install run for this version yet: Pi was not installed on the test host (checked 2026-10-28).
Which command when?
Pick the row that matches your situation.
Which command fits which situation
Your situation
Type
A new project idea
/plan new
A feature that is not clear yet
/plan feature
A feature that is clear
/session feature
A big or unclear change: look first, then build
/session deep
Tidy up and maintain
/session housekeeping
/plan new runs without extra setup; with plan-baseline-path set it uses your baseline's templates. On Codex, put $session-orchestrator: in front of the command name. Every command, by situation: /commands.
When you need more
Open only what you need.
Before you start: requirements and the instruction file
Windows is barely tested. macOS and Linux run the full tests in CI; Windows only a smoke test. The shell hooks and the optional MCP server need WSL or Git Bash. Some optional workflows (the plugin validator, some wave-scope snippets, the MCP server) also need jq.
Your settings live in the project’s instruction file: CLAUDE.md on Claude Code and Cursor, AGENTS.md on Codex CLI and Pi. The contents are the same.
Each tool keeps its own session state (STATE.md in .claude/, .codex/, .cursor/ or .pi/). Session records and lessons in .orchestrator/metrics/ are shared, and so are the issues. Switching tools keeps your history.
Configuration: the Session Config
Bootstrap writes this block for you. These seven fields are the minimum:
## 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 heading must read ## Session Config exactly. Pasting the block alone does not finish setup: bootstrap also writes .orchestrator/bootstrap.lock, so run bootstrap once.
enforcement takes strict (edits outside the file list are blocked), warn (they are reported) or off. Every key: configuration reference.
What the guards block, and where they stop
The destructive-command guard follows .orchestrator/policy/blocked-commands.json: 14 blocking and 4 warning rules. It blocks hard resets, discarding checkouts, forced cleaning, destructive removal, force-push, SQL DROP TABLE and deleting the session records. It warns on soft resets, stash and git push --force-with-lease.
Guard behaviour per coding tool
Tool
Dangerous commands
Edits outside the file list
Claude Code
blocked by a hook
blocked in strict
Codex CLI
blocked by a hook (Codex honours the deny)
an instruction only
Cursor IDE
through a bridge
blocked in strict
Pi
through a bridge
blocked in strict
A file list is not filesystem isolation. Several sessions can share one working copy, which is why a stash or a reset is guarded: it can take a neighbour’s work.
What to do when a command is blocked
Read the reason in the message first. Most blocks protect work you did not create.
If you really mean it, run the command yourself in your own terminal, or relax the guard from outside the agent’s reach: start the session with SO_HOOK_PROFILE=relaxed (or set hooks.profile: relaxed in your host-local owner.yaml), which only warns on cases the guard can prove recoverable. SO_DISABLED_HOOKS=pre-bash-destructive-guard turns the guard off. The old allow-destructive-ops: true line in the Session Config is ignored, because the agent could write it itself.
If a legitimate edit is blocked by the file list, check the plan and the other agents’ files before you add the path. enforcement: off turns off the file-scope and blocked-command checks, not the destructive-command guard.
When something goes wrong
A command fails right after installing on Claude Code. Check the dependencies once. In a terminal, run claude plugin list --json, take the installPath of the enabled session-orchestrator@kanevry entry, then:
Hooks cannot find Node. Hooks run in your coding tool’s environment, not your login shell. Set SO_NODE_BIN to the absolute path of your Node binary, or start the tool from a shell where node works.
Cursor files landed in the wrong project. Rerun the installer with the absolute project path.
The summary does not match what you saw. Compare it with the latest session record:
Look closer at total_agents: 0 after agents plainly worked, undefined anywhere, or -abandoned- in the id after a clean /close. Then check what actually changed on disk before you build on it. Still stuck: open an issue.
One task from start to finish: “Add a CSV export to the dashboard.” The task is an example; the commands and the steps are the real ones.
Once per repository, before the first session Type /bootstrap. It sets up your repository; add --fast --no-interview to skip its questions. After that, each task needs only the three commands below. On Codex you pick every command as a skill: $session-orchestrator:bootstrap, $session-orchestrator:session, $session-orchestrator:go, $session-orchestrator:close.
1Read
You type/session feature add a CSV export
It reads your code, open issues, recent commits and the last session, then recommends what to work on. Nothing has changed yet.
What you see next
Session Overview
Type: feature
Repo: shop-dashboard on branch main
Git: clean, 0 unpushed
VCS: 12 open issues (2 high), 1 open MR
Health: TypeScript 0 errors | Tests: passing | CI: green
Recommended Focus
Option A (recommended): #48 CSV export on its own. It is what you asked for, and the code it touches has tests.
Focus Which focus should this session have?
1.#48 CSV export (Recommended) One button, one export route, one test. Serves: orders as a spreadsheet; observable via the new export test.
2.#48 + #51 date filter Same export code, about twice the work. Serves: exports per month; observable via the filter test.
3.#57 slow order list High priority, needs its own session. Serves: no named outcome.
Recreated from a real /session overview, shortened; repository and numbers made up.
You pick an option or answer in your own words. Then it shows the plan. Nothing is built before you type /go.
2Plan
You type/go
Correct the plan by writing in the chat, or say yes by typing /go. Every agent gets its own list of files, and overlaps are rejected before work starts.
3Go
You donothing. Watch, or do something else.
The agents work in rounds: side by side on Claude Code and Codex, one after another on Cursor and Pi.
4Check
You donothing.
After each round your tests and typecheck run. A failing test becomes a fix task for the next round, so the error is caught in the round that made it.
5Close
You type/close
It runs the full check, compares the result with the plan, commits the work and turns what is left into issues. The next /session starts here.
The next session starts where the last one stopped · made with AI
Nothing gets lost.
A crash, a closed laptop or a long weekend does not cost you the work. STATE.md records every finished round, so the next /session offers to resume. What /close could not finish is waiting as an issue on GitLab or GitHub.
The session film
The same session as a 34-second film, with sound · made with AI
How it fits together
Your tool writes the code. This plugin keeps the work in order.
It is not another AI. It adds a fixed way of working to the coding tool you already use, and everything it keeps is plain text in your repository.
Swipe sideways to see the whole picture.
Schematic. The plugin runs inside your coding tool, on your machine.
In your repository: plain text you can read and delete. STATE.md for the running session, rules under .claude/rules/.
On GitLab or GitHub: one issue for each thing that is left, so it cannot be forgotten.
Nowhere else: no account and no server of its own. By default, besides your coding tool and your Git host, the plugin only asks npm for updates, and you can switch that off. Features you turn on yourself, such as usage data or remote hosts, make their own connections. Optional usage data stays off until you agree.
Your coding tool
Same workflow. Different strengths.
All four tools get the same commands, checks and memory. What differs: how strictly the guards block, and whether agents work side by side.
Bridge: on Cursor and Pi the guards run through a small adapter, for the commands those tools report. Strict mode: set enforcement: strict in your Session Config; with the default warn, an edit outside the file list is reported, not blocked.
My recommendation
Want every guard to block, and the lead Inbox? Use Claude Code. Prefer Codex? You get the same commands as skills, agents side by side and the command guard. Only the file list per agent is an instruction, not a block, because Codex edits files through apply_patch. Cursor or Pi? Everything works, one agent after another.
I kept 20–30 prompts there for different projects. Before each session I would find the right row, copy it, and explain how I wanted to work all over again.
That routine gradually became Plan, Go, Close. I now use it on my Mac M4 and the M5 at the office. Session Orchestrator is the tool that grew out of it.
Under the hood
What is enforced, and where it stops.
See which checks run, what they cover and where their limits are. With the source files to inspect.
332sessions have built Session Orchestrator with itself so far, counted from the maintainer’s session log (development activity, not users). Counted on 2026-11-14. See the receipt or all numbers.
Checks and their source files
Some protections run in code; others are instructions the agent must follow. Their strength depends on the tool and configuration.
Each check or workflow rule and its source
Claim
Source
The workflow declares each agent’s write scope before dispatch.
scripts/validate-wave-scope.mjs --assert-disjoint
With an active scope hook on Claude Code, Cursor or Pi, strict blocks supported out-of-scope edits, warn reports them, and off disables the check. Codex has no scope enforcement.
hooks/enforce-scope.mjs
With the destructive-command hook active, Claude Code and Codex apply 14 blocking rules and 4 warning rules. Cursor and Pi use bridges.
Subagents are instructed to leave staging and commits to the coordinator. This is a workflow rule.
.claude/rules/parallel-sessions.md, PSA-007
The close workflow requires evidence for every planned item.
skills/session-end/SKILL.md
Supported tools and limitations
Independent and community-maintained. Not affiliated with or endorsed by Anthropic, OpenAI, or Cursor.
Shipped as-is, with no service level agreement and best-effort maintenance.
Local by default, without its own account. Optional telemetry is off; the npm update check can be disabled separately.
Windows is barely tested. macOS and Linux run the full tests in CI; Windows only a smoke test. Shell hooks and the optional MCP server need WSL or Git Bash.
Hook-level enforcement is not the same on every harness. The list below is the current state, not a roadmap. The configured quality checks run on all four tools.
Hook-level enforcement per harness
Claude Code
direct guard hooks; scope blocking requires strict mode
Cursor IDE
bridge for supported tool and shell calls; scope blocking requires strict mode. Post-edit checks cannot prevent a write
Pi
tool-call bridge for supported calls; scope blocking requires strict mode
Codex CLI
destructive-command guard runs as a Bash hook and blocks; file-scope rules are instructions only, because edits go through apply_patch
Repository numbers and their receipt
v5.20.0
current release
53
skills
32
slash commands
14
typed sub-agents
33
hook files
876
test files
332
session records in this repo
44
learnings in this repo
3312
npm downloads, last 30 days
54
GitHub stars
Counted on 2026-11-14 at commit db5c8188. Repository records describe development activity, not active users. The session count includes only sessions that actually ran, not every line in the session log, so it is lower than on older versions of this page. npm downloads include automated requests. See the count receipt.
No. It adds a workflow for planning, working and checking results. Your coding tool writes the code. Technical enforcement depends on the tool and guard configuration.
Which tools does it work with?
Claude Code runs the guard hooks directly. Cursor and Pi use bridges with documented limits. Codex CLI offers selectable workflow skills and runs the destructive-command guard as a Bash hook that blocks; its file-scope rules are instructions only, because Codex edits files through apply_patch, which the scope guard does not read. Parallel agents are available on Claude Code and Codex; Cursor and Pi run tasks sequentially.
Can a team use it?
Yes. Each person installs the plugin in their own coding tool. The Session Config in CLAUDE.md and the session records under .orchestrator/ live in the repository and are committed, so the next person's session reads what the last one left. Commits land on the branch you are on; /close pushes that branch. It creates a new branch only when you accept a worktree offer or run /autopilot.
What happens to my existing CLAUDE.md?
/bootstrap never overwrites it. It only adds the sections it needs (## Session Config, ## Dispatcher Autonomy and a short rules section) when they are missing.
Does it work with Jira or Linear?
No. Issues are read and written on GitHub or GitLab only.
What is different from just using Claude Code?
It adds a repeatable session workflow: read the project, agree the scope, divide the work into steps with declared files, and check the results between steps. The session record carries progress and unfinished work into the next session.
Does it send data anywhere?
The plugin runs locally without its own account. Optional usage telemetry is off until you consent. By default, session-start checks the npm registry for updates. Successful results are cached for 24 hours per repository; a failed request or cache write may cause another request at the next session. SO_DISABLE_UPDATE_CHECK=1 or DO_NOT_TRACK=1 disables the check. Your coding tool and configured services still use their own network connections. This website uses cookieless Vercel Web Analytics, described in its privacy policy.
Does it work on Windows?
Windows is barely tested. macOS and Linux run the full tests in CI; Windows only a smoke test. The Node core uses portable paths, but the shell-based hooks and optional MCP server need WSL or Git Bash. Treat Windows support as best-effort.
What does it cost?
Nothing for the plugin. It is free and open source under the MIT licence. You still pay for your coding tool, and a session with several agents and rounds uses more of its quota or tokens than a single chat.
Can it break my project?
It can still make mistakes. On Claude Code and Codex, an active destructive-command hook applies 14 blocking rules and 4 warning rules. Cursor and Pi use bridges with documented limits. Codex does not enforce the file-scope guard. For supported edits with an active scope hook, strict blocks violations, warn reports them, and off disables the check. Review changes and keep backups; the checks do not guarantee correct code.
Who maintains it?
Me, Bernhard Götzendorfer. I answer questions on GitHub myself. It is shipped as-is, with best-effort maintenance and no service level agreement.