laststance/claude-code-plugin-hacker

Claude Code Plugin Hacker

Codex Compatibility

When running this skill in Codex, translate Claude Code-only primitives before acting: AskUserQuestion -> chat/request_user_input, TodoWrite -> update_plan, Task/TaskCreate/TeamCreate/SendMessage -> spawn_agent/send_input/wait_agent when available and allowed, and EnterPlanMode/ExitPlanMode -> a concise chat plan plus explicit approval. Resolve Read/Write/Edit/Bash/WebSearch/WebFetch to Codex file/shell/web tools, and map ~/.claude/... paths to ~/.agents/... or ~/.codex/... unless the task explicitly targets Claude Code.

Cursor Compatibility

When running this skill in Cursor Agent, translate Claude Code-only primitives before acting: AskUserQuestion -> AskQuestion; TodoWrite -> Cursor TodoWrite or an equivalent checklist; Task/TaskCreate/TeamCreate/SendMessage/multi-agent flows -> Cursor Task (subagents), parallel Tasks, or run_in_background when allowed (TeamCreate/SendMessage may have no exact match); EnterPlanMode/ExitPlanMode -> Plan mode (SwitchMode / CreatePlan) plus explicit user approval. Resolve Read/Write/Edit/StrReplace/Bash/web/search/MCP via Cursor Composer or Agent equivalents. MCP names written as mcp__server__tool typically map to call_mcp_tool with configured server identifiers. Map ~/.claude/... to ~/.cursor/skills/, .cursor/skills/, and .cursor/rules/ unless the task explicitly targets Claude Code.

Specialist skill for debugging and fixing Claude Code plugin system issues.

When to Use

• SessionStart:startup hook error or any hook error on launch
• Plugin behavior after enable/disable doesn't match expectations
• Investigating how plugins, hooks, and skills interact
• Fixing broken plugin hooks across projects
• Auditing which plugins inject what into sessions

Critical Knowledge

enabledPlugins: false Is NOT a Kill Switch

| Component | When false | When true | |-----------|-------------|-------------| | hooks | Still execute | Execute | | skills | Still accessible via Skill tool | Accessible | | CLAUDE.md | Likely not loaded | Loaded | | agents | Likely not registered | Registered |

To truly stop a hook: edit hooks.json in cache, delete cache dir, or fix the script.

Plugin Cache Is Versioned

~/.claude/plugins/cache/<marketplace>/<plugin>/<hash>/

• <hash> = git commit hash of ~/.claude repo (when it's a git repo)
• New commit → new cache directory → new copy of hooks/skills
• Fixing ONE cached version does NOT fix others
• Always use find ... -exec for bulk fixes

Hook Execution Environment

Claude Code runs hooks in a minimal environment:

• Restricted PATH (may lack timeout, jq, etc.)
• Minimal environment variables (many unset)
• Short timeout on hook execution
• stdin receives JSON with hook context
• stdout must emit valid JSON for context injection
• Non-zero exit code → "hook error" displayed to user

Phase 1: Audit

Enumerate ALL hook sources. Run these diagnostics:

# 1. List ALL plugin hooks.json files
find ~/.claude/plugins/cache -name "hooks.json" -path "*/hooks/*" \
  -exec echo "=== {} ===" \; -exec cat {} \;

# 2. Find ALL SessionStart hooks specifically
find ~/.claude/plugins/cache -name "hooks.json" -path "*/hooks/*" \
  -exec grep -l "SessionStart" {} \;

# 3. User-defined hooks in settings.json
grep -A5 '"SessionStart"' ~/.claude/settings.json

# 4. List enabled plugins
grep -A1 'enabledPlugins' ~/.claude/settings.json | head -30

# 5. Count cached versions per plugin
for d in ~/.claude/plugins/cache/*/*/; do
  plugin=$(echo "$d" | rev | cut -d/ -f3-2 | rev)
  echo "$plugin: $(ls -d ${d}*/ 2>/dev/null | wc -l) versions"
done

Output: Complete map of hooks × plugins × versions.

Phase 2: Diagnose

Test each suspicious hook in isolation:

# Test a hook script directly
echo '{"source":"startup","session_id":"diag-test"}' | \
  CLAUDE_PLUGIN_ROOT="<plugin_root>" \
  <hook_command> 2>&1
echo "EXIT: $?"

Known Failure Patterns

| Pattern | Signature | Root Cause | Fix | |---------|-----------|------------|-----| | Permission denied | EACCES, exit 126/127 | .sh script missing +x | chmod +x all copies | | Unset variable | exit 1 with no output | set -u in bash script | Remove -u from set | | Node module mismatch | NODE_MODULE_VERSION N vs M | Native addon for wrong Node.js | npm rebuild <module> | | Database locked | SqliteError: database is locked | Concurrent DB access | Retry logic or skip | | Command not found | timeout: not found | Minimal PATH | Use builtins or full paths | | JSON parse error | SyntaxError: Unexpected token | Hook outputs non-JSON to stdout | Fix script output |

Permission Check (bulk)

# Find ALL hook scripts without execute permission
find ~/.claude/plugins/cache -name "*.sh" ! -perm -u+x \
  -exec echo "BROKEN: {}" \;

Bash Safety Check

# Find dangerous set -u in hook scripts
grep -rn "set.*-u" ~/.claude/plugins/cache/*/hooks/ \
  ~/.claude/plugins/cache/*/*/hooks/ 2>/dev/null

Node.js Native Addon Check

# Find better-sqlite3 or other native addons
find ~/.claude/plugins/cache -name "*.node" -exec sh -c \
  'echo "=== $1 ==="; file "$1"' _ {} \;

Phase 3: Fix

Fix 1: Bulk chmod (permission denied)

find ~/.claude/plugins/cache/<plugin> -name "<script>.sh" \
  ! -perm -u+x -exec chmod +x {} \; -exec echo "FIXED: {}" \;

Fix 2: Remove set -u (unset variable errors)

find ~/.claude/plugins/cache/<plugin> -name "<script>" \
  -exec sed -i '' 's/set -euo pipefail/set -eo pipefail 2>\/dev\/null || true/' {} \; \
  -exec echo "FIXED: {}" \;

Fix 3: Rebuild native addons

cd ~/.claude/plugins/cache/<plugin>/<version>
npm rebuild <module-name>

Fix 4: Remove problematic hook entirely

Edit hooks.json to empty the event:

{ "hooks": { "SessionStart": [] } }

Apply to ALL cached versions with find ... -exec.

Fix 5: Nuclear option — delete plugin cache

rm -rf ~/.claude/plugins/cache/<marketplace>/<plugin>/

Plugin will be re-cached on next session start.

Phase 4: Verify

# Re-test all hooks after fixes
find ~/.claude/plugins/cache -name "hooks.json" -path "*/hooks/*" \
  -exec grep -l "SessionStart" {} \; | while read f; do
    dir=$(dirname "$f")
    root=$(dirname "$dir")
    echo "=== Testing: $root ==="
    # Extract command from hooks.json and test it
    cmd=$(python3 -c "
import json, sys
h=json.load(open('$f'))
for entry in h.get('hooks',{}).get('SessionStart',[]):
  for hook in entry.get('hooks',[]):
    print(hook['command'].replace('\${CLAUDE_PLUGIN_ROOT}','$root'))
" 2>/dev/null)
    if [ -n "$cmd" ]; then
      echo '{"source":"startup"}' | CLAUDE_PLUGIN_ROOT="$root" eval "$cmd" >/dev/null 2>&1
      echo "EXIT: $?"
    fi
  done

Decision Tree

Hook error on startup?
├─ Run Phase 1 Audit
│  └─ Which plugins have SessionStart hooks?
│     ├─ Test each hook (Phase 2)
│     │  ├─ Permission denied → Fix 1 (chmod, ALL copies)
│     │  ├─ Exit 1, no output → Fix 2 (remove set -u)
│     │  ├─ NODE_MODULE_VERSION → Fix 3 (npm rebuild)
│     │  ├─ All pass locally but still errors →
│     │  │  Check if there are MORE cached versions
│     │  │  you didn't fix (Phase 1, count versions)
│     │  └─ Unknown error → Fix 4 (remove hook) or Fix 5 (nuke cache)
│     └─ Verify all hooks pass (Phase 4)
│
Plugin behavior unexpected after disable?
├─ Remember: `false` doesn't stop hooks/skills
├─ To stop hooks: edit hooks.json or delete cache
└─ To stop skills: delete cache (no other way)

Anti-Patterns

| Don't | Why | Do Instead | |-------|-----|-----------| | Set enabledPlugins: false to stop hooks | Doesn't work — hooks still run | Edit hooks.json or delete cache | | Fix one cached version | Other versions still broken | Use find -exec for ALL versions | | Add set -euo pipefail to hook scripts | -u kills script in minimal runtime | Use set -e or set -eo pipefail | | Test hooks only from your shell | Your shell has richer env than CC runtime | Test with minimal PATH and env | | Assume manual test = CC runtime | CC may pipe stdin differently, set timeout | Always verify with actual CC launch |