Global Hook Setup
One-time setup for global Claude Code hooks. These hooks work across all projects.
Purpose
Installs 8 project-agnostic hooks that enforce DESIGN-v2 determinism:
- State machine integrity
- Git hygiene
- Learning layer (outcome tracking)
- Session checkpoints
When to Use
| Situation | Action |
|---|---|
| First time setup | Run full setup |
| ~/.claude/hooks/ missing | Run full setup |
| After updating hooks | Re-run setup |
| Manual verification | Run verify script |
Quick Check
# Check if global hooks exist
ls ~/.claude/hooks/
Expected output:
verify-state-transition.py
require-commit-before-tested.py
require-outcome-update.py
link-feature-to-trace.py
markdownlint-fix.sh
remind-decision-trace.sh
session-end.sh
feature-commit.sh
Setup Steps
1. Install Hooks
~/.claude/skills/global-hook-setup/scripts/setup-global-hooks.sh
This creates:
~/.claude/hooks/directory- 8 hook files
- Executable permissions (chmod +x)
2. Verify Installation
~/.claude/skills/global-hook-setup/scripts/verify-global-hooks.sh
Hooks Installed
| Hook | Event | Purpose | Blocks? |
|---|---|---|---|
verify-state-transition.py | PreToolUse | Valid state transitions only | Yes |
require-commit-before-tested.py | PreToolUse | Git clean before tested | Yes |
require-outcome-update.py | PreToolUse | Update trace outcome | Yes |
link-feature-to-trace.py | PostToolUse | Auto-link features | No |
markdownlint-fix.sh | PostToolUse | Auto-fix .md linting | No |
remind-decision-trace.sh | SessionEnd | Remind to log decisions | No |
session-end.sh | SessionEnd | Checkpoint commit | No |
feature-commit.sh | CLI utility | Feature commit helper | N/A |
Note: feature-commit.sh is a CLI utility (not a hook). Use: ~/.claude/hooks/feature-commit.sh <feature-id> [message]
Settings.json Configuration
Setup script configures ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{"type": "command", "command": "python3 ~/.claude/hooks/verify-state-transition.py"},
{"type": "command", "command": "python3 ~/.claude/hooks/require-commit-before-tested.py"},
{"type": "command", "command": "python3 ~/.claude/hooks/require-outcome-update.py"}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{"type": "command", "command": "python3 ~/.claude/hooks/link-feature-to-trace.py"},
{"type": "command", "command": "/bin/bash ~/.claude/hooks/markdownlint-fix.sh"}
]
}
],
"SessionEnd": [
{
"hooks": [
{"type": "command", "command": "/bin/bash ~/.claude/hooks/session-end.sh"},
{"type": "command", "command": "/bin/bash ~/.claude/hooks/remind-decision-trace.sh"}
]
}
]
}
}
Exit Criteria (Code Verified)
# Directory exists
[ -d ~/.claude/hooks ]
# All hooks exist and executable
[ -x ~/.claude/hooks/verify-state-transition.py ]
[ -x ~/.claude/hooks/require-commit-before-tested.py ]
[ -x ~/.claude/hooks/require-outcome-update.py ]
[ -x ~/.claude/hooks/link-feature-to-trace.py ]
[ -x ~/.claude/hooks/markdownlint-fix.sh ]
[ -x ~/.claude/hooks/remind-decision-trace.sh ]
[ -x ~/.claude/hooks/session-end.sh ]
[ -x ~/.claude/hooks/feature-commit.sh ]
# Verify script passes
~/.claude/skills/global-hook-setup/scripts/verify-global-hooks.sh
Scripts
| Script | Purpose |
|---|---|
setup-global-hooks.sh | Main setup (install + configure + validate) |
configure-settings.py | Configure settings.json with hook entries |
validate-settings.py | Validate hooks configured in settings.json |
verify-global-hooks.sh | Verify hook files exist |
install-hooks.sh | Copy from templates |
Troubleshooting
| Problem | Solution |
|---|---|
| Hooks not found | Re-run setup script |
| Permission denied | Run: chmod +x ~/.claude/hooks/* |
| Verification fails | Check hook syntax, ensure python3 available |
| Already exists | Setup is idempotent, safe to re-run |
Next Steps
After global hooks: Set up project-specific hooks with project-hook-setup skill.