Skip to main content
hook CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/settings.json
Open on GitHub

What 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 Bash commands 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 compact or resume

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.json

The 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

Similar hooks

All hooks for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
tailtest tailtest detects files modified during an agent turn and triggers automated test writing and execution. Works across 8 languages with zero config. CX Codex ★ 1,596repo stars stop-that-shit The stop-that-shit hook for Claude Code and Codex checks agent actions against explicit task modes and bounds decisions about dependencies, hashes, and subagents. CX Codex ★ 1,596repo stars board A SessionStart hook that tells the agent what is on the project board. The board lives in plain Markdown files, so you can read it straight from the terminal. CX Codex ★ 1,596repo stars steinwall The steinwall hook for Claude Code and Codex provides cost controls, action guards, and loop recovery for unattended agent sessions with shell execution. CX Codex ★ 1,596repo stars repopilot repopilot takes a repo snapshot at session start and checks it again before the agent stops. If tests, suppressions or CI gates got weaker, the session will not end quietly. CX Codex ★ 1,596repo stars codex-project-autopilot codex-project-autopilot — a hook for Claude Code and Codex that runs a check after every file write or edit. Fires automatically on PostToolUse events. CX Codex ★ 1,596repo stars praxis This hook loads Praxis triage when a session starts or resumes, so the agent can work toward a defined outcome instead of a step list. CX Codex ★ 1,596repo stars off-the-wall The off-the-wall hook quotes your earlier fixes into the prompt before every Codex answer. The model sees what you corrected before and stops repeating the same mistakes. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open