Documentation Index
Fetch the complete documentation index at: https://mintlify.com/swt-labs/vibe-better-with-claude-code-vbw/llms.txt
Use this file to discover all available pages before exploring further.
VBW installs 22 hook handlers across 11 Claude Code event types. Hooks run automatically after installation — no configuration needed. They execute as bash subprocesses at zero model token cost.
All hooks route through hook-wrapper.sh, which provides graceful degradation: if a hook script is missing or fails unexpectedly, the wrapper logs the error to .vbw-planning/.hook-errors.log and exits 0. No hook can break a session.
Verification hooks
Verification hooks enforce quality gates on agent output — SUMMARY.md structure, commit format, frontmatter, task completion, and agent lifecycle.
| Event | Handler | What it does |
|---|
PostToolUse (Write|Edit) | validate-summary.sh | Validates SUMMARY.md structure on write |
PostToolUse (Write|Edit) | validate-frontmatter.sh | Validates frontmatter descriptions |
PostToolUse (Bash) | validate-commit.sh | Checks conventional commit format |
PostToolUse (Write|Edit|Bash) | skill-hook-dispatch.sh | Dispatches skill-defined hook handlers |
PostToolUse (Write|Edit) | state-updater.sh | Updates execution state |
SubagentStart | agent-start.sh | Writes agent marker (role normalization, concurrency-safe) |
SubagentStop | agent-stop.sh | Validates SUMMARY.md, cleans markers, corruption recovery |
TeammateIdle | qa-gate.sh | Tiered SUMMARY.md gate (1-plan grace, 2+ gap blocks) |
TaskCompleted | task-verify.sh | Verifies task-related commit exists via keyword matching |
Security hooks
Security hooks intercept tool calls before they reach the shell or filesystem. They are fail-closed: any parse error or unexpected condition blocks the call rather than allowing it through.
| Event | Handler | What it does |
|---|
PreToolUse (Bash) | bash-guard.sh | Blocks destructive bash commands (40+ patterns) |
PreToolUse (Read|Glob|Grep|Write|Edit) | security-filter.sh | Blocks access to .env, private keys, and credential files |
PreToolUse (Write|Edit) | file-guard.sh | Enforces plan file boundaries; blocks writes to files not declared in the active plan |
Lifecycle hooks
Lifecycle hooks manage session and agent state across the full session arc — from start through compaction to stop.
| Event | Handler | What it does |
|---|
SessionStart | session-start.sh | Detects project state, checks map staleness |
SessionStart | map-staleness.sh | Checks whether the codebase map needs a refresh |
SessionStart (matcher: compact) | post-compact.sh | Verifies critical context survived compaction |
PreCompact | compaction-instructions.sh | Injects agent-specific compaction priorities |
Stop | session-stop.sh | Logs session metrics, persists cost ledger |
Stop | agent-health.sh cleanup | Cleans up agent health markers on session end |
UserPromptSubmit | prompt-preflight.sh | Pre-flight prompt validation |
Notification | notification-log.sh | Logs teammate communication |
Health tracking hooks
Agent health hooks track the lifecycle of each teammate for monitoring and recovery.
| Event | Handler | What it does |
|---|
SubagentStart | agent-health.sh start | Records agent start event |
SubagentStop | agent-health.sh stop | Records agent stop event |
TeammateIdle | agent-health.sh idle | Records idle event for stuck-agent detection |
Custom hooks via skills
Skills can register their own hook handlers through skill-hook-dispatch.sh. When a PostToolUse or PreToolUse event fires, the dispatcher checks for skill-specific hook scripts and calls them in sequence.
To add a hook in a skill, define the handler script in your skill directory and register it in the skill manifest. The dispatcher resolves skill hooks from the plugin cache at runtime — no changes to hooks.json required.
Run /vbw:config with no arguments to see active skill-hook mappings alongside all other settings.
How hooks are resolved
Every hook command in hooks.json uses a multi-step resolution to find hook-wrapper.sh:
- Plugin cache (
~/.claude/plugins/cache/vbw-marketplace/vbw/)
CLAUDE_PLUGIN_ROOT environment variable (for --plugin-dir installs)/tmp/.vbw-plugin-root-link-*/ symlinks--plugin-dir from the running claude process arguments
If none of those paths resolve to an existing file, the hook exits 0 silently. This ensures VBW hooks never block a session when the plugin root is unavailable.