session-orchestrator — Claude Code & Codex hook: what it does
session-orchestrator — a hook for Claude Code and Codex that wraps each agent session in structured planning, staged execution, and quality gates. Fires on SessionStart, PreToolUse, PostToolUse, Stop, and SubagentStop.
MIT ★ 1,596 updated 2026-10-29
.claude/settings.jsonWhat session-orchestrator does
session-orchestrator runs on both Claude Code and Codex, shipping as a hook bundle inside the hashgraph-online plugin. Each lifecycle event gets its own chain of .mjs scripts, executed synchronously via run-node.sh on Unix or codex-win.cjs on Windows, with a 5-second timeout per hook.
At session start, on-session-start.mjs prints a command menu — /session, /plan, /discovery, /evolve — and sets up state. Every Bash call then passes through seven PreToolUse guards in sequence: pre-bash-destructive-guard.mjs stops dangerous operations before they run, pre-bash-staging-fence.mjs keeps writes inside the staging boundary, pre-bash-memory-propose-audit.mjs audits memory proposals, pre-bash-sessions-ledger-guard.mjs maintains a session ledger, pre-tool-state-md-path-guard.mjs validates state-file paths, pre-bash-issue-budget.mjs tracks issue budgets, and enforce-commands.mjs checks command allowlists. After Bash finishes, post-bash-write-verify.mjs confirms the write landed, and loop-guard.mjs watches every tool call to cut off agent loops.
GitHub and GitLab integration lets the agent close issues directly from a session. To install, register the hooks in .claude/settings.json by hand — the full JSON structure is in the README at hashgraph-online/awesome-codex-plugins.
What it helps with
- block destructive
Bashcommands before they execute - stop the agent from looping on a single tool call
- close GitHub or GitLab issues from within the agent session
- restrict file writes to a defined staging boundary
- restore plan context after a
compactorresume
Example prompts for the agent
- Start a feature session against our issue tracker:
/session feature - Build a plan for the next milestone:
/plan new - Kick off a codebase analysis:
/evolve analyze
How to install session-orchestrator
Manually: put the files in place
.claude/settings.jsonThe hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json
Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command
Questions about session-orchestrator
How do I install session-orchestrator in Claude Code?
Register the hook entries in .claude/settings.json manually. The full JSON structure is documented in the README inside hashgraph-online/awesome-codex-plugins.
What does the session-orchestrator hook do?
It intercepts SessionStart, PreToolUse, PostToolUse, Stop, and SubagentStop events, runs a chain of guard scripts on every Bash call, prevents agent loops, enforces staging boundaries, and syncs issue state with GitHub and GitLab.
Does session-orchestrator work on Windows?
Yes. On Windows each hook runs through codex-win.cjs instead of run-node.sh; the rest of the logic is identical.
Source text
hooks-codex.json · MIT
Hooks bundle shipped with the session-orchestrator plugin for Claude Code.
Session orchestration for Claude Code, Codex, and Cursor IDE — structured planning, wave-based execution, VCS integration (GitLab + GitHub), quality gates, and clean session close-out with issue tracking.
Triggers on: PreToolUse, PostToolUse, SessionStart, Stop, SubagentStop.
```json
{
"description": "Synchronous Codex hooks for payload-compatible Session Orchestrator handlers.",
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
"command": "echo '🎯 Session Orchestrator v5.16.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"console.log('🎯 Session Orchestrator v5.16.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]')\"",
"async": false
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-session-start.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" on-session-start.mjs",
"timeout": 5
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/pre-bash-destructive-guard.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" pre-bash-destructive-guard.mjs",
"timeout": 5
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/pre-bash-staging-fence.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" pre-bash-staging-fence.mjs",
"timeout": 5
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/pre-bash-memory-propose-audit.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" pre-bash-memory-propose-audit.mjs",
"timeout": 5
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/pre-bash-sessions-ledger-guard.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" pre-bash-sessions-ledger-guard.mjs",
"timeout": 5
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/pre-tool-state-md-path-guard.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" pre-tool-state-md-path-guard.mjs",
"timeout": 5
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/pre-bash-issue-budget.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" pre-bash-issue-budget.mjs",
"timeout": 5
},
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/enforce-commands.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" enforce-commands.mjs",
"timeout": 5
}
]
}
],
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/post-bash-write-verify.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" post-bash-write-verify.mjs",
"timeout": 5
}
]
},
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/loop-guard.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" loop-guard.mjs",
"timeout": 5
}
]
}
],
"SubagentStart": [],
"SubagentStop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-stop.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" on-stop.mjs",
"timeout": 5
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-stop.mjs\"",
"commandWindows": "set NoDefaultCurrentDirectoryInExePath=1&& node -e \"require(require('path').join(require('path').isAbsolute(process.env.PLUGIN_ROOT||'')?process.env.PLUGIN_ROOT:process.exit(1),'hooks','codex-win.cjs'))\" on-stop.mjs",
"timeout": 5
}
]
}
]
}
}
```
© hashgraph-online · MIT · hashgraph-online/awesome-codex-plugins