Hookify plugin: ImportError due to versioned cache directory structure

[liyoungc]

Bug Description

The hookify plugin fails to import its own modules when loaded from the plugin cache, producing this error on every PreToolUse, PostToolUse, and other hook events:

Hookify import error: No module named 'hookify'

Root Cause

The plugin cache stores hookify at:

~/.claude/plugins/cache/claude-code-plugins/hookify/0.1.0/

The hook scripts (e.g., hooks/pretooluse.py) set up sys.path like this:

PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT')  # .../hookify/0.1.0/
parent_dir = os.path.dirname(PLUGIN_ROOT)            # .../hookify/
sys.path.insert(0, parent_dir)
sys.path.insert(0, PLUGIN_ROOT)

from hookify.core.config_loader import load_rules  # fails

Python's from hookify.core.config_loader expects a directory named hookify/ containing core/config_loader.py on sys.path. But:

• parent_dir (…/hookify/) contains only 0.1.0/, not a hookify/ subdirectory
• PLUGIN_ROOT (…/hookify/0.1.0/) also doesn't contain a hookify/ subdirectory

The version number directory (0.1.0/) breaks Python's package resolution.

Workaround

Creating a symlink inside the cache directory resolves the issue:

ln -sf "0.1.0" ~/.claude/plugins/cache/claude-code-plugins/hookify/hookify

This lets Python find hookify/core/config_loader.py via the symlink.

Suggested Fix

Either:

1. Change imports to be relative — use from core.config_loader import load_rules instead of from hookify.core.config_loader
2. Add grandparent to sys.path — add os.path.dirname(os.path.dirname(PLUGIN_ROOT)) (i.e., .../cache/claude-code-plugins/) which contains the hookify/ directory. Then create an __init__.py in the hookify/ cache directory, or adjust the versioned layout.
3. Use PLUGIN_ROOT directly — since PLUGIN_ROOT/core/ exists, change the path setup to treat PLUGIN_ROOT as the package root.

Environment

• macOS Darwin 25.4.0 (Apple Silicon)
• Claude Code (latest)
• Hookify plugin v0.1.0
• Plugin author: Daisy Hollman (daisy@anthropic.com)

Impact

The error fires on every single tool call (PreToolUse + PostToolUse), meaning 2 error messages per tool invocation. While hookify gracefully degrades (exits 0), it clutters system-reminder messages and wastes context window tokens.

🤖 Generated with Claude Code

[github-actions]

Found 1 possible duplicate issue:

1. hookify plugin: broken Python imports — ModuleNotFoundError on every hook execution #33409

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[raye-deng]

This is a great analysis of the root cause. The pattern you're seeing is exactly what we call an "environment drift" bug — the code works in development (when imports resolve), but breaks in production (when versioned cache structure changes).

The interesting thing is that this wouldn't be caught by traditional quality gates:

• Unit tests pass because they don't test the versioned cache layout
• Type checking passes because Python's import system is runtime-only
• Code review passes because the logic looks correct

The bug only manifests in a specific deployment scenario (versioned cache).

We've seen similar patterns with AI-generated code: the AI assumes a particular environment structure (like "the cache has flat directory layout") without validating that assumption at runtime. The fix you suggested (relative imports) is the right direction — it removes the assumption about parent directory structure.

For anyone running into similar environment assumptions in AI-generated code, adding runtime environment validation checks in CI can catch these issues before they hit production.

npx @opencodereview/cli scan . --sla L1

[poparcosmin]

Reproducing this on Ubuntu 26.04 (Python 3.12, Claude Code recent), hookify v0.1.0. The root cause is correctly identified — from hookify.core.config_loader import load_rules fails because PLUGIN_ROOT/hookify/ doesn't exist in the flat cache layout.

Local workaround that unblocks the plugin (idempotent, applies to any cached version):

for v in ~/.claude/plugins/cache/claude-code-plugins/hookify/*/; do
  [ -d "$v/core" ] || continue
  mkdir -p "$v/hookify"
  touch "$v/hookify/__init__.py"
  for sub in core utils matchers hooks; do
    [ -d "$v/$sub" ] && ln -sfn "../$sub" "$v/hookify/$sub"
  done
done

This adds a tiny hookify/ facade subdirectory with symlinks, so the existing imports resolve without modifying any shipped code. We've automated this as a SessionStart hook locally so it survives plugin cache regeneration on updates.

Suggested upstream fix (2 minimal options):

Option A — facade hookify/__init__.py in the plugin repo (no runtime layout change):

# hookify/__init__.py
import os, sys
_PARENT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
if _PARENT not in sys.path:
    sys.path.insert(0, _PARENT)

Plus trivial hookify/core.py, hookify/hooks.py, etc., each doing from core import * (or similar namespace re-export).

Option B — move everything under hookify/ (cleaner long-term):

plugins/hookify/
└── hookify/
    ├── __init__.py
    ├── core/
    ├── hooks/
    ├── matchers/
    └── utils/

Then hooks.json hook commands become python3 ${CLAUDE_PLUGIN_ROOT}/hookify/hooks/pretooluse.py.

Happy to prep a PR for either option if maintainers indicate preference. Full issue + patch saved locally at ~/.claude/pending-contributions/hookify-plugin/ (README + issue-body + git-format-patch for Option A).