cc-safe-setup 11.7.0 → 11.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/README.md +15 -1
  2. package/package.json +1 -1
  3. package/.claude/session-snapshot.md +0 -25
  4. package/cc-safe-setup-export.json +0 -321
  5. package/docs/README.ja.md +0 -64
  6. package/docs/ROADMAP.md +0 -83
  7. package/docs/builder.html +0 -283
  8. package/docs/by-example.html +0 -234
  9. package/docs/cheatsheet.html +0 -187
  10. package/docs/ecosystem.html +0 -223
  11. package/docs/faq.html +0 -244
  12. package/docs/hooks-cheatsheet.html +0 -319
  13. package/docs/hub.html +0 -155
  14. package/docs/index-legacy.html +0 -685
  15. package/docs/index.html +0 -271
  16. package/docs/matrix.html +0 -139
  17. package/docs/migration-guide.html +0 -198
  18. package/docs/settings-reference.html +0 -317
  19. package/docs/troubleshooting.html +0 -189
  20. package/examples/go/destructive_guard.go +0 -69
  21. package/examples/python/__pycache__/destructive_guard.cpython-312.pyc +0 -0
  22. package/examples/python/__pycache__/secret_guard.cpython-312.pyc +0 -0
  23. package/examples/rust/destructive_guard.rs +0 -72
  24. package/examples/typescript/destructive-guard.ts +0 -64
package/docs/cheatsheet.html DELETED
@@ -1,187 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Claude Code Hooks Cheat Sheet</title>
7
- <style>
8
- @media print { body { padding: 0; background: #fff; color: #000; font-size: 9px; } .no-print { display: none; } h1 { font-size: 14px; } h2 { font-size: 11px; } pre { font-size: 8px; border: 1px solid #ccc; } .col { break-inside: avoid; } }
9
- @media screen { body { background: #0d1117; color: #c9d1d9; padding: 1rem; } pre { background: #161b22; border: 1px solid #30363d; } h1 { color: #f0f6fc; } h2 { color: #f0f6fc; } a { color: #58a6ff; } }
10
- * { box-sizing: border-box; margin: 0; padding: 0; }
11
- body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', monospace; font-size: 11px; line-height: 1.4; }
12
- .container { max-width: 900px; margin: 0 auto; columns: 2; column-gap: 1.5rem; }
13
- h1 { font-size: 16px; margin-bottom: 0.3rem; text-align: center; column-span: all; }
14
- .subtitle { text-align: center; margin-bottom: 0.8rem; font-size: 10px; opacity: 0.7; column-span: all; }
15
- h2 { font-size: 12px; margin: 0.6rem 0 0.3rem; border-bottom: 1px solid #30363d; padding-bottom: 0.15rem; }
16
- pre { padding: 0.4rem; border-radius: 4px; overflow-x: auto; font-size: 9.5px; margin: 0.2rem 0 0.4rem; white-space: pre-wrap; word-break: break-all; }
17
- .col { break-inside: avoid; margin-bottom: 0.3rem; }
18
- table { width: 100%; border-collapse: collapse; font-size: 9.5px; margin: 0.2rem 0; }
19
- th, td { text-align: left; padding: 0.15rem 0.3rem; border-bottom: 1px solid #21262d; }
20
- th { font-weight: 600; }
21
- code { font-size: 9px; padding: 0.1rem 0.2rem; border-radius: 2px; }
22
- @media screen { code { background: #161b22; } }
23
- .footer { text-align: center; font-size: 8px; opacity: 0.5; margin-top: 0.5rem; column-span: all; }
24
- </style>
25
- </head>
26
- <body>
27
- <h1>Claude Code Hooks Cheat Sheet</h1>
28
- <p class="subtitle">Quick reference · Print this page (Ctrl+P) · <a href="https://github.com/yurukusa/cc-safe-setup" class="no-print">github.com/yurukusa/cc-safe-setup</a></p>
29
-
30
- <div class="container">
31
-
32
- <div class="col">
33
- <h2>Hook Lifecycle</h2>
34
- <pre>Prompt → PreToolUse → Tool Executes → PostToolUse → Stop
35
- ↑ block here ↑ check here ↑ log here</pre>
36
- </div>
37
-
38
- <div class="col">
39
- <h2>Exit Codes</h2>
40
- <table>
41
- <tr><th>Code</th><th>Meaning</th></tr>
42
- <tr><td><code>0</code></td><td>Allow (or no opinion)</td></tr>
43
- <tr><td><code>2</code></td><td><strong>Block</strong> — tool call cancelled</td></tr>
44
- <tr><td>other</td><td>Error (treated as allow)</td></tr>
45
- </table>
46
- </div>
47
-
48
- <div class="col">
49
- <h2>Hook Events</h2>
50
- <table>
51
- <tr><th>Event</th><th>Matcher</th><th>Use</th></tr>
52
- <tr><td>PreToolUse</td><td>Bash</td><td>Block commands</td></tr>
53
- <tr><td>PostToolUse</td><td>Edit|Write</td><td>Syntax check</td></tr>
54
- <tr><td>PostToolUse</td><td>(empty)</td><td>All tools</td></tr>
55
- <tr><td>Stop</td><td>(empty)</td><td>Session end</td></tr>
56
- <tr><td>UserPromptSubmit</td><td>—</td><td>Validate input</td></tr>
57
- </table>
58
- </div>
59
-
60
- <div class="col">
61
- <h2>settings.json Structure</h2>
62
- <pre>{
63
- "hooks": {
64
- "PreToolUse": [{
65
- "matcher": "Bash",
66
- "hooks": [{
67
- "type": "command",
68
- "command": "~/.claude/hooks/guard.sh"
69
- }]
70
- }]
71
- }
72
- }</pre>
73
- </div>
74
-
75
- <div class="col">
76
- <h2>Minimal Block Hook</h2>
77
- <pre>#!/bin/bash
78
- COMMAND=$(cat | jq -r '.tool_input.command // empty')
79
- [ -z "$COMMAND" ] && exit 0
80
- if echo "$COMMAND" | grep -qE 'PATTERN'; then
81
- echo "BLOCKED: reason" >&2
82
- exit 2
83
- fi
84
- exit 0</pre>
85
- </div>
86
-
87
- <div class="col">
88
- <h2>Auto-Approve Hook</h2>
89
- <pre>#!/bin/bash
90
- COMMAND=$(cat | jq -r '.tool_input.command // empty')
91
- [ -z "$COMMAND" ] && exit 0
92
- if echo "$COMMAND" | grep -qE '^\s*git\s+(status|log|diff)'; then
93
- jq -n '{
94
- "hookSpecificOutput": {
95
- "hookEventName": "PreToolUse",
96
- "permissionDecision": "allow"
97
- }
98
- }'
99
- fi
100
- exit 0</pre>
101
- </div>
102
-
103
- <div class="col">
104
- <h2>PostToolUse Syntax Check</h2>
105
- <pre>#!/bin/bash
106
- FILE=$(cat | jq -r '.tool_input.file_path // empty')
107
- [ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0
108
- case "${FILE##*.}" in
109
- py) python3 -m py_compile "$FILE" 2>&1 ;;
110
- sh) bash -n "$FILE" 2>&1 ;;
111
- json) jq empty "$FILE" 2>&1 ;;
112
- js) node --check "$FILE" 2>&1 ;;
113
- esac
114
- exit 0</pre>
115
- </div>
116
-
117
- <div class="col">
118
- <h2>Modify Input</h2>
119
- <pre>#!/bin/bash
120
- # Strip comments from bash commands
121
- COMMAND=$(cat | jq -r '.tool_input.command // empty')
122
- CLEAN=$(echo "$COMMAND" | sed '/^#/d; /^$/d')
123
- [ "$CLEAN" = "$COMMAND" ] && exit 0
124
- jq -n --arg cmd "$CLEAN" '{
125
- "hookSpecificOutput": {
126
- "hookEventName": "PreToolUse",
127
- "updatedInput": {"command": $cmd}
128
- }
129
- }'</pre>
130
- </div>
131
-
132
- <div class="col">
133
- <h2>stdin JSON Reference</h2>
134
- <table>
135
- <tr><th>Event</th><th>Key Fields</th></tr>
136
- <tr><td>PreToolUse (Bash)</td><td><code>.tool_input.command</code></td></tr>
137
- <tr><td>PreToolUse (Edit)</td><td><code>.tool_input.file_path</code></td></tr>
138
- <tr><td>PostToolUse</td><td><code>.tool_input.file_path</code></td></tr>
139
- <tr><td>Stop</td><td><code>.stop_reason</code></td></tr>
140
- <tr><td>UserPromptSubmit</td><td><code>.prompt</code></td></tr>
141
- </table>
142
- </div>
143
-
144
- <div class="col">
145
- <h2>Test a Hook</h2>
146
- <pre># Manual test
147
- echo '{"tool_input":{"command":"rm -rf /"}}' \
148
- | bash ~/.claude/hooks/guard.sh
149
- echo $? # 2 = blocked
150
-
151
- # Auto-test
152
- npx cc-hook-test ~/.claude/hooks/guard.sh</pre>
153
- </div>
154
-
155
- <div class="col">
156
- <h2>Quick Setup Commands</h2>
157
- <table>
158
- <tr><td><code>npx cc-safe-setup</code></td><td>Install 8 hooks</td></tr>
159
- <tr><td><code>--create "desc"</code></td><td>Generate hook</td></tr>
160
- <tr><td><code>--audit</code></td><td>Safety score</td></tr>
161
- <tr><td><code>--lint</code></td><td>Config analysis</td></tr>
162
- <tr><td><code>--doctor</code></td><td>Diagnose issues</td></tr>
163
- <tr><td><code>--watch</code></td><td>Live dashboard</td></tr>
164
- <tr><td><code>--stats</code></td><td>Block statistics</td></tr>
165
- <tr><td><code>--verify</code></td><td>Test all hooks</td></tr>
166
- <tr><td><code>--export</code></td><td>Share with team</td></tr>
167
- </table>
168
- </div>
169
-
170
- <div class="col">
171
- <h2>Common Patterns</h2>
172
- <table>
173
- <tr><th>Block</th><th>Pattern</th></tr>
174
- <tr><td>rm -rf /</td><td><code>rm\s+(-[rf]+\s+)*/</code></td></tr>
175
- <tr><td>force push</td><td><code>git\s+push.*--force</code></td></tr>
176
- <tr><td>push main</td><td><code>git\s+push.*main</code></td></tr>
177
- <tr><td>.env commit</td><td><code>git\s+add.*\.env</code></td></tr>
178
- <tr><td>git reset</td><td><code>git\s+reset\s+--hard</code></td></tr>
179
- <tr><td>DB wipe</td><td><code>migrate:fresh|DROP\s+DB</code></td></tr>
180
- </table>
181
- </div>
182
-
183
- </div>
184
-
185
- <p class="footer">cc-safe-setup v3.2.0 · 20 recipes: <a href="https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md" class="no-print">COOKBOOK.md</a> · Full ref: <a href="https://github.com/yurukusa/cc-safe-setup/blob/main/SETTINGS_REFERENCE.md" class="no-print">SETTINGS_REFERENCE.md</a></p>
186
- </body>
187
- </html>
package/docs/ecosystem.html DELETED
@@ -1,223 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Claude Code Hooks Ecosystem</title>
7
- <meta name="description" content="Compare all Claude Code hook projects — features, language, stars, and installation methods.">
8
- <style>
9
- * { box-sizing: border-box; margin: 0; padding: 0; }
10
- body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0d1117; color: #c9d1d9; min-height: 100vh; padding: 2rem; }
11
- .container { max-width: 900px; margin: 0 auto; }
12
- h1 { font-size: 1.5rem; margin-bottom: 0.5rem; color: #f0f6fc; }
13
- h2 { font-size: 1.2rem; margin: 2rem 0 1rem; color: #f0f6fc; }
14
- .subtitle { color: #8b949e; margin-bottom: 2rem; }
15
- a { color: #58a6ff; text-decoration: none; }
16
- a:hover { text-decoration: underline; }
17
- table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.85rem; }
18
- th { text-align: left; padding: 0.6rem 0.5rem; border-bottom: 2px solid #30363d; color: #f0f6fc; font-weight: 600; }
19
- td { padding: 0.5rem; border-bottom: 1px solid #21262d; vertical-align: top; }
20
- tr:hover td { background: #161b22; }
21
- .badge { display: inline-block; padding: 0.15rem 0.4rem; border-radius: 3px; font-size: 0.7rem; font-weight: bold; margin-right: 0.3rem; }
22
- .badge-bash { background: #1f6feb22; color: #58a6ff; border: 1px solid #1f6feb44; }
23
- .badge-js { background: #f0e68c22; color: #f0e68c; border: 1px solid #f0e68c44; }
24
- .badge-py { background: #3fb95022; color: #3fb950; border: 1px solid #3fb95044; }
25
- .badge-ts { background: #388bfd22; color: #388bfd; border: 1px solid #388bfd44; }
26
- .check { color: #3fb950; }
27
- .cross { color: #484f58; }
28
- .note { color: #8b949e; font-size: 0.8rem; margin-top: 2rem; }
29
- .footer { color: #484f58; font-size: 0.75rem; margin-top: 3rem; text-align: center; }
30
- </style>
31
- </head>
32
- <body>
33
- <div class="container">
34
- <h1>Claude Code Hooks Ecosystem</h1>
35
- <p class="subtitle">A neutral comparison of all major hook projects. Pick the one that fits your stack.</p>
36
-
37
- <h2>Projects at a Glance</h2>
38
- <table>
39
- <tr>
40
- <th>Project</th>
41
- <th>Language</th>
42
- <th>Hooks</th>
43
- <th>Install</th>
44
- <th>Focus</th>
45
- </tr>
46
- <tr>
47
- <td><a href="https://github.com/kenryu42/claude-code-safety-net">safety-net</a></td>
48
- <td><span class="badge badge-ts">TS</span></td>
49
- <td>5 rules</td>
50
- <td>npx</td>
51
- <td>Destructive command blocking with configurable severity</td>
52
- </tr>
53
- <tr>
54
- <td><a href="https://github.com/yurukusa/cc-safe-setup">cc-safe-setup</a></td>
55
- <td><span class="badge badge-bash">Bash</span></td>
56
- <td>8 + 26 examples</td>
57
- <td>npx</td>
58
- <td>Full safety suite: block, audit, create, learn, watch, doctor</td>
59
- </tr>
60
- <tr>
61
- <td><a href="https://github.com/karanb192/claude-code-hooks">karanb192/hooks</a></td>
62
- <td><span class="badge badge-js">JS</span></td>
63
- <td>5+</td>
64
- <td>copy files</td>
65
- <td>JS hooks with configurable safety levels and logging</td>
66
- </tr>
67
- <tr>
68
- <td><a href="https://github.com/disler/claude-code-hooks-mastery">hooks-mastery</a></td>
69
- <td><span class="badge badge-py">Python</span></td>
70
- <td>12</td>
71
- <td>copy files</td>
72
- <td>Python hooks covering all hook events + LLM integration</td>
73
- </tr>
74
- <tr>
75
- <td><a href="https://github.com/lasso-security/claude-hooks">lasso-security</a></td>
76
- <td><span class="badge badge-py">Python</span></td>
77
- <td>1 skill</td>
78
- <td>install.sh</td>
79
- <td>Prompt injection defense using YAML pattern matching</td>
80
- </tr>
81
- <tr>
82
- <td><a href="https://github.com/johnlindquist/claude-hooks">johnlindquist</a></td>
83
- <td><span class="badge badge-ts">TS</span></td>
84
- <td>8</td>
85
- <td>Bun</td>
86
- <td>TypeScript hooks with Bun runtime, notification focus</td>
87
- </tr>
88
- <tr>
89
- <td><a href="https://github.com/yurukusa/claude-code-hooks">claude-code-hooks</a></td>
90
- <td><span class="badge badge-bash">Bash</span></td>
91
- <td>16 + 5 templates</td>
92
- <td>install.sh</td>
93
- <td>Production hooks from 1000+ hours autonomous operation</td>
94
- </tr>
95
- </table>
96
-
97
- <h2>Feature Comparison</h2>
98
- <table>
99
- <tr>
100
- <th>Feature</th>
101
- <th>safety-net</th>
102
- <th>cc-safe-setup</th>
103
- <th>karanb192</th>
104
- <th>mastery</th>
105
- <th>lasso</th>
106
- </tr>
107
- <tr>
108
- <td>rm -rf blocker</td>
109
- <td class="check">&#10003;</td>
110
- <td class="check">&#10003;</td>
111
- <td class="check">&#10003;</td>
112
- <td class="check">&#10003;</td>
113
- <td class="cross">-</td>
114
- </tr>
115
- <tr>
116
- <td>Branch push guard</td>
117
- <td class="check">&#10003;</td>
118
- <td class="check">&#10003;</td>
119
- <td class="cross">-</td>
120
- <td class="cross">-</td>
121
- <td class="cross">-</td>
122
- </tr>
123
- <tr>
124
- <td>Secret leak prevention</td>
125
- <td class="cross">-</td>
126
- <td class="check">&#10003;</td>
127
- <td class="check">&#10003;</td>
128
- <td class="cross">-</td>
129
- <td class="cross">-</td>
130
- </tr>
131
- <tr>
132
- <td>Syntax validation</td>
133
- <td class="cross">-</td>
134
- <td class="check">&#10003;</td>
135
- <td class="cross">-</td>
136
- <td class="cross">-</td>
137
- <td class="cross">-</td>
138
- </tr>
139
- <tr>
140
- <td>Context monitor</td>
141
- <td class="cross">-</td>
142
- <td class="check">&#10003;</td>
143
- <td class="cross">-</td>
144
- <td class="cross">-</td>
145
- <td class="cross">-</td>
146
- </tr>
147
- <tr>
148
- <td>Prompt injection defense</td>
149
- <td class="cross">-</td>
150
- <td class="cross">-</td>
151
- <td class="cross">-</td>
152
- <td class="cross">-</td>
153
- <td class="check">&#10003;</td>
154
- </tr>
155
- <tr>
156
- <td>Auto-approve safe cmds</td>
157
- <td class="cross">-</td>
158
- <td class="check">&#10003;</td>
159
- <td class="cross">-</td>
160
- <td class="cross">-</td>
161
- <td class="cross">-</td>
162
- </tr>
163
- <tr>
164
- <td>Database wipe guard</td>
165
- <td class="cross">-</td>
166
- <td class="check">&#10003;</td>
167
- <td class="cross">-</td>
168
- <td class="check">&#10003;</td>
169
- <td class="cross">-</td>
170
- </tr>
171
- <tr>
172
- <td>Safety audit/score</td>
173
- <td class="cross">-</td>
174
- <td class="check">&#10003;</td>
175
- <td class="cross">-</td>
176
- <td class="cross">-</td>
177
- <td class="cross">-</td>
178
- </tr>
179
- <tr>
180
- <td>Hook generator (NL)</td>
181
- <td class="cross">-</td>
182
- <td class="check">&#10003;</td>
183
- <td class="cross">-</td>
184
- <td class="cross">-</td>
185
- <td class="cross">-</td>
186
- </tr>
187
- <tr>
188
- <td>Zero dependencies</td>
189
- <td class="cross">TS</td>
190
- <td class="check">jq only</td>
191
- <td class="check">Node</td>
192
- <td class="cross">uv/pip</td>
193
- <td class="cross">uv</td>
194
- </tr>
195
- <tr>
196
- <td>GitHub Action</td>
197
- <td class="cross">-</td>
198
- <td class="check">&#10003;</td>
199
- <td class="cross">-</td>
200
- <td class="cross">-</td>
201
- <td class="cross">-</td>
202
- </tr>
203
- </table>
204
-
205
- <p class="note">This page is maintained by the cc-safe-setup team but aims to be neutral. PRs welcome for corrections: <a href="https://github.com/yurukusa/cc-safe-setup">GitHub</a></p>
206
-
207
- <h2>Which Should I Use?</h2>
208
- <table>
209
- <tr><th>If you want...</th><th>Use this</th></tr>
210
- <tr><td>Quickest setup, bash-based</td><td><code>npx cc-safe-setup</code></td></tr>
211
- <tr><td>TypeScript hooks, configurable severity</td><td>safety-net</td></tr>
212
- <tr><td>Python hooks, all event types</td><td>hooks-mastery</td></tr>
213
- <tr><td>Prompt injection protection</td><td>lasso-security</td></tr>
214
- <tr><td>JS hooks with logging</td><td>karanb192</td></tr>
215
- <tr><td>Complete ops toolkit (hooks + templates)</td><td>claude-code-hooks</td></tr>
216
- </table>
217
-
218
- <div class="footer">
219
- Last updated: March 2026 · <a href="https://yurukusa.github.io/cc-safe-setup/">Safety Audit Tool</a> · <a href="https://github.com/yurukusa/cc-safe-setup">Source</a>
220
- </div>
221
- </div>
222
- </body>
223
- </html>
package/docs/faq.html DELETED
@@ -1,244 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Claude Code Hooks FAQ — Every Question Answered</title>
7
- <meta name="description" content="Answers to every common question about Claude Code hooks. Why hooks? How do they work? What about performance?">
8
- <style>
9
- *{box-sizing:border-box;margin:0;padding:0}
10
- body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#0d1117;color:#c9d1d9;padding:1.5rem;line-height:1.6}
11
- .c{max-width:800px;margin:0 auto}
12
- h1{color:#f0f6fc;font-size:1.5rem;margin-bottom:.3rem}
13
- .sub{color:#8b949e;font-size:.85rem;margin-bottom:1.5rem}
14
- a{color:#58a6ff;text-decoration:none}
15
- code{background:#161b22;padding:.15rem .3rem;border-radius:3px;font-size:.85rem}
16
- pre{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:.7rem;font-size:.8rem;color:#e6edf3;overflow-x:auto;margin:.4rem 0}
17
- details{background:#161b22;border:1px solid #30363d;border-radius:6px;margin:.5rem 0}
18
- summary{padding:.7rem .9rem;cursor:pointer;font-weight:600;color:#f0f6fc;font-size:.9rem;list-style:none}
19
- summary::before{content:"▸ ";color:#58a6ff}
20
- details[open] summary::before{content:"▾ "}
21
- details[open] summary{border-bottom:1px solid #21262d}
22
- .answer{padding:.7rem .9rem;font-size:.85rem}
23
- .answer p{margin:.4rem 0}
24
- .cat{color:#58a6ff;font-size:.75rem;font-weight:bold;text-transform:uppercase;margin:1.5rem 0 .5rem;letter-spacing:.05em}
25
- .footer{text-align:center;color:#484f58;font-size:.7rem;margin-top:2rem;padding-top:1rem;border-top:1px solid #21262d}
26
- .quick{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:.8rem;margin:.8rem 0;font-size:.82rem}
27
- </style>
28
- </head>
29
- <body>
30
- <div class="c">
31
-
32
- <h1>Claude Code Hooks FAQ</h1>
33
- <p class="sub">Every question we've been asked, answered. <a href="https://docs.anthropic.com/en/docs/claude-code/hooks">Official docs</a></p>
34
-
35
- <div class="quick">
36
- <strong>TL;DR:</strong> Hooks are shell scripts that run before/after Claude Code tools. <code>exit 2</code> = block. <code>exit 0</code> = allow. Install 8 safety hooks: <code>npx cc-safe-setup</code>
37
- </div>
38
-
39
- <div class="cat">Basics</div>
40
-
41
- <details>
42
- <summary>What are Claude Code hooks?</summary>
43
- <div class="answer">
44
- <p>Shell scripts that run at specific points in Claude Code's lifecycle:</p>
45
- <ul>
46
- <li><strong>PreToolUse</strong> — before any tool (Bash, Edit, Write) executes</li>
47
- <li><strong>PostToolUse</strong> — after a tool completes</li>
48
- <li><strong>Stop</strong> — when Claude finishes responding</li>
49
- </ul>
50
- <p>They're configured in <code>~/.claude/settings.json</code> and enforced at the process level — the model cannot bypass them.</p>
51
- </div>
52
- </details>
53
-
54
- <details>
55
- <summary>How is this different from CLAUDE.md?</summary>
56
- <div class="answer">
57
- <p><strong>CLAUDE.md</strong> is a prompt-level instruction. It works well at the start of a session but degrades as context fills up. After 100+ tool calls, Claude may "forget" rules.</p>
58
- <p><strong>Hooks</strong> run on every single tool call, enforced by the runtime. Even if Claude wants to ignore them, <code>exit 2</code> physically prevents the action.</p>
59
- <p>Use both: CLAUDE.md for guidelines, hooks for hard constraints.</p>
60
- </div>
61
- </details>
62
-
63
- <details>
64
- <summary>Do I need to know bash to use hooks?</summary>
65
- <div class="answer">
66
- <p>Not really. You can:</p>
67
- <ol>
68
- <li>Use <code>npx cc-safe-setup</code> to install pre-built hooks (zero coding)</li>
69
- <li>Use <code>npx cc-safe-setup --create "your description"</code> to generate hooks from English</li>
70
- <li>Use the <a href="builder.html">Hook Builder</a> web tool</li>
71
- <li>Copy-paste from the <a href="hooks-cheatsheet.html">Cheat Sheet</a></li>
72
- </ol>
73
- </div>
74
- </details>
75
-
76
- <div class="cat">How It Works</div>
77
-
78
- <details>
79
- <summary>What does exit code 2 do?</summary>
80
- <div class="answer">
81
- <p><code>exit 2</code> blocks the tool call. The model receives a message that the operation was blocked and must try a different approach.</p>
82
- <p><code>exit 0</code> allows the operation (default).</p>
83
- <p><code>exit 1</code> is treated as a hook error and is silently ignored — don't use it for blocking.</p>
84
- </div>
85
- </details>
86
-
87
- <details>
88
- <summary>What JSON does the hook receive on stdin?</summary>
89
- <div class="answer">
90
- <p>For <strong>PreToolUse</strong> (Bash):</p>
91
- <pre><code>{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}</code></pre>
92
- <p>For <strong>PreToolUse</strong> (Edit):</p>
93
- <pre><code>{"tool_name":"Edit","tool_input":{"file_path":"app.js","old_string":"...","new_string":"..."}}</code></pre>
94
- <p>For <strong>PostToolUse</strong>:</p>
95
- <pre><code>{"tool_name":"Bash","tool_input":{"command":"ls"},"tool_result":"file1.txt\nfile2.txt"}</code></pre>
96
- <p>Extract with: <code>cat | jq -r '.tool_input.command // empty'</code></p>
97
- </div>
98
- </details>
99
-
100
- <details>
101
- <summary>Can I auto-approve commands via hooks?</summary>
102
- <div class="answer">
103
- <p>Yes. Output JSON to stdout:</p>
104
- <pre><code>echo '{"decision":"approve","reason":"Safe test command"}'
105
- exit 0</code></pre>
106
- <p>This skips the permission prompt for that specific tool call.</p>
107
- </div>
108
- </details>
109
-
110
- <details>
111
- <summary>What does the "matcher" field do?</summary>
112
- <div class="answer">
113
- <p>It's a regex matched against the tool name:</p>
114
- <ul>
115
- <li><code>"Bash"</code> — only Bash commands</li>
116
- <li><code>"Edit|Write"</code> — file modifications</li>
117
- <li><code>""</code> (empty) — matches ALL tools</li>
118
- <li><code>"Read"</code> — file reads</li>
119
- </ul>
120
- </div>
121
- </details>
122
-
123
- <div class="cat">Performance & Safety</div>
124
-
125
- <details>
126
- <summary>Do hooks slow down Claude Code?</summary>
127
- <div class="answer">
128
- <p>No. Each hook runs in ~5ms (bash + jq). Even with 10 hooks chained, total overhead is <50ms per tool call — imperceptible compared to the API latency.</p>
129
- <p>You can measure: <code>npx cc-safe-setup --benchmark</code></p>
130
- </div>
131
- </details>
132
-
133
- <details>
134
- <summary>Can Claude disable or modify hooks?</summary>
135
- <div class="answer">
136
- <p>Claude can edit <code>settings.json</code> via the Edit tool. To prevent this:</p>
137
- <pre><code>npx cc-safe-setup --install-example protect-claudemd</code></pre>
138
- <p>This hook blocks edits to CLAUDE.md and settings files.</p>
139
- </div>
140
- </details>
141
-
142
- <details>
143
- <summary>What if my hook has a bug?</summary>
144
- <div class="answer">
145
- <p>If a hook exits with code 1 (error), Claude Code treats it as a hook failure and <strong>ignores it</strong> — the tool call proceeds. This is by design: buggy hooks don't block all operations.</p>
146
- <p>Only <code>exit 2</code> blocks. If your hook accidentally exits 2 for everything, use <code>npx cc-safe-setup --doctor</code> to diagnose.</p>
147
- </div>
148
- </details>
149
-
150
- <details>
151
- <summary>Can I use Python/TypeScript instead of bash?</summary>
152
- <div class="answer">
153
- <p>Yes. The <code>command</code> field can run anything:</p>
154
- <pre><code>{"type": "command", "command": "python3 ~/.claude/hooks/my-guard.py"}</code></pre>
155
- <p>cc-safe-setup includes Python examples: <code>examples/python/destructive_guard.py</code></p>
156
- <p>For TypeScript, see <a href="https://www.npmjs.com/package/@anthropic-ai/claude-code-safety-net">safety-net</a> (1,185★).</p>
157
- </div>
158
- </details>
159
-
160
- <div class="cat">Common Issues</div>
161
-
162
- <details>
163
- <summary>My hook doesn't fire — what's wrong?</summary>
164
- <div class="answer">
165
- <p>Run diagnostics: <code>npx cc-safe-setup --doctor</code></p>
166
- <p>Common causes:</p>
167
- <ol>
168
- <li><strong>Not executable:</strong> <code>chmod +x ~/.claude/hooks/your-hook.sh</code></li>
169
- <li><strong>Missing shebang:</strong> First line must be <code>#!/bin/bash</code></li>
170
- <li><strong>Wrong matcher:</strong> <code>"Bash"</code> won't fire for Edit/Write tools</li>
171
- <li><strong>settings.json syntax error:</strong> Validate with <code>python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"</code></li>
172
- <li><strong>jq not installed:</strong> <code>which jq</code> — install if missing</li>
173
- </ol>
174
- <p>Quick fix: <code>npx cc-safe-setup --quickfix</code></p>
175
- </div>
176
- </details>
177
-
178
- <details>
179
- <summary>My hook blocks everything</summary>
180
- <div class="answer">
181
- <p>Your hook is returning <code>exit 2</code> for all inputs. Debug by testing manually:</p>
182
- <pre><code>echo '{"tool_input":{"command":"ls"}}' | bash ~/.claude/hooks/your-hook.sh
183
- echo "Exit: $?"</code></pre>
184
- <p>If it exits 2 for <code>ls</code>, your regex is too broad. Check the <code>grep -qE</code> pattern.</p>
185
- </div>
186
- </details>
187
-
188
- <details>
189
- <summary>Multiple hooks — does order matter?</summary>
190
- <div class="answer">
191
- <p>Hooks in the same group run sequentially. If any hook exits 2, the tool call is blocked — remaining hooks don't run.</p>
192
- <p><strong>Important:</strong> Each hook consumes stdin. If you chain multiple hooks in the same group, the second hook gets empty stdin. Put each hook in a separate matcher group, or use <code>tee</code>.</p>
193
- </div>
194
- </details>
195
-
196
- <details>
197
- <summary>Can hooks access the internet?</summary>
198
- <div class="answer">
199
- <p>Yes. Hooks are regular shell scripts — they can make HTTP requests, send notifications, write to databases, etc.</p>
200
- <p>Example: send a Slack notification when a dangerous command is blocked:</p>
201
- <pre><code>curl -s -X POST "$SLACK_WEBHOOK" -d "{\"text\":\"Blocked: $COMMAND\"}"</code></pre>
202
- </div>
203
- </details>
204
-
205
- <div class="cat">Installation</div>
206
-
207
- <details>
208
- <summary>How do I install hooks?</summary>
209
- <div class="answer">
210
- <p>Three ways:</p>
211
- <ol>
212
- <li><strong>One command:</strong> <code>npx cc-safe-setup</code> (installs 8 safety hooks)</li>
213
- <li><strong>Individual:</strong> <code>npx cc-safe-setup --install-example block-database-wipe</code></li>
214
- <li><strong>Manual:</strong> Save script to <code>~/.claude/hooks/</code>, <code>chmod +x</code>, add to <code>settings.json</code></li>
215
- </ol>
216
- </div>
217
- </details>
218
-
219
- <details>
220
- <summary>How do I uninstall hooks?</summary>
221
- <div class="answer">
222
- <pre><code>npx cc-safe-setup --uninstall</code></pre>
223
- <p>Or manually: remove the hook entries from <code>~/.claude/settings.json</code> and delete the script files.</p>
224
- </div>
225
- </details>
226
-
227
- <details>
228
- <summary>Where are hooks stored?</summary>
229
- <div class="answer">
230
- <p>Scripts: <code>~/.claude/hooks/</code></p>
231
- <p>Configuration: <code>~/.claude/settings.json</code> (global) or <code>.claude/settings.json</code> (project)</p>
232
- <p>Project-level hooks override global hooks for the same matcher.</p>
233
- </div>
234
- </details>
235
-
236
- <div class="footer">
237
- <a href="hooks-cheatsheet.html">Cheat Sheet</a> ·
238
- <a href="builder.html">Hook Builder</a> ·
239
- <a href="https://yurukusa.github.io/cc-hook-registry/playground.html">Playground</a> ·
240
- <a href="https://github.com/yurukusa/cc-safe-setup">GitHub</a>
241
- </div>
242
- </div>
243
- </body>
244
- </html>