helix — Claude Code hook: session event and prompt interception
helix is a Claude Code hook that intercepts session lifecycle events and custom prompt expansions. It triggers on session start, directory changes, tool execution, and exit.
Apache-2.0 ★ 454 updated 2026-11-17
/plugin marketplace add didi/helixharness
/plugin install helix@helixharness-marketplaceWhat helix does
The hook connects Claude Code lifecycle events to the HelixHarness plugin execution logic. Each event triggers scripts/python_hook_bootstrap.sh, handing control over to hosts/claude-code/hook_entry.py inside a Bash shell.
The configuration listens to SessionStart, CwdChanged, and SessionEnd. It intercepts tool operations matching Skill under PreToolUse, and expands user prompts prefixed with ^helix: under UserPromptExpansion. Every command has a strict 3-second execution timeout, requiring functioning sh and Python runtime environments.
What it helps with
- Intercept session startup and termination events
- Track current working directory changes during runs
- Catch skill executions before tool dispatch
- Expand user prompts starting with the helix: prefix
Example prompts for the agent
- helix: draft the implementation plan for this service
- Run a workflow requiring directory change tracking
- Invoke a skill managed by HelixHarness
How to install helix
1Plugin marketplace
/plugin marketplace add didi/helixharness/plugin install helix@helixharness-marketplace2Manually: 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 helix
How to install helix in Claude Code?
Run /plugin marketplace add didi/helixharness, then execute /plugin install helix@helixharness-marketplace and configure .claude/settings.json.
What does helix do?
It handles lifecycle triggers including SessionStart, SessionEnd, CwdChanged, PreToolUse, and UserPromptExpansion, routing them into hook_entry.py.
What is required to run helix?
The setup depends on Bash, standard sh, and Python to execute python_hook_bootstrap.sh within a 3-second execution limit.
Source text
hooks.json · Apache-2.0
Hooks bundle shipped with the helix plugin for Claude Code.
HelixHarness workflow plugin for Claude Code and Codex with commands and reusable skills
Triggers on: PreToolUse, SessionStart, SessionEnd.
```json
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/scripts/python_hook_bootstrap.sh\" SessionStart \"${CLAUDE_PLUGIN_ROOT}/hosts/claude-code/hook_entry.py\"",
"timeout": 3,
"shell": "bash"
}
]
}
],
"CwdChanged": [
{
"hooks": [
{
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/scripts/python_hook_bootstrap.sh\" CwdChanged \"${CLAUDE_PLUGIN_ROOT}/hosts/claude-code/hook_entry.py\"",
"timeout": 3,
"shell": "bash"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/scripts/python_hook_bootstrap.sh\" SessionEnd \"${CLAUDE_PLUGIN_ROOT}/hosts/claude-code/hook_entry.py\"",
"timeout": 3,
"shell": "bash"
}
]
}
],
"PreToolUse": [
{
"matcher": "Skill",
"hooks": [
{
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/scripts/python_hook_bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/hosts/claude-code/hook_entry.py\"",
"timeout": 3,
"shell": "bash"
}
]
}
],
"UserPromptExpansion": [
{
"matcher": "^helix:",
"hooks": [
{
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/scripts/python_hook_bootstrap.sh\" UserPromptExpansion \"${CLAUDE_PLUGIN_ROOT}/hosts/claude-code/hook_entry.py\"",
"timeout": 3,
"shell": "bash"
}
]
}
]
}
}
```
© HelixHarness contributors · Apache-2.0 · didi/helixharness