1# Hook Setup Guide
2 
3Configure automatic self-improvement triggers for AI coding agents.
4 
5## Overview
6 
7Hooks enable proactive learning capture by injecting reminders at key moments:
8- **UserPromptSubmit**: Reminder after each prompt to evaluate learnings
9- **PostToolUse (Bash)**: Error detection when commands fail
10 
11## Claude Code Setup
12 
13### Option 1: Project-Level Configuration
14 
15Create `.claude/settings.json` in your project root:
16 
17```json
18{
19  "hooks": {
20    "UserPromptSubmit": [
21      {
22        "matcher": "",
23        "hooks": [
24          {
25            "type": "command",
26            "command": "./skills/self-improvement/scripts/activator.sh"
27          }
28        ]
29      }
30    ],
31    "PostToolUse": [
32      {
33        "matcher": "Bash",
34        "hooks": [
35          {
36            "type": "command",
37            "command": "./skills/self-improvement/scripts/error-detector.sh"
38          }
39        ]
40      }
41    ]
42  }
43}
44```
45 
46### Option 2: User-Level Configuration
47 
48Add to `~/.claude/settings.json` for global activation:
49 
50```json
51{
52  "hooks": {
53    "UserPromptSubmit": [
54      {
55        "matcher": "",
56        "hooks": [
57          {
58            "type": "command",
59            "command": "~/.claude/skills/self-improvement/scripts/activator.sh"
60          }
61        ]
62      }
63    ]
64  }
65}
66```
67 
68### Minimal Setup (Activator Only)
69 
70For lower overhead, use only the UserPromptSubmit hook:
71 
72```json
73{
74  "hooks": {
75    "UserPromptSubmit": [
76      {
77        "matcher": "",
78        "hooks": [
79          {
80            "type": "command",
81            "command": "./skills/self-improvement/scripts/activator.sh"
82          }
83        ]
84      }
85    ]
86  }
87}
88```
89 
90## Codex CLI Setup
91 
92Codex uses the same hook system as Claude Code. Create `.codex/settings.json`:
93 
94```json
95{
96  "hooks": {
97    "UserPromptSubmit": [
98      {
99        "matcher": "",
100        "hooks": [
101          {
102            "type": "command",
103            "command": "./skills/self-improvement/scripts/activator.sh"
104          }
105        ]
106      }
107    ]
108  }
109}
110```
111 
112## GitHub Copilot Setup
113 
114Copilot doesn't support hooks directly. Instead, add guidance to `.github/copilot-instructions.md`:
115 
116```markdown
117## Self-Improvement
118 
119After completing tasks that involved:
120- Debugging non-obvious issues
121- Discovering workarounds
122- Learning project-specific patterns
123- Resolving unexpected errors
124 
125Consider logging the learning to `.learnings/` using the format from the self-improvement skill.
126 
127For high-value learnings that would benefit other sessions, consider skill extraction.
128```
129 
130## Verification
131 
132### Test Activator Hook
133 
1341. Enable the hook configuration
1352. Start a new Claude Code session
1363. Send any prompt
1374. Verify you see `<self-improvement-reminder>` in the context
138 
139### Test Error Detector Hook
140 
1411. Enable PostToolUse hook for Bash
1422. Run a command that fails: `ls /nonexistent/path`
1433. Verify you see `<error-detected>` reminder
144 
145### Dry Run Extract Script
146 
147```bash
148./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
149```
150 
151Expected output shows the skill scaffold that would be created.
152 
153## Troubleshooting
154 
155### Hook Not Triggering
156 
1571. **Check script permissions**: `chmod +x scripts/*.sh`
1582. **Verify path**: Use absolute paths or paths relative to project root
1593. **Check settings location**: Project vs user-level settings
1604. **Restart session**: Hooks are loaded at session start
161 
162### Permission Denied
163 
164```bash
165chmod +x ./skills/self-improvement/scripts/activator.sh
166chmod +x ./skills/self-improvement/scripts/error-detector.sh
167chmod +x ./skills/self-improvement/scripts/extract-skill.sh
168```
169 
170### Script Not Found
171 
172If using relative paths, ensure you're in the correct directory or use absolute paths:
173 
174```json
175{
176  "command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
177}
178```
179 
180### Too Much Overhead
181 
182If the activator feels intrusive:
183 
1841. **Use minimal setup**: Only UserPromptSubmit, skip PostToolUse
1852. **Add matcher filter**: Only trigger for certain prompts:
186 
187```json
188{
189  "matcher": "fix|debug|error|issue",
190  "hooks": [...]
191}
192```
193 
194## Hook Output Budget
195 
196The activator is designed to be lightweight:
197- **Target**: ~50-100 tokens per activation
198- **Content**: Structured reminder, not verbose instructions
199- **Format**: XML tags for easy parsing
200 
201If you need to reduce overhead further, you can edit `activator.sh` to output less text.
202 
203## Security Considerations
204 
205- Hook scripts run with the same permissions as Claude Code
206- Scripts only output text; they don't modify files or run commands
207- Error detector reads `CLAUDE_TOOL_OUTPUT` environment variable
208- Treat `CLAUDE_TOOL_OUTPUT` as potentially sensitive; do not log or forward it verbatim unless the user explicitly wants that detail
209- All scripts are opt-in (you must configure them explicitly)
210- Recommended default: enable `UserPromptSubmit` only, and add `PostToolUse` only when you want error-pattern reminders from command output
211 
212## Disabling Hooks
213 
214To temporarily disable without removing configuration:
215 
2161. **Comment out in settings**:
217```json
218{
219  "hooks": {
220    // "UserPromptSubmit": [...]
221  }
222}
223```
224 
2252. **Or delete the settings file**: Hooks won't run without configuration
226