Claude Code · Codex CLI · Cursor IDE · Pi

Install. Run a session.
Check the result.

Choose your coding tool, install the plugin and its dependencies, then bootstrap your project. This guide explains the first session and which guards your tool can enforce. On Codex, destructive-command and file-scope rules are instructions only.

Node.js 24 or later · MIT · guidance reviewed against source on 2026-09-08

Historical installation E2E record: v3.20.0 on 2026-08-19. The source review date records a documentation check, not a new installation test.

01 / Prerequisites

Before you start

Start with Node.js, Git and a supported coding tool. Some optional workflows also need a shell utility.

Operating systems: macOS and Linux are covered by CI. Native Windows use is untested; the shell hooks and optional MCP server need WSL or Git Bash.

Which file your harness reads

The configuration lives in your project’s instruction file. Which file that is depends on the tool, and the contents are identical either way.

On Cursor, native pickup of CLAUDE.md is unverified. If settings are not visible, mirror the block into AGENTS.md; see Cursor configuration.

02 / Install

Install

Same plugin, four paths. Pick your tool and complete the dependency and restart steps for it.

Claude Code

Marketplace, then one manual step

/plugin marketplace add Kanevry/session-orchestrator
/plugin install session-orchestrator@kanevry

Both lines run inside Claude Code, not in a shell.

Current Claude Code installs the Node dependencies with the plugin. To check once, in a shell:

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

Clone, install, run the installer

git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator
cd ~/Projects/session-orchestrator && npm install
node scripts/codex-install.mjs

Requires Codex CLI 0.144.4 or later. Your project config goes in AGENTS.md. Start a fresh task after installation and review the plugin hooks through /hooks. The destructive-command and file-scope guards are instructions only on Codex; the plugin does not enforce them. The workflow and quality checks still run.

For a Codex Git marketplace installation, refresh with codex plugin marketplace upgrade kanevry, then codex plugin add session-orchestrator@kanevry. For the local clone shown above, pull the clone, run npm install and rerun the installer. After either path, start a fresh task and reopen the skill picker. See Codex refresh instructions.

Cursor IDE

Clone, install, point at your project

git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator
cd ~/Projects/session-orchestrator && npm install
node scripts/cursor-install.mjs /absolute/path/to/your/project

Cursor bridges preToolUse for scope checks and beforeShellExecution for command checks. afterFileEdit runs additional checks after a write; it cannot undo that write. Tasks execute sequentially.

Pi

The only path that resolves dependencies for you

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi install npm:session-orchestrator

No separate npm install step afterwards. Config goes in AGENTS.md.

03 / First run

Your first session

Bootstrap the project once, then use the three session commands. On Claude Code, Cursor and Pi, start with /bootstrap. Codex exposes these workflows as selectable skills:

$session-orchestrator:bootstrap
$session-orchestrator:session feature
$session-orchestrator:go
$session-orchestrator:close

Select these skills in the Codex picker or invoke them in a message. They are not shell commands. The slash commands below describe the same workflows on the other tools.

1. /session feature: research and agree the scope

   It reads the repository before it asks you anything: git state, open issues, CI status on the current commit, what the last session left behind. Then it reports what it found and proposes a plan: how many waves, how many agents, and how confident it is. You can correct the proposed scope before implementation. Session-start also records local session state.

2. /go: execute the plan in checked waves

   For a deep session, Discovery reads and Impl-Core writes the feature. Impl-Polish fixes the edges. Quality simplifies, tests and reviews. Finalization tidies up. The workflow runs your tests and typecheck after each implementation wave and requires the full configured test, typecheck and lint gate after the Quality wave and before completion. Claude Code and Codex can dispatch parallel agents; Cursor and Pi run the tasks sequentially. Housekeeping uses one wave; deep uses five and the ultradeep profile uses seven.

3. /close: verify, commit, and file what is left

   It walks the plan item by item and checks each one against the actual working tree, commits, and turns anything unfinished into a carryover issue instead of quietly dropping it.

Setup can ask about:

• Tier: fast, standard or deep. It decides how much structure gets scaffolded. Fast is right for a spike.
• Stack archetype: only asked for standard or deep, and only when the repository is genuinely ambiguous.
• Owner persona: language, tone, how much output you want, how much preamble before an action. Stored once per machine in ~/.config/session-orchestrator/owner.yaml, outside every repository, never committed.
• Telemetry consent: whether anonymized hardware patterns may be shared to improve resource defaults. Declining is a normal answer and changes nothing else.
• Dispatcher autonomy: a one-time, per-repository capture. The recommended answer is off, which is also the fail-closed default.
• Your actual scope: the question you came for.

Saved preferences and the bootstrap marker let later sessions reuse the setup. Each session still checks the repository and confirms any scope that has not already been authorized.

04 / Configuration

The minimal config

These seven fields define the minimal Session Config. See the configuration reference for additional features and their defaults.

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

Use CLAUDE.md on Claude Code or AGENTS.md on Codex CLI and Pi. For Cursor, follow the instruction-file note above. The heading matters: the parser looks for ## Session Config literally.

enforcement takes strict, warn or off. With an active compatible scope hook, strict denies supported out-of-scope edits, warn reports them without denying the edit, and off disables scope checking. Codex has no compatible scope handler, so changing this setting does not add enforcement there.

05 / Guards

What the guards can enforce

Guard behaviour depends on your coding tool. Claude Code runs the guard hooks directly; Cursor and Pi use bridges with documented limits. On Codex, destructive-command and file-scope rules are instructions only. Scope edits are denied only when a compatible hook is active and enforcement is strict.

The destructive-command guard

The policy in .orchestrator/policy/blocked-commands.json defines 16 rules: 12 blocking and 4 warning. An active hook applies them on Claude Code and through compatible Cursor or Pi bridges. The plugin does not enforce this guard on Codex. The blocking rules cover hard resets, checkout discards, forced cleaning, destructive removal, force-push, SQL DROP TABLE, truncating protected files or the harness memory, and deleting the session ledgers. The warning rules cover mixed and soft resets, stash, and git push --force-with-lease.

The reason it is that broad: several sessions can share one working copy, and a stash or a reset takes work from a neighbour who has no way to find it again.

Scope enforcement

Agents receive declared paths, checked for overlaps before dispatch. With an active compatible handler, hooks/enforce-scope.mjs blocks supported out-of-scope edits in strict mode and reports them without denial in warn mode. Claude Code runs the hook directly; Cursor and Pi use bridges with documented limits. On Codex the rule is an instruction only, because no compatible file-scope handler is wired. A declared scope is not filesystem isolation.

When a legitimate edit is denied, review the plan and other agents' scopes before adding the missing path. Recheck overlaps before dispatching work against the wider scope.

enforcement: off disables scope checking. It does not disable the separate destructive-command guard on tools where that guard is active.

06 / Diagnosis

When something is wrong, and how you would even notice

A session summary can miss a failed dispatch or an incomplete record. Compare the recorded work with the changes and checks you actually observed.

The session record is one source of evidence. To inspect its latest entry:

tail -1 .orchestrator/metrics/sessions.jsonl | jq '{session_id, total_waves, total_agents, total_files_changed}'

This diagnostic command needs jq. You can also open the JSONL file in a text editor.

Signs that the record needs investigation:

• total_agents: 0 after a wave in which you plainly watched agents work.
• A duration of 0m for a session that took you half an hour.
• undefined anywhere in the record: a field that was never written, not a field that is empty.
• -abandoned- inside the session id although you closed cleanly with /close. That name is reconstructed after the fact for sessions that never closed themselves.

None of these mean your code is broken. They mean the run did not do what the summary implies, and the honest response is to look at what actually changed on disk before you build on it.

Installation and environment checks

Check these common failure points and the issue tracker when installation seems incomplete.

• Node is not on the hook’s PATH. Hooks run in the harness’s environment, not your login shell. A version manager that only initialises in your interactive shell profile is not there when a hook runs, so the hook cannot find node. The hook launcher tries known Node locations and warns when Node cannot be found. Set SO_NODE_BIN to an absolute Node executable path, or launch the coding tool from a shell where Node resolves.
• Missing node_modules. Use claude plugin list --json to find the active installation and run npm install there. Missing runtime packages can prevent hooks from loading.
• Wrong target directory. Cursor uses the current directory when no project path is given. Verify the generated Cursor files in the intended project.

07 / Further

Where to go deeper

This page is the short path. Everything below is the long one, and all of it lives in the repository.