Open source for your coding sessions
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.
Plan the work. Run it in checked waves. Pick up where you left off. 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 on Claude Code, Codex, Cursor and Pi.
Free · MIT licensed · No plugin account
Plan / Go / Close
One session.
A thread you can follow.
A shared plan, separate responsibilities and a handover that makes the next session easier to start.
“Add a CSV export to the dashboard.”
Illustrative workflow, not a live report- 01
Plan
Understand the work before splitting it.
Read the code, open issues and existing tests. Agree the goal before anyone changes files.
Read export codeCheck data accessReview the testsBring it together: One plan for the export button, CSV format and download. Assign the write scopes before work starts.
- 02
Go
Work independently. Check the result together.
InterfaceBuild the button and its empty state.
DataBuild the CSV output and handle special characters.
Verify: Combine the changes. Test the download, format and error cases. Fix findings, then check again.
Claude Code and Codex can run independent tasks in parallel. Cursor and Pi work through them sequentially.
- 03
Close
Record what is done. Keep the open work visible.
Done CSV export implemented and the agreed cases checked.
Still open Selectable columns recorded as a follow-up task.
The changes, verification evidence and next steps give the next session somewhere to begin.
Size the workflow to the job.
Housekeeping uses one wave, a feature three, deep five, the ultradeep profile seven. Waves organise the work; a small change does not need to become a large project.
Run your first sessionWhat you get
Less babysitting.
More finished work.
Each part closes one gap that shows up when agents work alone. First what it does for you, then how it works. Everything runs on your machine and writes plain text into your repository.
- Start right
Know what to work on.
Every session starts from the real state of your project, not from a prompt you write again each time.
/sessionreads git, open issues, recent commits and the last session record, recommends one scope and waits for your correction./plan,/brainstormand/grillhelp while an idea is still vague. - Catch mistakes early
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 of it.
/gochecks each wave with your tests and typecheck and turns failures into fix tasks; lint and the full suite run before the commit./closechecks every planned item against what happened./debugfinds the root cause before anyone patches. - Stay in scope
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, and overlaps are rejected before work starts. A guard blocks 12 destructive command patterns, such as hard resets,
rm -rf, force-push andDROP TABLE, and warns on 4 more. Real hooks on Claude Code, bridges on Cursor and Pi, instructions only on Codex. - Keep the thread
Pick up where you stopped.
A crash, a closed laptop or a second session in the same folder does not cost you the work.
STATE.mdrecords every finished wave, so the next/sessionoffers to resume. A heartbeat lock keeps two sessions from colliding in one checkout./closefiles what is left as issues on GitLab or GitHub. - Learn as you go
It improves with your sessions.
Patterns from your own sessions become rules your agents follow next time, once you approve them.
Every session appends a record.
/evolveproposes learnings with a confidence score, and/reconciledrafts rules from them. You read each one and delete what you disagree with. Optional: mirror sessions and learnings into a Markdown notes vault. - Look further
Audit, test and review on demand.
The same workflow can find problems you did not ask about, and show that the app works.
A discovery scan at
/closeturns findings you confirm into issues./testdrives web and macOS flows end to end,/ux-grillchecks a running web app for accessibility and layout faults, and/test-auditremoves tests that catch nothing./repo-auditand/harness-auditscore a repository against a checklist, and/persona-panelhas several reviewer personas read the same output in parallel.
For longer runs: /autopilot chains whole 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. Every command is listed in the component reference.
What happens between /session and /close
- ReadGit, issues, recent commits and earlier sessions become one overview with a recommendation.
- AgreeNothing changes in your code until you accept or correct the scope.
- SplitThe work becomes waves: 1 for housekeeping, 3 for a feature, 5 for deep work, 7 for the ultradeep profile. Each wave gets a goal and the files it may write.
- Run and checkAgents with separate files work in parallel on Claude Code and Codex. 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.
- CloseThe plan is compared with the result, the changes are committed, and unfinished work becomes issues.
Made by Bernhard Götzendorfer
It started with
a Notion page.
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.
More about BernhardInstall
Your tool.
Your next session.
Choose your installation path. You need Node.js 24 or later and a Git repository. The plugin is free; your coding tool has its own costs.
Claude Code
/plugin marketplace add Kanevry/session-orchestrator
/plugin install session-orchestrator@kanevry
Current Claude Code installs the Node dependencies with the plugin. To check once, or if yours did not, run the command below in a shell: it runs npm install only when the dependencies are missing. Restart Claude Code if it did.
claude plugin list --json
Find the enabled session-orchestrator@kanevry entry. Replace the placeholder below with its installPath. If the entry is missing or disabled, resolve that through /plugin first. If several entries match, check the active installation instead of guessing.
cd "/absolute/installPath/from/the/list" && { [ -d node_modules/js-yaml ] && echo "dependencies present, nothing to do" || npm install; }
Codex CLI
git clone https://github.com/Kanevry/session-orchestrator.git
cd session-orchestrator && npm install
node scripts/codex-install.mjs
Requires Codex CLI 0.144.4 or later. Config goes in AGENTS.md. After installation, open a fresh task and review the plugin hooks through /hooks.
Select the Session Orchestrator skills: $session-orchestrator:bootstrap, then $session-orchestrator:session feature, $session-orchestrator:go, and $session-orchestrator:close. See the first-session guide.
Both guards are instructions only on Codex. The plugin does not enforce the destructive-command or file-scope guard here. The workflows and quality checks still run.
Cursor IDE
git clone https://github.com/Kanevry/session-orchestrator.git
cd session-orchestrator && npm install
node scripts/cursor-install.mjs /absolute/path/to/your/project
Target project. Pass the target project explicitly. Without a path, the installer uses the current directory.
Pi
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi install npm:session-orchestrator
This path installs its own dependencies; the Codex CLI and Cursor clones need npm install once.
Setting up for the first time? The guide covers installation and bootstrap.
Under the hood
Follow the rules.
Right down to the code.
See which checks run, what they cover and where their limits are. With the source files to inspect.
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.
| 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 applies 12 blocking rules and 4 warning rules. Cursor and Pi use bridges; Codex treats these rules as instructions. | .orchestrator/policy/blocked-commands.json, 16 rules |
| 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.
- macOS and Linux are covered by CI. Native Windows use is untested; 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.
| 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 and file-scope rules are instructions only; neither guard blocks operations |
Repository numbers and their receipt
v5.12.0
current release
51
skills
30
slash commands
14
typed sub-agents
29
hook files
749
test files
481
session records in this repo
115
learnings in this repo
3576
npm downloads, last 30 days
53
GitHub stars
Counted on 2026-10-11 at commit c588e6d8. Repository records describe development activity, not active users. npm downloads include automated requests. See the count receipt.
A few practical questions
Questions people ask
Is this itself an AI that writes code?
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, but its destructive-command and file-scope rules are instructions only; the plugin does not enforce either guard there. Parallel agents are available on Claude Code and Codex; Cursor and Pi run tasks sequentially.
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?
macOS and Linux are covered by CI. Native Windows use has not been tested. 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. 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?
It can still make mistakes. On Claude Code, an active destructive-command hook applies 12 blocking rules and 4 warning rules. Cursor and Pi use bridges with documented limits. Codex does not enforce this guard or 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?
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.
For your next project
Start with
a clear session.
Install the plugin and let it read your repository. Then decide what comes next.