Extensibility — SCORPIOX CODE

Overview

scorpiox code is designed for extensibility from the ground up. Every major subsystem exposes file-based extension points — drop a shell script into a hooks directory, create a markdown file for a new slash command, or register an MCP server for custom tools. No recompilation, no plugins API, no dynamic linking. Just files.

Extension Model

Hooks, slash commands, skills, custom MCP servers, CLAUDE.md, EmitEvent tool

# Directory structure
.scorpiox/
├── hooks/
│   ├── session_start/
│   │   ├── sync-01-validate.sh    # sync — blocks, checked
│   │   └── 01-notify.sh           # async — fire-and-forget
│   ├── agent_complete/
│   ├── tool_use/
│   └── api_error/
.claude/
├── commands/
│   ├── deploy.md                  # /deploy — markdown prompt
│   └── test.sh                    # /test — executable script
└── skills/
    └── my-skill/
        └── SKILL.md               # /my-skill — reusable workflow
        

Event Hooks

14 built-in events covering the full session lifecycle. Hooks are shell scripts (or Python, PowerShell, batch) placed in .scorpiox/hooks/<event>/. Sync hooks run first and can abort; async hooks fire in parallel.

Hook Arguments

# Every hook receives 4 positional arguments:
$1  event name        # e.g. session_start
$2  session ID        # e.g. 2026_02_10_cool_newton
$3  ISO timestamp     # e.g. 2026-02-10T20:12:59Z
$4  JSON data         # e.g. {"model":"opus"}
        

Environment Variables

SX_CWD         working directory
SX_HOOKS_DIR    .scorpiox/hooks
SX_EVENT        event name (convenience)
SX_SESSION_ID   session id (convenience)
        

All Events

Event	Type	Trigger	JSON $4
`session_start`	lifecycle	New session begins	`model, provider, log_level`
`session_end`	lifecycle	Session ends gracefully	`—`
`session_clear`	lifecycle	User runs /clear	`—`
`user_message`	event	User sends a message	`len`
`agent_run_start`	event	Agent begins processing	`—`
`agent_complete`	event	Agent finishes a run	`turns, history`
`subagent_complete`	event	Sub-agent finishes	`turns, history`
`agent_cancelled`	event	User cancels agent	`reason, turns`
`tool_use`	event	Tool invocation	`tool, tool_use_id`
`mcp_call`	event	MCP server tool call	`server, tool`
`api_response`	event	API response received	`turn, stop_reason, in_tokens, out_tokens`
`api_error`	event	API error occurred	`error, status`
`compact`	event	Conversation compacted	`from, to`
`hook_failed`	event	A hook exited non-zero	`exit_code, hook`

Naming Conventions

Pattern	Description
`01-notify.sh`	Async (default) — fire-and-forget, sorted by prefix
`sync-01-validate.sh`	Sync — blocks execution, exit code checked, runs first
`_disabled.sh`	Disabled — underscore prefix, skipped
`.hidden.sh`	Hidden — dot prefix, skipped

Supported Script Types

Extension	Runner	Note
`.sh`	`/bin/sh <script> <args>`	auto-fixes CRLF
`.ps1`	`pwsh -NoProfile -File <script> <args>`	—
`.py`	`python3 <script> <args>`	—
`.bat`	`cmd.exe /c <script> <args>`	Windows only
`other`	`direct exec`	must have shebang on Unix

Execution Order

Sync hooks run first (sorted by filename, sequential, blocking)
If any sync hook fails (non-zero exit) → abort, skip async hooks
Async hooks run after (sorted, forked in parallel)

Logs

# Per-session log:
.scorpiox/sessions/<id>/hooks.log

# Fallback log:
.scorpiox/hooks/logs/hook.log
        

Example: Slack Notification on API Error

#!/bin/bash
# .scorpiox/hooks/api_error/01-slack.sh
curl -X POST https://hooks.slack.com/services/T.../B.../xxx   -d "{"text":"API error: $( echo $4 | jq -r .error )"}"
        

Hook CLI

The scorpiox-hook binary manages hooks from the command line.

Command	Description
`scorpiox-hook emit <event> [--data '{"json"}'] [--session <id>]`	Emit a custom event
`scorpiox-hook init`	Initialize hooks directory structure
`scorpiox-hook list [--event <name>]`	List installed hooks
`scorpiox-hook test <event> [name]`	Test a hook script
`scorpiox-hook install <event> <file>`	Install a hook script
`scorpiox-hook events`	List all supported events

Quick Start

# Initialize hook directories for all events
scorpiox-hook init

# Install a hook script
scorpiox-hook install session_start ./my-hook.sh

# Test it
scorpiox-hook test session_start

# Emit a custom event (triggers hooks + writes to events.jsonl)
scorpiox-hook emit my_custom_event --data '{"key":"value"}'
        

Slash Commands

Custom commands invoked via /command_name in the TUI. Markdown files are injected as system prompt context. Script files are executed directly.

File Formats

.md — Injected as system prompt context (the AI reads it)
.sh — Executed via bash, output returned to the AI
.ps1 — Executed via pwsh, output returned to the AI

Locations

# User-level (available in all projects)
~/.claude/commands/deploy.md

# Project-level (available in this repo)
./.claude/commands/deploy.md
        

Argument Passing

Text after the command name replaces $ARGUMENTS in the file content.

# .claude/commands/fix.md
Fix the following issue: $ARGUMENTS
Focus on test coverage and error handling.

# Usage in TUI:
/fix the login form validation is broken on Safari
        

Resolution Priority

When multiple sources define the same command name, higher priority wins:

#	Source	Description
1	`SX_CMDSRC_SYSTEM`	Built-in system commands (/exit, /clear, /help, etc.)
2	`SX_CMDSRC_BUILTIN_SKILL`	Pre-shipped skills embedded in binary
3	`SX_CMDSRC_BUILTIN_CMD`	Pre-shipped commands embedded in binary
4	`SX_CMDSRC_USER`	~/.claude/commands/
5	`SX_CMDSRC_PROJECT`	./.claude/commands/
6	`SX_CMDSRC_USER_SKILL`	~/.claude/skills/<name>/SKILL.md
7	`SX_CMDSRC_PROJECT_SKILL`	./.claude/skills/<name>/SKILL.md — highest priority

Built-in System Commands (23)

/exit
/quit
/q
/clear
/help
/model
/save
/load
/rewind
/config
/transcript
/continue
/info
/resume
/r
/keepalive
/context_resize
/terminal
/history
/compact
/cd
/voice
/callbacks
        

Skills

Skills are reusable workflow instructions in SKILL.md format. They define multi-step procedures the AI follows when invoked. Built-in skills are embedded in the binary at compile time; user and project skills override built-ins.

Structure

# Directory layout
.claude/skills/
└── my-skill/
    └── SKILL.md      # Invoked via /my-skill or InvokeSkill tool

~/.claude/skills/
└── global-skill/
    └── SKILL.md      # Available in all projects
        

SKILL.md Format

# my-skill

Description of what this skill does.

## Steps

1. First, check the current state by running ...
2. Then modify the configuration at ...
3. Verify by running the test suite ...

## Notes

- Always create a backup before modifying
- Use $ARGUMENTS as the target path
        

Invocation

/skill_name — Invoke from TUI slash command
InvokeSkill tool — Programmatic invocation by the agent

Source

Built-in skills source: scorpiox/libsxutil/sx_builtin_skills.c
Generator: scorpiox/libsxutil/gen_builtin_skills.py
Skill source directory: scorpiox/libsxutil/builtin_skills/

MCP Servers

Register custom MCP servers (JSON-RPC 2.0 over stdio) for additional tools. The agent discovers and calls tools on registered servers automatically. Max 16 servers, 512 tools.

Configuration

# scorpiox-env.txt
MCP=1                                    # Enable MCP system
MCP_SERVER=mytools:node:server.js         # Inline: name:command:args
MCP_CONFIG=/path/to/mcp_servers.json       # JSON config file
MCP_FILE=/path/to/.mcp                     # .mcp format config
MCP_ALLOW=mytools:read_*                   # Allow specific tool patterns
MCP_DENY=mytools:delete_*                  # Deny specific tool patterns
        

CLI Commands

Command	Description
`scorpiox-mcp discover [--json]`	Discover available servers and tools
`scorpiox-mcp call <server> <tool> [json]`	Call a specific tool on a server
`scorpiox-mcp list [--json]`	List all registered servers
`scorpiox-mcp info <server> <tool>`	Show tool details
`scorpiox-mcp test <server>`	Test server connectivity

Tool Registry

Built-in tools can be toggled via TOOL_<NAME>=0|1 in scorpiox-env.txt. MCP-discovered tools are injected via sx_tools_set_extra_json() into the tool array sent to the LLM.

Source

scorpiox/scorpiox-mcp.c — MCP client binary
scorpiox/libsxutil/sx_tools.c — Tool registry
scorpiox/libsxutil/sx_tools.h — Tool definitions

CLAUDE.md

A CLAUDE.md file in the project root is automatically loaded as system prompt context. This is the simplest extension point — write instructions in markdown, and the AI follows them for every session in that project.

How It Works

# Place in project root:
./CLAUDE.md

# Loaded by:
scorpiox/libsxutil/sx_systemprompt.c
        

Example

# CLAUDE.md

## Project Rules
- Always write tests for new functions
- Use snake_case for C function names
- Run `make test` before committing
- Never modify files in vendor/

## Variables
{API_KEY}='sk-...'
{DEPLOY_TARGET}='production'
        

Scope

CLAUDE.md applies to every session started in that directory. It's read once at session start and included in the system prompt sent to the AI provider.

EmitEvent Tool

The EmitEvent tool allows the AI agent to emit custom events into the session event stream (events.jsonl). Disabled by default for safety.

Enable

# scorpiox-env.txt
TOOL_EMITEVENT=1
        

Session Events

All events (built-in and custom) are written to structured JSON lines:

# Event log location:
.scorpiox/sessions/<id>/events.jsonl

# Also emitted as individual files for SDK consumers:
msg_NNNN_event.json   # when emit_msg is enabled
        

Source

scorpiox/libsxutil/sx_tools.c — EmitEvent tool implementation
scorpiox/libsxutil/sx_session.c — sx_session_event() writes events

Configuration Cascade

All extensibility features are configured via scorpiox-env.txt using a cascading priority system. Higher-priority files override lower ones.

#	Source	Description
1	Built-in defaults	Compiled into the binary
2	`exe_dir/scorpiox-env.txt`	Global config next to the executable
3	`~/.claude/scorpiox-env.txt`	User-level overrides
4	`CWD/.scorpiox/scorpiox-env.txt`	Project-level overrides
5	OS environment variables	Highest priority — always wins

Key Settings

# Hooks
HOOKS_ENABLED=1          # Enable/disable hook system (default: enabled)
HOOKS_TIMEOUT=30         # Sync hook timeout in seconds

# MCP
MCP=1                     # Enable MCP server system
MCP_SERVER=name:cmd:args  # Register inline server

# Tools
TOOL_EMITEVENT=1          # Enable EmitEvent tool
TOOL_BASH=1               # Enable/disable individual tools

# Agent hooks (.hooks file)
# Format: event:command (one per line)
# Installed to: <task_dir>/.scorpiox/hooks/<event>/
        

Source

scorpiox/libsxutil/sx_config.c — Configuration loader
scorpiox/libsxutil/sx_config.h — Config key definitions
scorpiox/scorpiox-config.c — TUI config editor