Skip to main content
hook

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add didi/helixharness
/plugin install helix@helixharness-marketplace
Open on GitHub

What 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-marketplace

2Manually: 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 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

Similar hooks

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

From the same set3

More in the catalog

Project sponsors

Companies that keep this analytics open