npm - cc-safe-setup - Versions diffs - 7.8.0 → 8.0.0 - Mend

cc-safe-setup 7.8.0 → 8.0.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 (10) hide show

package/CLAUDE.md +18 -0
package/README.md +1 -1
package/docs/builder.html +283 -0
package/docs/faq.html +244 -0
package/examples/auto-stash-before-pull.sh +27 -0
package/examples/commit-scope-guard.sh +32 -0
package/examples/compact-reminder.sh +36 -0
package/examples/worktree-guard.sh +28 -0
package/index.mjs +207 -0
package/package.json +1 -1

package/CLAUDE.md ADDED Viewed

@@ -0,0 +1,18 @@
+# Project Rules
+## Safety
+- Do not push to main/master directly
+- Do not force-push
+- Do not delete files outside this project
+- Do not commit .env or credential files
+- Run tests before committing
+## Code Style
+- Follow existing conventions
+- Keep functions small and focused
+- Add comments only when the logic isn't obvious
+## Git
+- Use descriptive commit messages
+- One logical change per commit
+- Create feature branches for new work

package/README.md CHANGED Viewed

@@ -6,7 +6,7 @@
 **One command to make Claude Code safe for autonomous operation.** [日本語](docs/README.ja.md)
-8 built-in + 75 examples = **83 hooks**. 28 CLI commands. 420 tests. [Web Tool](https://yurukusa.github.io/cc-safe-setup/) · [Hooks Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/hooks-cheatsheet.html) · [Playground](https://yurukusa.github.io/cc-hook-registry/playground.html) · [Troubleshooting](TROUBLESHOOTING.md)
+8 built-in + 77 examples = **85 hooks**. 28 CLI commands. 423 tests. [Web Tool](https://yurukusa.github.io/cc-safe-setup/) · [Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/hooks-cheatsheet.html) · [Builder](https://yurukusa.github.io/cc-safe-setup/builder.html) · [FAQ](https://yurukusa.github.io/cc-safe-setup/faq.html) · [Playground](https://yurukusa.github.io/cc-hook-registry/playground.html)
 ```bash
 npx cc-safe-setup

package/docs/builder.html ADDED Viewed

@@ -0,0 +1,283 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Hook Builder — Claude Code</title>
+<meta name="description" content="Generate Claude Code hooks from plain English. No coding required.">
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#0d1117;color:#c9d1d9;min-height:100vh;padding:1.5rem}
+.c{max-width:800px;margin:0 auto}
+h1{color:#f0f6fc;font-size:1.4rem;margin-bottom:.3rem}
+.sub{color:#8b949e;font-size:.85rem;margin-bottom:1.2rem}
+a{color:#58a6ff;text-decoration:none}
+input,select{width:100%;padding:.6rem;background:#161b22;border:1px solid #30363d;border-radius:6px;color:#c9d1d9;font-size:.9rem;margin-bottom:.6rem}
+input:focus,select:focus{outline:none;border-color:#58a6ff}
+input::placeholder{color:#484f58}
+label{display:block;color:#8b949e;font-size:.78rem;margin-bottom:.2rem}
+pre{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:.8rem;font-size:.8rem;color:#e6edf3;overflow-x:auto;white-space:pre-wrap;position:relative;margin:.5rem 0}
+.copy-btn{position:absolute;top:.4rem;right:.4rem;background:#21262d;border:1px solid #30363d;color:#8b949e;padding:.2rem .5rem;border-radius:4px;cursor:pointer;font-size:.7rem}
+.copy-btn:hover{color:#f0f6fc;border-color:#58a6ff}
+.btn{background:#238636;color:#fff;border:none;padding:.6rem 1.2rem;border-radius:6px;cursor:pointer;font-size:.9rem;width:100%;margin:.5rem 0}
+.btn:hover{background:#2ea043}
+.templates{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:.4rem;margin:.8rem 0}
+.tmpl{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:.5rem;cursor:pointer;font-size:.78rem;color:#8b949e;transition:border-color .15s}
+.tmpl:hover{border-color:#58a6ff;color:#c9d1d9}
+.tmpl-title{font-weight:600;color:#c9d1d9;font-size:.82rem}
+.section{margin:1.2rem 0}
+.footer{text-align:center;color:#484f58;font-size:.7rem;margin-top:2rem}
+.note{background:#161b22;border-left:3px solid #58a6ff;padding:.5rem .8rem;font-size:.78rem;color:#8b949e;margin:.5rem 0}
+.hidden{display:none}
+</style>
+</head>
+<body>
+<div class="c">
+<h1>Hook Builder</h1>
+<p class="sub">Describe what you want in plain English. Get a working hook.</p>
+<div class="section">
+  <label>What should the hook do?</label>
+  <input id="desc" placeholder="e.g., Block npm publish without running tests first" oninput="clearOutput()">
+</div>
+<div class="section">
+  <label>Trigger event</label>
+  <select id="trigger">
+    <option value="PreToolUse">PreToolUse (before tool runs — block/approve)</option>
+    <option value="PostToolUse">PostToolUse (after tool runs — check results)</option>
+    <option value="Stop">Stop (when Claude finishes — notify/cleanup)</option>
+  </select>
+</div>
+<div class="section">
+  <label>Tool matcher (regex)</label>
+  <input id="matcher" placeholder='e.g., Bash, Edit|Write, or empty for all' value="Bash">
+</div>
+<button class="btn" onclick="generate()">Generate Hook</button>
+<div id="output" class="hidden">
+  <h2 style="color:#f0f6fc;font-size:1rem;margin:1rem 0 .5rem">Generated Hook</h2>
+  <pre id="hook-code"><code></code><button class="copy-btn" onclick="copyCode()">Copy</button></pre>
+  <h2 style="color:#f0f6fc;font-size:1rem;margin:1rem 0 .5rem">settings.json entry</h2>
+  <pre id="settings-code"><code></code><button class="copy-btn" onclick="copySettings()">Copy Settings</button></pre>
+  <div class="note">
+    <strong>Install:</strong> Save the hook to <code>~/.claude/hooks/your-hook.sh</code>, run <code>chmod +x</code>, and add the settings.json entry.
+    <br>Or use the CLI: <code id="cli-cmd"></code>
+  </div>
+</div>
+<div class="section">
+  <h2 style="color:#8b949e;font-size:.9rem;margin-bottom:.5rem">Templates</h2>
+  <div class="templates" id="templates"></div>
+</div>
+<div class="footer">
+  <a href="hooks-cheatsheet.html">Cheat Sheet</a> ·
+  <a href="https://yurukusa.github.io/cc-hook-registry/playground.html">Playground</a> ·
+  <a href="https://github.com/yurukusa/cc-safe-setup">GitHub</a>
+</div>
+</div>
+<script>
+const TEMPLATES = [
+  { title: 'Block rm -rf /', desc: 'Block rm -rf on root directory', trigger: 'PreToolUse', matcher: 'Bash', pattern: 'rm\\s+.*-rf\\s+/', action: 'block', msg: 'rm -rf on root directory' },
+  { title: 'Block force push', desc: 'Block git push --force', trigger: 'PreToolUse', matcher: 'Bash', pattern: 'git\\s+push\\s+.*--force', action: 'block', msg: 'Force push' },
+  { title: 'Block .env commit', desc: 'Block git add .env files', trigger: 'PreToolUse', matcher: 'Bash', pattern: 'git\\s+add\\s+.*\\.env', action: 'block', msg: 'Adding .env to git' },
+  { title: 'Block sudo', desc: 'Block all sudo commands', trigger: 'PreToolUse', matcher: 'Bash', pattern: '^\\s*sudo\\b', action: 'block', msg: 'sudo command' },
+  { title: 'Block DB drop', desc: 'Block DROP DATABASE/TABLE', trigger: 'PreToolUse', matcher: 'Bash', pattern: 'DROP\\s+(DATABASE|TABLE)', action: 'block', msg: 'Database drop' },
+  { title: 'Auto-approve tests', desc: 'Auto-approve npm test, pytest, cargo test', trigger: 'PreToolUse', matcher: 'Bash', pattern: '^\\s*(npm\\s+test|pytest|cargo\\s+test)', action: 'approve', msg: 'Safe test command' },
+  { title: 'Warn large output', desc: 'Warn when output exceeds 50KB', trigger: 'PostToolUse', matcher: '', pattern: null, action: 'warn-output', msg: 'Large output consuming context' },
+  { title: 'Session end notify', desc: 'Desktop notification on session end', trigger: 'Stop', matcher: '', pattern: null, action: 'notify', msg: 'Session completed' },
+  { title: 'Block npm -g', desc: 'Block global npm install', trigger: 'PreToolUse', matcher: 'Bash', pattern: 'npm\\s+install\\s+(-g|--global)', action: 'block', msg: 'Global npm install' },
+  { title: 'Block deploy Friday', desc: 'Block deploy commands on Fridays', trigger: 'PreToolUse', matcher: 'Bash', pattern: null, action: 'friday', msg: 'No deploys on Friday' },
+];
+document.getElementById('templates').innerHTML = TEMPLATES.map((t,i) => `
+  <div class="tmpl" onclick="useTemplate(${i})">
+    <div class="tmpl-title">${t.title}</div>
+    <div>${t.desc}</div>
+  </div>
+`).join('');
+function useTemplate(i) {
+  const t = TEMPLATES[i];
+  document.getElementById('desc').value = t.desc;
+  document.getElementById('trigger').value = t.trigger;
+  document.getElementById('matcher').value = t.matcher;
+  generate(t);
+}
+function clearOutput() {
+  document.getElementById('output').classList.add('hidden');
+}
+function generate(template) {
+  const desc = document.getElementById('desc').value.trim();
+  const trigger = document.getElementById('trigger').value;
+  const matcher = document.getElementById('matcher').value.trim();
+  if (!desc && !template) return;
+  let hookCode, hookName;
+  if (template) {
+    hookName = template.title.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    hookCode = generateFromTemplate(template);
+  } else {
+    hookName = desc.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30);
+    hookCode = generateFromDesc(desc, trigger, matcher);
+  }
+  const settingsCode = JSON.stringify({
+    hooks: {
+      [trigger]: [{
+        matcher: matcher,
+        hooks: [{ type: "command", command: `bash ~/.claude/hooks/${hookName}.sh` }]
+      }]
+    }
+  }, null, 2);
+  document.getElementById('hook-code').querySelector('code').textContent = hookCode;
+  document.getElementById('settings-code').querySelector('code').textContent = settingsCode;
+  document.getElementById('cli-cmd').textContent = `npx cc-safe-setup --create "${desc}"`;
+  document.getElementById('output').classList.remove('hidden');
+}
+function generateFromTemplate(t) {
+  if (t.action === 'block') {
+    return `#!/bin/bash
+# ${t.desc}
+# TRIGGER: ${t.trigger}  MATCHER: "${t.matcher}"
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qE '${t.pattern}'; then
+  echo "BLOCKED: ${t.msg}" >&2
+  exit 2
+fi
+exit 0`;
+  }
+  if (t.action === 'approve') {
+    return `#!/bin/bash
+# ${t.desc}
+# TRIGGER: ${t.trigger}  MATCHER: "${t.matcher}"
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qE '${t.pattern}'; then
+  echo '{"decision":"approve","reason":"${t.msg}"}'
+fi
+exit 0`;
+  }
+  if (t.action === 'warn-output') {
+    return `#!/bin/bash
+# ${t.desc}
+# TRIGGER: PostToolUse  MATCHER: ""
+OUTPUT=$(cat | jq -r '.tool_result // empty' 2>/dev/null)
+LEN=\${#OUTPUT}
+if [ "$LEN" -gt 50000 ]; then
+  echo "WARNING: Output is \${LEN} chars — consuming context fast" >&2
+fi
+exit 0`;
+  }
+  if (t.action === 'notify') {
+    return `#!/bin/bash
+# ${t.desc}
+# TRIGGER: Stop  MATCHER: ""
+notify-send "Claude Code" "Session completed" 2>/dev/null || \\
+osascript -e 'display notification "Session completed"' 2>/dev/null
+exit 0`;
+  }
+  if (t.action === 'friday') {
+    return `#!/bin/bash
+# ${t.desc}
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+if [ "$(date +%u)" = "5" ]; then
+  if echo "$COMMAND" | grep -qE '(deploy|publish|release)'; then
+    echo "BLOCKED: No deploys on Friday" >&2
+    exit 2
+  fi
+fi
+exit 0`;
+  }
+  return '#!/bin/bash\n# Custom hook\nexit 0';
+}
+function generateFromDesc(desc, trigger, matcher) {
+  const d = desc.toLowerCase();
+  let pattern = '', action = 'block', msg = desc;
+  if (d.includes('block') || d.includes('prevent') || d.includes('stop')) {
+    action = 'block';
+    if (d.includes('rm') || d.includes('delete')) pattern = 'rm\\s+.*-rf';
+    else if (d.includes('push') && d.includes('main')) pattern = 'git\\s+push\\s+.*\\b(main|master)\\b';
+    else if (d.includes('force')) pattern = '--force';
+    else if (d.includes('sudo')) pattern = '^\\s*sudo\\b';
+    else if (d.includes('drop')) pattern = 'DROP\\s+(DATABASE|TABLE)';
+    else if (d.includes('publish')) pattern = 'npm\\s+publish';
+    else if (d.includes('deploy')) pattern = '(deploy|vercel|netlify|firebase)';
+    else pattern = d.split(' ').pop();
+  } else if (d.includes('approve') || d.includes('allow') || d.includes('auto')) {
+    action = 'approve';
+    if (d.includes('test')) pattern = '(npm\\s+test|pytest|cargo\\s+test)';
+    else if (d.includes('build')) pattern = '(npm\\s+run\\s+build|cargo\\s+build|go\\s+build)';
+    else if (d.includes('git')) pattern = 'git\\s+(status|log|diff)';
+    else pattern = d.split(' ').pop();
+  } else if (d.includes('warn') || d.includes('alert') || d.includes('notify')) {
+    action = 'warn';
+    pattern = d.split(' ').pop();
+  }
+  if (action === 'block') {
+    return `#!/bin/bash
+# ${desc}
+# TRIGGER: ${trigger}  MATCHER: "${matcher}"
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qiE '${pattern}'; then
+  echo "BLOCKED: ${msg}" >&2
+  exit 2
+fi
+exit 0`;
+  }
+  if (action === 'approve') {
+    return `#!/bin/bash
+# ${desc}
+# TRIGGER: ${trigger}  MATCHER: "${matcher}"
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qiE '${pattern}'; then
+  echo '{"decision":"approve","reason":"${msg}"}'
+fi
+exit 0`;
+  }
+  return `#!/bin/bash
+# ${desc}
+# TRIGGER: ${trigger}  MATCHER: "${matcher}"
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qiE '${pattern}'; then
+  echo "WARNING: ${msg}" >&2
+fi
+exit 0`;
+}
+function copyCode() {
+  navigator.clipboard.writeText(document.getElementById('hook-code').querySelector('code').textContent);
+  document.getElementById('hook-code').querySelector('.copy-btn').textContent = 'Copied!';
+  setTimeout(() => document.getElementById('hook-code').querySelector('.copy-btn').textContent = 'Copy', 1500);
+}
+function copySettings() {
+  navigator.clipboard.writeText(document.getElementById('settings-code').querySelector('code').textContent);
+  document.getElementById('settings-code').querySelector('.copy-btn').textContent = 'Copied!';
+  setTimeout(() => document.getElementById('settings-code').querySelector('.copy-btn').textContent = 'Copy Settings', 1500);
+}
+</script>
+</body>
+</html>

package/docs/faq.html ADDED Viewed

@@ -0,0 +1,244 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Claude Code Hooks FAQ — Every Question Answered</title>
+<meta name="description" content="Answers to every common question about Claude Code hooks. Why hooks? How do they work? What about performance?">
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#0d1117;color:#c9d1d9;padding:1.5rem;line-height:1.6}
+.c{max-width:800px;margin:0 auto}
+h1{color:#f0f6fc;font-size:1.5rem;margin-bottom:.3rem}
+.sub{color:#8b949e;font-size:.85rem;margin-bottom:1.5rem}
+a{color:#58a6ff;text-decoration:none}
+code{background:#161b22;padding:.15rem .3rem;border-radius:3px;font-size:.85rem}
+pre{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:.7rem;font-size:.8rem;color:#e6edf3;overflow-x:auto;margin:.4rem 0}
+details{background:#161b22;border:1px solid #30363d;border-radius:6px;margin:.5rem 0}
+summary{padding:.7rem .9rem;cursor:pointer;font-weight:600;color:#f0f6fc;font-size:.9rem;list-style:none}
+summary::before{content:"▸ ";color:#58a6ff}
+details[open] summary::before{content:"▾ "}
+details[open] summary{border-bottom:1px solid #21262d}
+.answer{padding:.7rem .9rem;font-size:.85rem}
+.answer p{margin:.4rem 0}
+.cat{color:#58a6ff;font-size:.75rem;font-weight:bold;text-transform:uppercase;margin:1.5rem 0 .5rem;letter-spacing:.05em}
+.footer{text-align:center;color:#484f58;font-size:.7rem;margin-top:2rem;padding-top:1rem;border-top:1px solid #21262d}
+.quick{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:.8rem;margin:.8rem 0;font-size:.82rem}
+</style>
+</head>
+<body>
+<div class="c">
+<h1>Claude Code Hooks FAQ</h1>
+<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>
+<div class="quick">
+<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>
+</div>
+<div class="cat">Basics</div>
+<details>
+<summary>What are Claude Code hooks?</summary>
+<div class="answer">
+<p>Shell scripts that run at specific points in Claude Code's lifecycle:</p>
+<ul>
+<li><strong>PreToolUse</strong> — before any tool (Bash, Edit, Write) executes</li>
+<li><strong>PostToolUse</strong> — after a tool completes</li>
+<li><strong>Stop</strong> — when Claude finishes responding</li>
+</ul>
+<p>They're configured in <code>~/.claude/settings.json</code> and enforced at the process level — the model cannot bypass them.</p>
+</div>
+</details>
+<details>
+<summary>How is this different from CLAUDE.md?</summary>
+<div class="answer">
+<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>
+<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>
+<p>Use both: CLAUDE.md for guidelines, hooks for hard constraints.</p>
+</div>
+</details>
+<details>
+<summary>Do I need to know bash to use hooks?</summary>
+<div class="answer">
+<p>Not really. You can:</p>
+<ol>
+<li>Use <code>npx cc-safe-setup</code> to install pre-built hooks (zero coding)</li>
+<li>Use <code>npx cc-safe-setup --create "your description"</code> to generate hooks from English</li>
+<li>Use the <a href="builder.html">Hook Builder</a> web tool</li>
+<li>Copy-paste from the <a href="hooks-cheatsheet.html">Cheat Sheet</a></li>
+</ol>
+</div>
+</details>
+<div class="cat">How It Works</div>
+<details>
+<summary>What does exit code 2 do?</summary>
+<div class="answer">
+<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>
+<p><code>exit 0</code> allows the operation (default).</p>
+<p><code>exit 1</code> is treated as a hook error and is silently ignored — don't use it for blocking.</p>
+</div>
+</details>
+<details>
+<summary>What JSON does the hook receive on stdin?</summary>
+<div class="answer">
+<p>For <strong>PreToolUse</strong> (Bash):</p>
+<pre><code>{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}</code></pre>
+<p>For <strong>PreToolUse</strong> (Edit):</p>
+<pre><code>{"tool_name":"Edit","tool_input":{"file_path":"app.js","old_string":"...","new_string":"..."}}</code></pre>
+<p>For <strong>PostToolUse</strong>:</p>
+<pre><code>{"tool_name":"Bash","tool_input":{"command":"ls"},"tool_result":"file1.txt\nfile2.txt"}</code></pre>
+<p>Extract with: <code>cat | jq -r '.tool_input.command // empty'</code></p>
+</div>
+</details>
+<details>
+<summary>Can I auto-approve commands via hooks?</summary>
+<div class="answer">
+<p>Yes. Output JSON to stdout:</p>
+<pre><code>echo '{"decision":"approve","reason":"Safe test command"}'
+exit 0</code></pre>
+<p>This skips the permission prompt for that specific tool call.</p>
+</div>
+</details>
+<details>
+<summary>What does the "matcher" field do?</summary>
+<div class="answer">
+<p>It's a regex matched against the tool name:</p>
+<ul>
+<li><code>"Bash"</code> — only Bash commands</li>
+<li><code>"Edit|Write"</code> — file modifications</li>
+<li><code>""</code> (empty) — matches ALL tools</li>
+<li><code>"Read"</code> — file reads</li>
+</ul>
+</div>
+</details>
+<div class="cat">Performance & Safety</div>
+<details>
+<summary>Do hooks slow down Claude Code?</summary>
+<div class="answer">
+<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>
+<p>You can measure: <code>npx cc-safe-setup --benchmark</code></p>
+</div>
+</details>
+<details>
+<summary>Can Claude disable or modify hooks?</summary>
+<div class="answer">
+<p>Claude can edit <code>settings.json</code> via the Edit tool. To prevent this:</p>
+<pre><code>npx cc-safe-setup --install-example protect-claudemd</code></pre>
+<p>This hook blocks edits to CLAUDE.md and settings files.</p>
+</div>
+</details>
+<details>
+<summary>What if my hook has a bug?</summary>
+<div class="answer">
+<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>
+<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>
+</div>
+</details>
+<details>
+<summary>Can I use Python/TypeScript instead of bash?</summary>
+<div class="answer">
+<p>Yes. The <code>command</code> field can run anything:</p>
+<pre><code>{"type": "command", "command": "python3 ~/.claude/hooks/my-guard.py"}</code></pre>
+<p>cc-safe-setup includes Python examples: <code>examples/python/destructive_guard.py</code></p>
+<p>For TypeScript, see <a href="https://www.npmjs.com/package/@anthropic-ai/claude-code-safety-net">safety-net</a> (1,185★).</p>
+</div>
+</details>
+<div class="cat">Common Issues</div>
+<details>
+<summary>My hook doesn't fire — what's wrong?</summary>
+<div class="answer">
+<p>Run diagnostics: <code>npx cc-safe-setup --doctor</code></p>
+<p>Common causes:</p>
+<ol>
+<li><strong>Not executable:</strong> <code>chmod +x ~/.claude/hooks/your-hook.sh</code></li>
+<li><strong>Missing shebang:</strong> First line must be <code>#!/bin/bash</code></li>
+<li><strong>Wrong matcher:</strong> <code>"Bash"</code> won't fire for Edit/Write tools</li>
+<li><strong>settings.json syntax error:</strong> Validate with <code>python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"</code></li>
+<li><strong>jq not installed:</strong> <code>which jq</code> — install if missing</li>
+</ol>
+<p>Quick fix: <code>npx cc-safe-setup --quickfix</code></p>
+</div>
+</details>
+<details>
+<summary>My hook blocks everything</summary>
+<div class="answer">
+<p>Your hook is returning <code>exit 2</code> for all inputs. Debug by testing manually:</p>
+<pre><code>echo '{"tool_input":{"command":"ls"}}' | bash ~/.claude/hooks/your-hook.sh
+echo "Exit: $?"</code></pre>
+<p>If it exits 2 for <code>ls</code>, your regex is too broad. Check the <code>grep -qE</code> pattern.</p>
+</div>
+</details>
+<details>
+<summary>Multiple hooks — does order matter?</summary>
+<div class="answer">
+<p>Hooks in the same group run sequentially. If any hook exits 2, the tool call is blocked — remaining hooks don't run.</p>
+<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>
+</div>
+</details>
+<details>
+<summary>Can hooks access the internet?</summary>
+<div class="answer">
+<p>Yes. Hooks are regular shell scripts — they can make HTTP requests, send notifications, write to databases, etc.</p>
+<p>Example: send a Slack notification when a dangerous command is blocked:</p>
+<pre><code>curl -s -X POST "$SLACK_WEBHOOK" -d "{\"text\":\"Blocked: $COMMAND\"}"</code></pre>
+</div>
+</details>
+<div class="cat">Installation</div>
+<details>
+<summary>How do I install hooks?</summary>
+<div class="answer">
+<p>Three ways:</p>
+<ol>
+<li><strong>One command:</strong> <code>npx cc-safe-setup</code> (installs 8 safety hooks)</li>
+<li><strong>Individual:</strong> <code>npx cc-safe-setup --install-example block-database-wipe</code></li>
+<li><strong>Manual:</strong> Save script to <code>~/.claude/hooks/</code>, <code>chmod +x</code>, add to <code>settings.json</code></li>
+</ol>
+</div>
+</details>
+<details>
+<summary>How do I uninstall hooks?</summary>
+<div class="answer">
+<pre><code>npx cc-safe-setup --uninstall</code></pre>
+<p>Or manually: remove the hook entries from <code>~/.claude/settings.json</code> and delete the script files.</p>
+</div>
+</details>
+<details>
+<summary>Where are hooks stored?</summary>
+<div class="answer">
+<p>Scripts: <code>~/.claude/hooks/</code></p>
+<p>Configuration: <code>~/.claude/settings.json</code> (global) or <code>.claude/settings.json</code> (project)</p>
+<p>Project-level hooks override global hooks for the same matcher.</p>
+</div>
+</details>
+<div class="footer">
+  <a href="hooks-cheatsheet.html">Cheat Sheet</a> ·
+  <a href="builder.html">Hook Builder</a> ·
+  <a href="https://yurukusa.github.io/cc-hook-registry/playground.html">Playground</a> ·
+  <a href="https://github.com/yurukusa/cc-safe-setup">GitHub</a>
+</div>
+</div>
+</body>
+</html>

package/examples/auto-stash-before-pull.sh ADDED Viewed

@@ -0,0 +1,27 @@
+#!/bin/bash
+# ================================================================
+# auto-stash-before-pull.sh — Suggest stash before git pull/merge
+# ================================================================
+# PURPOSE:
+#   Claude runs git pull/merge with uncommitted changes, causing
+#   merge conflicts or lost work. This hook warns and suggests
+#   git stash before pull/merge/rebase operations.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+# ================================================================
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+# Only check pull/merge/rebase
+echo "$COMMAND" | grep -qE '\bgit\s+(pull|merge|rebase)\b' || exit 0
+# Check for uncommitted changes
+DIRTY=$(git status --porcelain 2>/dev/null)
+if [ -n "$DIRTY" ]; then
+    COUNT=$(echo "$DIRTY" | wc -l)
+    echo "WARNING: git pull/merge/rebase with $COUNT uncommitted change(s)." >&2
+    echo "Consider running: git stash && git pull && git stash pop" >&2
+fi
+exit 0

package/examples/commit-scope-guard.sh ADDED Viewed

@@ -0,0 +1,32 @@
+#!/bin/bash
+# ================================================================
+# commit-scope-guard.sh — Warn when committing too many files
+# ================================================================
+# PURPOSE:
+#   Claude Code can modify dozens of files and commit them all at
+#   once, making the commit hard to review and revert. This hook
+#   warns when staging more than a configurable number of files.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+#
+# CONFIG:
+#   CC_MAX_COMMIT_FILES=15  (warn above 15 files)
+# ================================================================
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+echo "$COMMAND" | grep -qE '^\s*git\s+commit' || exit 0
+MAX="${CC_MAX_COMMIT_FILES:-15}"
+STAGED=$(git diff --cached --name-only 2>/dev/null | wc -l)
+if [ "$STAGED" -gt "$MAX" ]; then
+    echo "WARNING: Committing $STAGED files (threshold: $MAX)." >&2
+    echo "Consider splitting into smaller, focused commits." >&2
+    echo "Files:" >&2
+    git diff --cached --name-only 2>/dev/null | head -10 | sed 's/^/  /' >&2
+    [ "$STAGED" -gt 10 ] && echo "  ... and $((STAGED-10)) more" >&2
+fi
+exit 0

package/examples/compact-reminder.sh ADDED Viewed

@@ -0,0 +1,36 @@
+#!/bin/bash
+# ================================================================
+# compact-reminder.sh — Remind to /compact when context is low
+# ================================================================
+# PURPOSE:
+#   After Claude responds (Stop event), check how many tool calls
+#   have been made in the session. If the count exceeds a threshold,
+#   suggest running /compact to free up context space.
+#
+# TRIGGER: Stop  MATCHER: ""
+#
+# CONFIG:
+#   CC_COMPACT_THRESHOLD=100  (suggest after 100 tool calls)
+# ================================================================
+THRESHOLD="${CC_COMPACT_THRESHOLD:-100}"
+STATE="/tmp/cc-tool-count-$(echo "$PWD" | md5sum | cut -c1-8)"
+# Increment counter
+COUNT=1
+[ -f "$STATE" ] && COUNT=$(($(cat "$STATE") + 1))
+echo "$COUNT" > "$STATE"
+if [ "$COUNT" -eq "$THRESHOLD" ]; then
+    echo "" >&2
+    echo "NOTE: $COUNT tool calls in this session." >&2
+    echo "Consider running /compact to free context space." >&2
+    echo "Reset counter: rm $STATE" >&2
+fi
+# Repeat reminder every 50 calls after threshold
+if [ "$COUNT" -gt "$THRESHOLD" ] && [ $(( (COUNT - THRESHOLD) % 50 )) -eq 0 ]; then
+    echo "REMINDER: $COUNT tool calls. /compact recommended." >&2
+fi
+exit 0

package/examples/worktree-guard.sh ADDED Viewed

@@ -0,0 +1,28 @@
+#!/bin/bash
+# ================================================================
+# worktree-guard.sh — Warn when operating in a git worktree
+# ================================================================
+# PURPOSE:
+#   Git worktrees share the same .git directory. Destructive operations
+#   in one worktree (git clean, reset) can affect the main working tree.
+#   This hook warns when Claude is operating inside a worktree.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+# ================================================================
+COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+# Only check destructive git commands
+echo "$COMMAND" | grep -qE '\bgit\s+(clean|reset|checkout\s+--|stash\s+drop)' || exit 0
+# Check if we're in a worktree
+GITDIR=$(git rev-parse --git-dir 2>/dev/null)
+if echo "$GITDIR" | grep -q "worktrees"; then
+    MAIN_DIR=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/.git$||')
+    echo "WARNING: You are in a git worktree." >&2
+    echo "Main working tree: $MAIN_DIR" >&2
+    echo "Destructive git operations may affect the main tree." >&2
+fi
+exit 0

package/index.mjs CHANGED Viewed

@@ -90,6 +90,7 @@ const MIGRATE = process.argv.includes('--migrate');
 const GENERATE_CI = process.argv.includes('--generate-ci');
 const REPORT = process.argv.includes('--report');
 const QUICKFIX = process.argv.includes('--quickfix');
+const SHIELD = process.argv.includes('--shield');
 const COMPARE_IDX = process.argv.findIndex(a => a === '--compare');
 const COMPARE = COMPARE_IDX !== -1 ? { a: process.argv[COMPARE_IDX + 1], b: process.argv[COMPARE_IDX + 2] } : null;
 const CREATE_IDX = process.argv.findIndex(a => a === '--create');
@@ -125,6 +126,7 @@ if (HELP) {
     npx cc-safe-setup --doctor     Diagnose why hooks aren't working
     npx cc-safe-setup --watch      Live dashboard of blocked commands
     npx cc-safe-setup --create "<desc>"  Generate a custom hook from description
+    npx cc-safe-setup --shield     Maximum safety in one command (fix + scan + install + CLAUDE.md)
     npx cc-safe-setup --quickfix   Auto-detect and fix common Claude Code problems
     npx cc-safe-setup --stats      Block statistics and patterns report
     npx cc-safe-setup --export     Export hooks config for team sharing
@@ -831,6 +833,210 @@ async function fullSetup() {
   console.log();
 }
+async function shield() {
+  const { execSync } = await import('child_process');
+  const { readdirSync } = await import('fs');
+  console.log();
+  console.log(c.bold + '  🛡️  cc-safe-setup --shield' + c.reset);
+  console.log(c.dim + '  Maximum safety in one command' + c.reset);
+  console.log();
+  // Step 1: Fix environment issues
+  console.log(c.bold + '  Step 1: Fix environment' + c.reset);
+  await quickfix();
+  // Step 2: Install core safety hooks
+  console.log();
+  console.log(c.bold + '  Step 2: Install safety hooks' + c.reset);
+  // Run the default install
+  mkdirSync(HOOKS_DIR, { recursive: true });
+  let installed = 0;
+  for (const [hookId, hookMeta] of Object.entries(HOOKS)) {
+    const hookPath = join(HOOKS_DIR, `${hookId}.sh`);
+    if (!existsSync(hookPath)) {
+      writeFileSync(hookPath, SCRIPTS[hookId]);
+      chmodSync(hookPath, 0o755);
+      installed++;
+      console.log(c.green + '  +' + c.reset + ` ${hookMeta.name}`);
+    } else {
+      console.log(c.dim + '  ✓' + c.reset + ` ${hookMeta.name} (already installed)`);
+    }
+  }
+  // Step 3: Detect project stack and install recommended examples
+  console.log();
+  console.log(c.bold + '  Step 3: Project-aware hooks' + c.reset);
+  const cwd = process.cwd();
+  const extras = [];
+  if (existsSync(join(cwd, 'package.json'))) {
+    extras.push('auto-approve-build');
+    try {
+      const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
+      if (pkg.dependencies?.prisma || pkg.devDependencies?.prisma) extras.push('block-database-wipe');
+      if (pkg.scripts?.deploy) extras.push('deploy-guard');
+    } catch {}
+  }
+  if (existsSync(join(cwd, 'requirements.txt')) || existsSync(join(cwd, 'pyproject.toml'))) extras.push('auto-approve-python');
+  if (existsSync(join(cwd, 'Dockerfile'))) extras.push('auto-approve-docker');
+  if (existsSync(join(cwd, 'go.mod'))) extras.push('auto-approve-go');
+  if (existsSync(join(cwd, 'Cargo.toml'))) extras.push('auto-approve-cargo');
+  if (existsSync(join(cwd, 'Makefile'))) extras.push('auto-approve-make');
+  if (existsSync(join(cwd, '.env'))) extras.push('env-source-guard');
+  // Always include these for maximum safety
+  extras.push('scope-guard', 'no-sudo-guard', 'protect-claudemd');
+  for (const ex of extras) {
+    const exPath = join(__dirname, 'examples', `${ex}.sh`);
+    const hookPath = join(HOOKS_DIR, `${ex}.sh`);
+    if (existsSync(exPath) && !existsSync(hookPath)) {
+      copyFileSync(exPath, hookPath);
+      chmodSync(hookPath, 0o755);
+      console.log(c.green + '  +' + c.reset + ` ${ex}`);
+      installed++;
+    } else if (existsSync(hookPath)) {
+      console.log(c.dim + '  ✓' + c.reset + ` ${ex} (already installed)`);
+    }
+  }
+  // Step 4: Update settings.json
+  console.log();
+  console.log(c.bold + '  Step 4: Configure settings.json' + c.reset);
+  let settings = {};
+  if (existsSync(SETTINGS_PATH)) {
+    try { settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8')); } catch {}
+  }
+  if (!settings.hooks) settings.hooks = {};
+  // Collect all installed hooks
+  const hookFiles = existsSync(HOOKS_DIR)
+    ? readdirSync(HOOKS_DIR).filter(f => f.endsWith('.sh'))
+    : [];
+  // Build hook entries by trigger type
+  const preToolHooks = [];
+  const postToolHooks = [];
+  const stopHooks = [];
+  for (const f of hookFiles) {
+    const content = readFileSync(join(HOOKS_DIR, f), 'utf-8');
+    const cmd = `bash ${join(HOOKS_DIR, f)}`;
+    // Check if already in settings
+    const alreadyConfigured = JSON.stringify(settings.hooks).includes(f);
+    if (alreadyConfigured) continue;
+    // Determine trigger from file content
+    if (content.includes('TRIGGER: Stop') || f.includes('api-error') || f.includes('revert-helper') || f.includes('session-handoff') || f.includes('compact-reminder') || f.includes('notify') || f.includes('tmp-cleanup')) {
+      stopHooks.push({ type: 'command', command: cmd });
+    } else if (content.includes('TRIGGER: PostToolUse') || f.includes('syntax-check') || f.includes('context-monitor') || f.includes('output-length') || f.includes('error-memory') || f.includes('cost-tracker')) {
+      postToolHooks.push({ type: 'command', command: cmd });
+    } else {
+      // Default: PreToolUse
+      const matcher = (f.includes('edit-guard') || f.includes('protect-dotfiles') || f.includes('overwrite-guard') || f.includes('binary-file') || f.includes('parallel-edit') || f.includes('test-deletion') || f.includes('memory-write'))
+        ? 'Edit|Write'
+        : 'Bash';
+      preToolHooks.push({ type: 'command', command: cmd, _matcher: matcher });
+    }
+  }
+  // Group PreToolUse hooks by matcher
+  if (preToolHooks.length > 0) {
+    if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+    const bashHooks = preToolHooks.filter(h => h._matcher === 'Bash').map(({ _matcher, ...h }) => h);
+    const editHooks = preToolHooks.filter(h => h._matcher === 'Edit|Write').map(({ _matcher, ...h }) => h);
+    if (bashHooks.length > 0) {
+      const existing = settings.hooks.PreToolUse.find(e => e.matcher === 'Bash');
+      if (existing) {
+        const existingCmds = new Set(existing.hooks.map(h => h.command));
+        for (const h of bashHooks) {
+          if (!existingCmds.has(h.command)) existing.hooks.push(h);
+        }
+      } else {
+        settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: bashHooks });
+      }
+    }
+    if (editHooks.length > 0) {
+      const existing = settings.hooks.PreToolUse.find(e => e.matcher === 'Edit|Write');
+      if (existing) {
+        const existingCmds = new Set(existing.hooks.map(h => h.command));
+        for (const h of editHooks) {
+          if (!existingCmds.has(h.command)) existing.hooks.push(h);
+        }
+      } else {
+        settings.hooks.PreToolUse.push({ matcher: 'Edit|Write', hooks: editHooks });
+      }
+    }
+  }
+  if (postToolHooks.length > 0) {
+    if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+    const existing = settings.hooks.PostToolUse.find(e => e.matcher === '');
+    if (existing) {
+      const existingCmds = new Set(existing.hooks.map(h => h.command));
+      for (const h of postToolHooks) {
+        if (!existingCmds.has(h.command)) existing.hooks.push(h);
+      }
+    } else {
+      settings.hooks.PostToolUse.push({ matcher: '', hooks: postToolHooks });
+    }
+  }
+  if (stopHooks.length > 0) {
+    if (!settings.hooks.Stop) settings.hooks.Stop = [];
+    const existing = settings.hooks.Stop.find(e => e.matcher === '');
+    if (existing) {
+      const existingCmds = new Set(existing.hooks.map(h => h.command));
+      for (const h of stopHooks) {
+        if (!existingCmds.has(h.command)) existing.hooks.push(h);
+      }
+    } else {
+      settings.hooks.Stop.push({ matcher: '', hooks: stopHooks });
+    }
+  }
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+  console.log(c.green + '  ✓' + c.reset + ' settings.json updated');
+  // Step 5: Generate CLAUDE.md template if none exists
+  console.log();
+  console.log(c.bold + '  Step 5: CLAUDE.md' + c.reset);
+  if (!existsSync(join(cwd, 'CLAUDE.md'))) {
+    const template = `# Project Rules
+## Safety
+- Do not push to main/master directly
+- Do not force-push
+- Do not delete files outside this project
+- Do not commit .env or credential files
+- Run tests before committing
+## Code Style
+- Follow existing conventions
+- Keep functions small and focused
+- Add comments only when the logic isn't obvious
+## Git
+- Use descriptive commit messages
+- One logical change per commit
+- Create feature branches for new work
+`;
+    writeFileSync(join(cwd, 'CLAUDE.md'), template);
+    console.log(c.green + '  +' + c.reset + ' Created CLAUDE.md with safety rules template');
+  } else {
+    console.log(c.dim + '  ✓' + c.reset + ' CLAUDE.md already exists');
+  }
+  // Summary
+  console.log();
+  const totalHooks = hookFiles.length;
+  console.log(c.bold + c.green + '  🛡️  Shield activated!' + c.reset);
+  console.log(c.dim + `  ${totalHooks} hooks installed and configured.` + c.reset);
+  console.log(c.dim + '  Your Claude Code sessions are now protected.' + c.reset);
+  console.log();
+  console.log(c.dim + '  Verify: npx cc-safe-setup --verify' + c.reset);
+  console.log(c.dim + '  Status: npx cc-safe-setup --status' + c.reset);
+  console.log();
+}
 async function quickfix() {
   const { execSync } = await import('child_process');
   console.log();
@@ -2836,6 +3042,7 @@ async function main() {
   if (FULL) return fullSetup();
   if (DOCTOR) return doctor();
   if (WATCH) return watch();
+  if (SHIELD) return shield();
   if (QUICKFIX) return quickfix();
   if (REPORT) return report();
   if (GENERATE_CI) return generateCI();

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "cc-safe-setup",
-  "version": "7.8.0",
+  "version": "8.0.0",
   "description": "One command to make Claude Code safe. 59 hooks (8 built-in + 51 examples). 26 CLI commands: dashboard, create, audit, lint, diff, migrate, compare, generate-ci. 284 tests.",
   "main": "index.mjs",
   "bin": {