Session Orchestrator

Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.

The same skills and commands run across all four, with platform-adapted hooks and enforcement (see Platform support). Community plugin (MIT, community-maintained) for solo devs and small teams.

Install

Prerequisite: Node.js 24 or later (node --version). v3.x runs as ES modules and needs a real Node runtime. Install Node.js.

| Platform | Install | |---|---| | Claude Code | /plugin marketplace add Kanevry/session-orchestrator then /plugin install session-orchestrator@kanevry (run both inside Claude Code). Also listed on the official community catalog: /plugin install session-orchestrator@claude-community (that catalog can lag HEAD). | | Codex CLI | git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs | | Cursor IDE | git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project | | Pi | pi install npm:session-orchestrator — or dev-fallback: git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only |

For Claude Code, also install Node dependencies once (hooks import zx) and restart Claude Code:

# Claude Code has no `plugin dir` subcommand, so resolve the install path from the cache.
SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
cd "$SO_DIR" && npm install

If SO_DIR comes back empty, the plugin is not installed from a marketplace — check /plugin list inside Claude Code first.

Setup guides: Codex · Cursor IDE · Pi. Per-IDE notes on CLAUDE.md vs AGENTS.md: instruction-file-resolution.

What makes it different

• Verification gates — every wave ends at a typecheck/lint/test gate; a confidence-filtered session-reviewer catches regressions between waves, not only at the end.
• Wave orchestration — five typed roles (Discovery → Impl-Core → Impl-Polish → Quality → Finalization), parallel subagents inside each wave, not one big batch.
• Persistent memory & learnings — STATE.md survives crashes and resumes the next session; /evolve extracts confidence-scored patterns across sessions, nothing hidden.
• Multi-harness — the same skills and commands run on Claude Code, Codex CLI, Cursor IDE, and Pi, with platform-adapted hooks and enforcement.

A session in three commands

/session feature    # research + Q&A — inspect git, issues, history, then agree on scope
/go                 # execute in five typed waves (fixed roles), with a quality gate between each
/close              # verify every item, commit cleanly, file carryover issues for the rest

That is the whole loop. /plan and /evolve extend it (see Lifecycle), but you can start with just these three.

Quick Start

Run /bootstrap in your project repo first — it writes .orchestrator/bootstrap.lock, which session-start requires before /session will run.

Add a ## Session Config section to your project's CLAUDE.md (Claude Code and Cursor IDE) or AGENTS.md (Codex CLI and Pi) — see instruction-file-resolution for which file each platform reads. The smallest valid config is seven fields:

## 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

Everything else is opt-in. See docs/session-config-template.md for the full template and docs/session-config-reference.md for the canonical type and default reference.

What you get

• 48 skills for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, audits, and more
• 28 slash commands (/session, /go, /close, /discovery, /plan, /grill, /evolve, /autopilot, /dispatcher, /reconcile, /eval, /test, /debug, …)
• 15 typed subagents (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …)
• 10 hook event types enforcing scope, blocking destructive commands, gating templates-first, capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged on the other platforms (Platform support)
• 10,000+ vitest tests run on every commit (telemetry methodology)

Full component inventory: docs/components.md.

Lifecycle at a glance

flowchart TD
    A["/plan [feature|retro]"] -->|optional, defines WHAT| B["/session [type]"]
    B -->|research + Q&A| C["/go"]
    C -->|5 waves with quality gates| D["/close"]
    D -->|verifies + commits| E["/evolve [analyze]"]
    E -->|extracts cross-session learnings| B
    style C fill:#1f6feb,color:#fff
    style D fill:#238636,color:#fff

/plan is optional — you can create issues manually and jump straight to /session. /evolve runs deliberately after 5+ sessions, not automatically.

How it works

Most agentic-coding tools jump straight into writing code. Session Orchestrator adds a structured loop on top: research first, agree on scope, then execute in five typed waves with verification gates between them.

flowchart LR
    W1["1·Discovery<br/>read-only audit"] --> G1{Gate}
    G1 --> W2["2·Impl-Core<br/>primary code"]
    W2 --> G2{Gate}
    G2 --> W3["3·Impl-Polish<br/>integration, edges"]
    W3 --> G3{Gate}
    G3 --> W4["4·Quality<br/>simplify + tests"]
    W4 --> G4{Full Gate}
    G4 --> W5["5·Finalization<br/>commit + close"]
    style G4 fill:#d29922,color:#000

When you type /session feature:

1. Phase analysis runs in parallel — git state, open issues, recent commits, SSOT freshness, resource health, and prior-session memory are all inspected, then distilled into a structured Session Overview with a recommendation, not a wall of raw data.
2. You agree on scope — through a tool-rendered picker (Claude Code) or a numbered list (Codex / Cursor / Pi). The orchestrator has an opinion and tells you what it would do.
3. The plan is decomposed into five waves — Discovery (read-only), Impl-Core, Impl-Polish, Quality, Finalization. Each wave has a defined purpose and a deliverable; agent counts scale by session type.
4. /go executes — agents work in parallel within a wave. A session-reviewer audits the output between waves on eight dimensions; only findings at confidence ≥ 80 reach you.
5. /close ships it — every planned item is verified, quality gates run full, and unfinished work becomes carryover issues. Files are staged individually, so parallel sessions can't stomp each other.

Two complementary commands round out the loop: /plan runs before a session when you need a PRD or retrospective; /evolve runs occasionally to surface patterns across sessions and feed them back at the next start.

The system is markdown-driven config plus a thin Node runtime — skills, commands, and agents are Markdown with YAML frontmatter; scripts/lib/*.mjs and hooks/*.mjs handle dispatch, validation, and telemetry. Everything is plain text: if something goes wrong, you can read every file and see what happened.

Why this design

• Five typed waves, not one big batch. Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a simplification pass on AI-generated code before tests are written — otherwise tests pin the AI patterns into place.
• Inter-wave reviews, not just end-of-session. Catching regressions between waves — not only at the end — stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.
• State persists across crashes. STATE.md records wave progress and deviations; the next /session offers to resume from the last completed wave.
• Hooks enforce, not just warn. A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike (specifics in Safety). This hard enforcement is full on Claude Code; Cursor and Pi reach it through payload bridges; Codex is still pending a real apply_patch adapter (see Platform support).
• Cross-session learning is opt-in and inspectable. Every session writes a record; after 5+ sessions /evolve analyze extracts confidence-scored patterns you can read and prune. Nothing is hidden.
• VCS dual support, no lock-in. Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.

Recent highlights (v3.23.0)

Every release is additive and backward-compatible. Highlights of the v3.23.0 line: the first shaped by three external bug reports on the public mirror (Kanevry#64, #65, #66), all three reproduced, fixed and live-verified:

• Codex CLI mints UUIDv7 session ids; every reader accepted only v4 (#66 / #1091) — each SessionStart minted a fresh v4, so a resumed or compacted thread read its own lock as a foreign session. parseSessionId now accepts RFC 9562 versions 1–8 and the stop/end hooks apply the writer's rule, so one id owns the lock from start through release. The UUID_V4_RE alias is gone: zero importers, and a name that said v4 while matching v1–8.
• Every /close wrote 0 of 5 recommendation fields (#65 / #1036) — the documented Phase 3.7a call passed undefined where a repo root is required, and the fail-open catch hid it on every run. The snippet binds the root; the catch now names the cause. A second defect found while verifying the fix: backticks in a comment inside a node -e "…" string made bash execute undefined on each close.
• Codex copies a marketplace plugin and starts the MCP child with no plugin-root variable (#64) — measured: the copy lives under ~/.codex/plugins/cache/<marketplace>/session-orchestrator/<version>/, and from a non-git cwd the launcher resolved to /scripts/mcp-server.sh. .mcp.json and plugin-root.mjs gained a cache-scan tier with a name-matched package.json, and .mcp.json now mirrors the module's tier order under two drift tests. Existing installs need a reinstall — Codex snapshots .mcp.json at install time.
• Worktree-Auto-Promotion is a process boundary, not a live migration (#1069, ADR-0013) — the source session deregisters and releases its lock before the new worktree's session acquires (leaveSourceRoot()), which removes the phantom peer that stayed visible for up to 60 minutes. Because the new session's id never equals the worktree suffix, Phase 4a cleanup keys on a promotion marker written at creation time; the review panel found that key dead before any user did.
• The host registry contributed nothing to session numbering (#1066) — the census projected only raw UUIDs, which the n-increment discards. It now counts semantic_session_id, so two sessions on one host cannot mint the same label. The semantic id stays a best-effort label; ownership remains the raw id plus owner proof.
• The mode selector scored a field no record carries (#1071) — completion_rate sits under effectiveness in all 281 ledger records; the flat read was always undefined, so the high-completion bonus was unreachable and the fixtures pinned a shape production never writes. Fixed with a nested-first read and a divisor test for the 99 records that carry no rate at all.
• Semgrep regained two rules a path filter had dropped (#1129) — re-aimed at this repo's real trust boundary (hook stdin, child-process stdout), taint-mode; the first true positives were three unguarded JSON.parse calls on glab/gh output in the CI banner. A proposed spread-sink was refused with a measurement: object spread cannot pollute a prototype.

Previous line (v3.22.0): instruments that confidently measured the wrong quantity — the 99%-firing resource warning, the AUQ audit, and the lock-release identity split.

Full version history: CHANGELOG.md.

Comparison

| Capability | Session Orchestrator | Manual CLAUDE.md | Other orchestrators | |---|---|---|---| | Session lifecycle (start → plan → execute → close) | Full, automated | Manual | Partial | | Typed waves with quality gates | 5 roles, progressive verification | None | Batch execution | | Session persistence and crash recovery | STATE.md plus memory files | None | Partial | | Scope and command enforcement hooks | PreToolUse with strict / warn / off | None | None | | Circuit breaker and spiral detection | Per-agent, with recovery | None | Partial | | Cross-session learning | Confidence-scored learnings | None | None | | VCS integration (GitLab + GitHub) | Dual, auto-detected | Manual CLI | Usually GitHub only | | Session close with carryover | Verified, with issue creation | Manual | Partial |

The design goal is engineering quality: every wave exits verified, every unfinished issue gets a carryover ticket, every session closes with a clean commit. A detailed head-to-head vs. maestro-orchestrate is in docs/components.md.

Platform support

| Feature | Claude Code | Codex CLI | Cursor IDE | Pi | |---|---|---|---|---| | All 28 commands | Native slash commands | Native plugin commands | 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 | PreToolUse hooks | Unavailable — pending a real apply_patch adapter | preToolUse + beforeShellExecution via cursor-hook-bridge; afterFileEdit post-hoc | tool_call bridge | | AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback | | Quality gates | Full | Full | Full | Full |

All platforms share the same skills, commands, and scripts; hooks use platform-specific adapters and event subsets. Codex intentionally wires only its six supported project event slots and omits Claude-only events plus Edit/Write payload handlers until a real Codex apply_patch adapter exists, so scope enforcement is currently unavailable there. Platform detection and adaptation live in scripts/lib/platform.mjs. OS: macOS and Linux are first-class and run in CI (ubuntu-latest, macos-latest). Windows runs natively (all paths via path.join, tmp via os.tmpdir()) but is not covered by CI — treat it as best-effort and run smoke tests locally when changing OS-sensitive code. Cursor and Pi have known event-coverage caveats — see docs/cursor-setup.md and docs/pi-setup.md.

Troubleshooting

Codex plugin or hooks not loading. Start with codex plugin list --available --json. Confirm session-orchestrator@kanevry is installed, enabled, unique, and at the tracked manifest version; then start a fresh task and review /hooks. Remove only the two allowlisted legacy IDs through codex plugin remove, and resolve marketplace conflicts through the public marketplace remove/add lifecycle before reinstalling. Any other pre-public plugin/config/cache/hook-state residue is unsupported: do not modify private Codex files; file an issue with codex --version plus the public plugin and marketplace list output. The full decision tree is in docs/codex-setup.md.

"'node' not found on the hook PATH — plugin hooks are skipped." The harness executes hook commands via /bin/sh -c with its own PATH — that shell does not source ~/.zshrc/~/.bashrc, so Node installed via Homebrew (/opt/homebrew/bin), nvm, volta, or asdf can be invisible to hooks even though node works fine in your terminal. All hook commands route through hooks/run-node.sh, which resolves Node via $SO_NODE_BIN → PATH → well-known install dirs → nvm and degrades gracefully when nothing is found: hooks are skipped with one warning per 6 hours instead of a shell error on every tool call. Fixes, in order of preference: launch the harness from a shell where node resolves; export SO_NODE_BIN=/abs/path/to/node; or install Node 24+ to a standard location.

Safety

hooks/pre-bash-destructive-guard.mjs blocks destructive shell commands (git reset --hard, rm -rf, git push --force, and more) in the main session and in subagent waves. Policy lives in .orchestrator/policy/blocked-commands.json. Bypass per session only for intentional maintenance:

allow-destructive-ops: true

The rule source of truth is .claude/rules/parallel-sessions.md (PSA-003), vendored to consumer repos via /bootstrap.

Development

git clone https://github.com/Kanevry/session-orchestrator.git && cd session-orchestrator
npm install
npm test          # vitest
npm run lint      # ESLint v10 + Prettier
npm run typecheck # node --check on every .mjs file

.npmrc ships with ignore-scripts=true (supply-chain defence), so Husky git hooks don't auto-wire on install — run npx husky once after cloning. git commit then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.

Two directories share the name rules and play opposite roles: rules/ is the deliverable rule library shipped out to consumer repos via /bootstrap --sync-rules, while .claude/rules/ is this repo's own always-on rule set.

Contributor docs: Plugin Architecture (v3) · CONTRIBUTING.md · agent authoring spec.

Support & scope

Session Orchestrator is provided as-is — a community project with no SLA, no commercial support contract, and no guaranteed response time. Maintenance is best-effort.

• Questions, ideas, show-and-tell → GitHub Discussions
• Bugs and feature requests → Issues

What it is not:

• Not an official product of any agent vendor. An independent, community-maintained project — not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)
• Not a replacement for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs on top of your existing agent — you still need one of those installed.
• Local by default. Runs locally — no account required. Optional, strictly opt-in anonymous usage telemetry (off until you consent; see docs/telemetry.md).
• No guarantee that telemetry numbers transfer to your repo. Reported test counts and metrics describe this repository under its own conditions (details). Your results will vary by stack, project size, and configuration.

Documentation

• docs/ Router — living reference vs. public decision history vs. active work documents; what moved to the private Meta-Vault and why
• User Guide — installation, config reference, workflow walkthrough, FAQ
• Components & Reference — full skill/command/agent/hook inventory, repository anatomy, comparisons
• Plugin Architecture (v3) — contributor guide, layering, hook anatomy, testing
• Migration to v3 — upgrade path from v2.x, known issues, rollback
• Telemetry — what the optional opt-in usage telemetry collects, and how to turn it off
• Telemetry claims — how reported metrics are measured, and why they may not transfer
• Example Configs — Session Config examples for Next.js, Express, Swift
• CHANGELOG.md — version history

We follow Conventional Commits — see CONTRIBUTING.md.

Learn the method behind it

This plugin is a methodology turned into code. If you want the reasoning behind it — why execution runs in waves, why every wave ends at a verification gate, how to make an autonomous loop that actually finishes — those playbooks are taught hands-on at agenticbuilders.at:

• Multi-Agent Orchestration — leading several agents in coordinated waves: when parallelism pays, briefing subagents cleanly, turning failures into firm gates.
• Loop Engineering — designing autonomous loops that finish verifiably: done-conditions, verification gates, kill-switches.

The plugin is free and MIT. The courses are for going deeper, not a requirement for using it.

Links

• Homepage · Privacy Policy

License

MIT