scorpiox-hookShell
Available Platforms:
Linux x64
Linux ARM64
macOS ARM64
Windows x64
Event hook system for ScorpioX lifecycle events. Allows you to register and execute custom scripts or commands that trigger automatically at specific points during the ScorpioX session lifecycle — such as session start, before/after tool execution, on error, and session end.
🪝 Lifecycle Hook Events
| Hook Event | When It Fires | Typical Use |
|---|
| session-start | When a new ScorpioX session begins | Set environment, load config, init logging |
| pre-tool | Before any tool is invoked | Validation, audit logging, permission checks |
| post-tool | After a tool finishes execution | Cleanup, result caching, notifications |
| on-error | When a tool or command fails | Error reporting, fallback logic, alerts |
| session-end | When the session terminates | Cleanup temp files, send summaries, save state |
| pre-prompt | Before the user prompt is processed | Input sanitization, context injection |
| post-response | After the model response is generated | Response logging, metrics, transformations |
⚙️ Flags & Options
This tool uses a folder-based hook convention rather than command-line flags. Place executable scripts in the appropriate hook directories to configure behavior.
📖 Usage Examples
Hook Directory Structure
Hooks are organized by event type in the .scorpiox/hooks/ directory:
.scorpiox/hooks/
├── session-start/
│ ├── 01-load-env.sh
│ └── 02-init-logging.sh
├── pre-tool/
│ └── validate-permissions.sh
├── post-tool/
│ └── audit-log.sh
├── on-error/
│ └── notify-slack.sh
├── session-end/
│ └── cleanup.sh
├── pre-prompt/
│ └── inject-context.sh
└── post-response/
└── log-response.sh
Creating a Session Start Hook
Create a script that runs automatically when a new session starts:
$ mkdir -p .scorpiox/hooks/session-start
$ cat > .scorpiox/hooks/session-start/01-setup.sh << 'EOF'
#!/bin/bash
export PROJECT_ROOT="$(pwd)"
echo "[hook] Session started at $(date -Iseconds)" >> /tmp/sx-audit.log
echo "[hook] Working directory: $PROJECT_ROOT" >> /tmp/sx-audit.log
EOF
$ chmod +x .scorpiox/hooks/session-start/01-setup.sh
Pre-Tool Validation Hook
Block tool execution if certain conditions are not met:
$ cat > .scorpiox/hooks/pre-tool/check-branch.sh << 'EOF'
#!/bin/bash
# Prevent destructive tools on main branch
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
TOOL_NAME="$SX_TOOL_NAME"
if [ "$BRANCH" = "main" ] && [ "$TOOL_NAME" = "scorpiox-bash" ]; then
echo "[hook] WARNING: Running bash on main branch" >&2
fi
EOF
$ chmod +x .scorpiox/hooks/pre-tool/check-branch.sh
Error Notification Hook
Send alerts when errors occur during the session:
$ cat > .scorpiox/hooks/on-error/notify.sh << 'EOF'
#!/bin/bash
# Log the error with context
echo "[ERROR] Tool: $SX_TOOL_NAME" >> /tmp/sx-errors.log
echo "[ERROR] Exit code: $SX_EXIT_CODE" >> /tmp/sx-errors.log
echo "[ERROR] Time: $(date -Iseconds)" >> /tmp/sx-errors.log
echo "---" >> /tmp/sx-errors.log
# Optional: send webhook notification
# curl -s -X POST "$WEBHOOK_URL" -d "{\"text\":\"Error in $SX_TOOL_NAME\"}"
EOF
$ chmod +x .scorpiox/hooks/on-error/notify.sh
Post-Response Metrics Hook
Track token usage and response times after each model response:
$ cat > .scorpiox/hooks/post-response/metrics.sh << 'EOF'
#!/bin/bash
# Append metrics to a CSV log
echo "$(date +%s),$SX_RESPONSE_TOKENS,$SX_DURATION_MS" >> .scorpiox/metrics.csv
EOF
$ chmod +x .scorpiox/hooks/post-response/metrics.sh
Execution Order
Hook scripts execute in alphabetical order. Use numeric prefixes to control ordering:
.scorpiox/hooks/session-start/
├── 01-load-env.sh
├── 02-init-logging.sh
└── 99-final-setup.sh
Session Cleanup Hook
Clean up temporary resources when the session ends:
$ cat > .scorpiox/hooks/session-end/cleanup.sh << 'EOF'
#!/bin/bash
# Remove temp files created during session
rm -rf /tmp/sx-session-$SX_SESSION_ID 2>/dev/null
# Summarize session
TOOL_COUNT=$(wc -l < /tmp/sx-audit.log 2>/dev/null || echo 0)
echo "[hook] Session ended. $TOOL_COUNT operations logged."
EOF
$ chmod +x .scorpiox/hooks/session-end/cleanup.sh
🔧 Source & Build Info