Home › Extensibility

Extensibility

31 lifecycle hooks, custom slash commands, reusable skills, MCP server integration, timer callbacks, and SDK event emission. Every extension point fires from C — zero runtime overhead when unused.

31Hooks
19Commands
16Max MCP Servers
8Callback Slots
Lifecycle Hooks Slash Commands Skills MCP Servers Timer Callbacks SDK Event Emission

Lifecycle Hooks

Drop shell, Python, or PowerShell scripts into .scorpiox/hooks/<event>/ and they execute automatically when the event fires. All 31 hooks pass four arguments: $1=event $2=session_id $3=ISO_timestamp $4=JSON.

Configuration

HOOKS_ENABLED1 (default) — master switch
HOOKS_TIMEOUT30 (default) — timeout in seconds

Logs

sessions/<id>/hooks.logPer-session log
hooks/logs/hook.logFallback global log
Hook Type Trigger
session_start lifecycle New session begins (user opens TUI or resumes)
session_end lifecycle Session ends gracefully (user exits or DLL unloads)
session_clear lifecycle User runs /clear command to reset chat history
user_message event User sends a message to the agent
agent_run_start lifecycle Agent begins processing a user message
agent_complete lifecycle Agent finishes an agentic run (all turns complete)
agent_cancelled lifecycle User cancels the running agent (Ctrl+C or Escape)
tool_use event Agent invokes a built-in tool (Bash, ReadImage, etc.)
mcp_call event Agent calls an MCP server tool (mcp__server__tool)
api_response event API response received from provider
api_error event API error occurred (rate limit, auth failure, network)
compact lifecycle Conversation compacted (auto-shrink or /compact)

Example: Log agent completions

#!/bin/bash # .scorpiox/hooks/agent_complete/log_turns.sh turns=$(echo $4 | jq .turns) history=$(echo $4 | jq .history) echo "[$(date)] Session $2: $turns turns, $history messages" >> ~/scorpiox-agent.log

Slash Commands

19 built-in system commands, plus unlimited custom commands via .md, .sh, or .ps1 files. Markdown commands inject prompt context; shell commands execute directly.

Command Directories

~/.claude/commands/User-level commands
./.claude/commands/Project-level commands

Supported Formats

.mdInjected as prompt context
.shExecuted directly (bash)
.ps1Executed directly (PowerShell)

Resolution Priority

When multiple commands share the same name, higher priority wins:

  1. SX_CMDSRC_SYSTEM — built-in system commands (lowest)
  2. SX_CMDSRC_BUILTIN_SKILL — pre-shipped skills in binary
  3. SX_CMDSRC_BUILTIN_CMD — pre-shipped commands in binary
  4. SX_CMDSRC_USER — ~/.claude/commands/
  5. SX_CMDSRC_PROJECT — ./.claude/commands/
  6. SX_CMDSRC_USER_SKILL — ~/.claude/skills/
  7. SX_CMDSRC_PROJECT_SKILL — ./.claude/skills/ (highest)
Command Description Aliases
/exit Exit the application /quit, /q
/clear Clear chat history and screen —
/help Show available commands —
/model Show or switch model —
/save Save conversation to file —
/load Load conversation from file —
/rewind Rewind to previous checkpoint —
/config Open configuration editor —
/transcript Open transcript viewer —
/continue Continue generating response —
/info Toggle info box visibility —
/resume Resume previous conversation /r
/keepalive Toggle cache keep-alive (on/off) —
/context_resize Resize context window threshold —
/terminal Toggle terminal panel —
/history View conversation history —
/compact Compact context into new session —
/cd Change working directory —
/voice Record and transcribe voice input —

Example: Custom /deploy command

# .claude/commands/deploy.md # This file is injected as prompt context when user types /deploy Deploy the application to production: 1. Run all tests with `pytest` 2. Build the Docker image 3. Push to registry 4. Update the Kubernetes deployment 5. Verify health checks pass Use $ARGUMENTS as the target environment (staging/production).

Skills

Skills are reusable workflows with YAML frontmatter. Each skill lives in its own directory with a SKILL.md file that declares name, description, allowed tools, and context.

Skill Directories

~/.claude/skills/<name>/User-level skills
./.claude/skills/<name>/Project-level skills

SKILL.md Format

--- name: deploy-aws description: Deploy to AWS ECS allowed-tools: Bash, BackgroundBash context: ./infra/ argument-hint: environment name --- Deployment workflow instructions...

Frontmatter Fields

nameRequired — skill identifier
descriptionRequired — shown in /help
allowed-toolsOptional — restrict tool access
contextOptional — files/dirs to include
argument-hintOptional — hint for $ARGUMENTS

MCP Servers

Register up to 16 custom MCP servers exposing up to 512 tools total. Servers communicate via JSON-RPC 2.0 over stdio. Tools appear as mcp__<server>__<tool>.

Configuration Keys

MCP0/1 — master switch for MCP
MCP_SERVERname:command:arg1,arg2,... — inline definition
MCP_CONFIG/path/to/mcp_servers.json — external config
MCP_FILE/path/to/.mcp — dotfile-style config
MCP_ALLOWserver:glob_pattern — tool allow filter
MCP_DENYserver:glob_pattern — deny filter (overrides allow)

Inline Definition

# scorpiox-env.txt MCP=1 MCP_SERVER=mydb:python3:db_server.py MCP_ALLOW=mydb:query_* MCP_DENY=mydb:drop_*

External JSON Config

// mcp_servers.json { "servers": { "github": { "command": "npx", "args": ["@mcp/github"] } } }

Discovery

# Discover available MCP tools $ scorpiox-mcp discover --json # Tools are injected via sx_tools_set_extra_json() # and appear as: mcp__github__create_issue, mcp__mydb__query_users, etc.

Timer Callbacks

Schedule delayed messages that re-enter the agentic loop as synthetic user messages. 8 concurrent slots, 1–3600 second delays, auto-repeating up to N times.

Limits

max_slots8 concurrent callbacks
delay_range1–3600 seconds
default_repeat20 fires before auto-cancel

Actions

setSchedule a new callback
listShow active callbacks
cancelCancel by ID or cancel all

Example: Monitor build status

# Agent sets a callback to check CI status every 60 seconds SetCallback( action="set", delay_seconds=60, message="Check CI build status for PR #42", repeat_count=10 ) # After 60s, the message fires as a synthetic user message # Agent responds, checks build, reports back # Repeats up to 10 times (10 minutes total)

SDK Event Emission

Every agent interaction writes structured JSON files to the session messages directory for external SDK consumers. Enable telemetry reporting to POST events to a remote URL.

Configuration

EMIT_SESSION_TRACKING0/1 — enable external telemetry
EMIT_SESSION_API_URLURL to POST session events

Output Structure

# Session messages directory .scorpiox/sessions/<id>/messages/ msg_0001_user.json # User message msg_0002_assistant.json # Agent response msg_0002_event.json # Event metadata msg_0003_tool_use.json # Tool invocation msg_0004_tool_result.json # Tool output