01 / work enters
Plugin for Claude Code, Codex CLI, Cursor and Pi
Most coding agents start writing before they know what changed.
Session Orchestrator puts a loop in front: research the repo, agree the scope, then five typed passes with a verification gate between each. Open source, one line to install.
$ /session feature
lock acquired · main-2026-08-19-1
git 14 commits · 3 dirty files
issues 7 open · 918 premise verified: GAP
ci pipeline 7204 green on d2de3ca
not-to-retry 1 approach force-read
recommend feature · 5 waves · 6 agents · confidence 0.82
$ /go
W1 Discovery 3 agents · read-only
W2 Impl-Core 6 agents · 12 files · gate pass
W3 Impl-Polish 4 agents · 5 files · gate pass
W4 Quality 5 agents · 8 files · FULL GATE pass
W5 Finalization 1 agent · 2 files · gate pass
$ /close
verified 11 of 12 planned items
carryover 1 item -> issue #1043
committed 19 files · pushedAbove: one whole session. The tool reads the repository first, says out loud what it thinks it should touch, then works through it in five passes, and finishes by reporting what got done and what did not. The lines that begin with a dollar sign are the three things a person types.
02 / the boundary
You cannot make a language model careful by asking it to be careful. You can take the ability away.
An agent that is never handed the git index cannot break commit discipline — not because it behaved, but because there was nothing there to break. Everything below is that one move, applied five times.
03 / install
Pick your harness
Same plugin, four install paths.
Claude Code
plugin marketplace
/plugin marketplace add Kanevry/session-orchestrator
/plugin install session-orchestrator@kanevryThen run npm install once inside the plugin cache and restart Claude Code.
claude plugin dir is not a subcommand Claude Code has, so it exits 1 and the fallback path it then used does not exist. The replacement below resolves the path from the plugin cache instead, and was run end to end on a real install:
cd "$(dirname "$(find ~/.claude/plugins/cache -name package.json -path '*session-orchestrator*' | head -1)")" && npm installCodex CLI
clone + installer
git clone https://github.com/Kanevry/session-orchestrator.git
cd session-orchestrator && npm install
node scripts/codex-install.mjsReads AGENTS.md instead of CLAUDE.md.
Cursor IDE
clone + installer
git clone https://github.com/Kanevry/session-orchestrator.git
cd session-orchestrator && npm install
node scripts/cursor-install.mjs /absolute/path/to/your/projectPi
package manager
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi install npm:session-orchestratorThe only path that resolves dependencies on its own.
04 / five passes
Five passes, one gate between each
Write access is declared per wave. The Quality gate cannot be skipped.
- the work, in flight
- a gate holding the work back — open bracket, cross
- a gate that came back clean — closed box, check
Fig. 1wave loop — elevation of one session
W1Discovery
0 files
G1
Gate 1, cleared: findings validated
W2Impl-Core
12 files
G2
Gate 2, cleared: incremental gate
W3Impl-Polish
5 files
G3
Gate 3, cleared: incremental gate
W4Quality
8 files
G4
Gate 4, cleared: Full gate
un-skippable
W5Finalization
2 files
G5
Gate 5, cleared: final review
Discovery has no height because it may write nothing. A pass with an empty write scope is not a box of height zero — it is a line on the baseline. Every other pass is exactly as tall as the number of files it was allowed to open, and no pass can grow taller than the scope it declared before it started.
Scale — one unit of height equals one file in the declared write scope of that pass. Same five rows as text in the schedule below.
The file scope is not a request — the union is computed and asserted disjoint before any agent starts.
Five passes over the work — each with a different job — and between each one an automatic check that has to come back clean before the next pass is allowed to start.
05 / schedule
The same five rows, as text
| Pass | Who runs it | May write | Files | Gate after |
|---|---|---|---|---|
| W1 Discovery | read-only explorers | nothing | 0 | cleared: findings validated |
| W2 Impl-Core | code, db, ui implementers | core feature code | 12 | cleared: incremental gate |
| W3 Impl-Polish | fix + integration agents | bug fixes, edges | 5 | cleared: incremental gate |
| W4 Quality | simplifiers, test-writer, read-only panel | tests only | 8 | cleared: full gate, un-skippable |
| W5 Finalization | 1 to 2 agents | SSOT, issue cleanup | 2 | cleared: final review |
File counts are the declared write scopes of the session in the tape above, not a fixed quota. A wave declares its scope before it runs; the numbers change per session, the rule does not.
06 / enforcement
Every claim names the file that enforces it
A sentence in a prompt is a wish. These five are code paths.
The write scope of an agent is fixed before it starts.
scripts/validate-wave-scope.mjs --assert-disjoint
A write outside that scope is refused, not warned about.
hooks/enforce-scope.mjs
Destructive shell commands are blocked by policy, not by prompt.
.orchestrator/policy/blocked-commands.json — 14 rules
A subagent can never touch the git index.
.claude/rules/parallel-sessions.md — PSA-007
Every planned item is checked against evidence at close.
skills/session-end/SKILL.md
07 / after the session
What survives the session
Nothing is learned silently. Every write is confirmed by the operator, every artifact is plain text.
The record
Learnings carry a confidence score and an expiry: 0.5 at the start, +0.15 on confirmation, −0.2 on contradiction.
.orchestrator/metrics/Rules are proposed, never applied
Reconcile writes a proposal, the operator approves it. A rule that switches itself on is structurally impossible.
skills/reconcile/SKILL.mdWhat Not To Retry
A failed approach is force-read at the next session start, so a dead end is not walked into twice.
.orchestrator/metrics/Across repositories
/portfolio reads issues, merge requests and stale signals across every registered repo. Read-only.
Which repo next
/dispatcher ranks the free repos on backlog, staleness and readiness, then claims the lease atomically.
A session that crashed
Shows up as force-closed from any other repository's session start, instead of holding a lock nobody can see.
08 / readings
Measured in this repository
v3.23.0
current release
48
skills
28
slash commands
15
typed sub-agents
26
hook files
622
test files
281
sessions in this repo
169
learnings in this repo
Counted on 2026-08-28 at commit 4b60f3c. These are this repository's own records, not a fleet total.
09 / limits
What this is, and what it is not
- 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. No account, no server. Telemetry is strictly opt-in.
- macOS and Linux are first-class and covered by CI. Windows runs natively but is not CI-covered.
- The eval standard refuses a global score, abstains with cannot-determine when a measurement is missing, and forbids superlatives. A leaderboard published before the comparison method is honest would be the exact failure the spec exists to prevent, so there is not one yet.
- Hook-level enforcement is not the same on every harness. The list below is the current state, not a roadmap. The quality gates are identical everywhere.
- Claude Code — full
- Cursor IDE — post-hoc
- Pi — bridged
- Codex CLI — scope enforcement currently unavailable
10 / work leaves
One line, then a session that reads first
MIT, no account, and the first thing it does is tell you what it found before it touches anything.