claudia-mentor 0.6.0 → 0.8.0

package/README.md

@@ -1,8 +1,10 @@
 # Claudia: Proactive Mentor Plugin for Claude Code
 
+[![Tests](https://github.com/reganomalley/claudia/actions/workflows/test.yml/badge.svg)](https://github.com/reganomalley/claudia/actions/workflows/test.yml)
+
 A Claude Code plugin that acts as your technology mentor, security advisor, and prompt coach. Claudia fills the gaps between writing code and making good technology decisions.
 
-**10 knowledge domains. 14 hooks. 11 commands. Beginner-friendly.**
+**10 knowledge domains. 14 hooks. 11 commands. 205+ tests. Beginner-friendly.**
 
 ## What Claudia Does
 

package/hooks/hooks.json

@@ -1,12 +1,12 @@
 {
-  "description": "Claudia mentor hooks: security, anti-patterns, dependencies, Docker, git hygiene, accessibility, license compliance, teaching moments, compaction tips, session tips, prompt coaching, run suggestions, next steps, and milestones",
+  "description": "Claudia mentor hooks: security, anti-patterns, CSS, dependencies, Docker, git hygiene, accessibility, license compliance, teaching moments, compaction tips, session tips, prompt coaching, run suggestions, next steps, and milestones",
   "hooks": {
     "PreToolUse": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-secrets.sh",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-secrets.py",
             "timeout": 10
           }
         ],
@@ -71,41 +71,24 @@
           }
         ],
         "matcher": "Edit|Write|MultiEdit"
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/claudia-milestones.py",
-            "timeout": 10
-          }
-        ]
       },
       {
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/claudia-run-suggest.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-css.py",
             "timeout": 10
           }
-        ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/claudia-next-steps.py",
-            "timeout": 10
-          }
-        ]
-      },
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      }
+    ],
+    "Stop": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/claudia-teach.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/claudia-stop-dispatch.py",
             "timeout": 10
           }
         ]

package/hooks/scripts/check-accessibility.py

@@ -159,7 +159,7 @@ def main():
     if warnings:
         save_state(session_id, shown)
         message = "Claudia noticed some accessibility concerns:\n" + "\n".join(warnings)
-        output = json.dumps({"systemMessage": f"\033[38;5;209m{message}\033[0m"})
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
         print(output)
 
     sys.exit(0)

package/hooks/scripts/check-css.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Claudia: check-css.py
+PreToolUse hook that warns on common CSS anti-patterns.
+Advisory only (exit 0 with systemMessage), never blocks.
+Session-aware dedup to avoid repeating warnings.
+Only fires on CSS/SCSS/style files and inline styles.
+"""
+
+import json
+import os
+import re
+import sys
+
+# CSS anti-patterns to detect
+# Each: (pattern_regex, description, advice, pattern_id)
+CSS_ANTI_PATTERNS = [
+    (
+        r'!important',
+        "!important usage detected",
+        "!important overrides all specificity and makes styles hard to maintain. Fix the specificity conflict instead.",
+        "important",
+    ),
+    (
+        r'z-index:\s*(?:9{3,}|[1-9]\d{3,})',
+        "Extremely high z-index",
+        "z-index values like 9999 create an arms race. Use a z-index scale (10, 20, 30...) or CSS variables.",
+        "z_index_high",
+    ),
+    (
+        r'(?:color|background(?:-color)?|border(?:-color)?)\s*:\s*#[0-9a-fA-F]{3,8}\s*[;\n]',
+        "Hardcoded color value",
+        "Use CSS custom properties (var(--color-name)) or design tokens instead of hardcoded hex values for maintainability.",
+        "hardcoded_color",
+    ),
+    (
+        r'\*\s*\{[^}]*(?:margin|padding)\s*:\s*0',
+        "Universal selector reset",
+        "Resetting all margins/padding with * {} is expensive and can break components. Use a targeted reset or normalize.css.",
+        "universal_reset",
+    ),
+    (
+        r'(?:width|height)\s*:\s*\d+px\s*[;\n].*(?:width|height)\s*:\s*\d+px',
+        "Fixed pixel dimensions on layout",
+        "Fixed px widths can break responsiveness. Consider max-width, min-width, or relative units (%, rem, vw).",
+        "fixed_dimensions",
+    ),
+    (
+        r'@import\s+(?:url\()?["\'](?!.*\.css)',
+        "@import in CSS",
+        "@import creates extra HTTP requests and blocks rendering. Use your bundler's import or <link> tags instead.",
+        "css_import",
+    ),
+    (
+        r'float\s*:\s*(?:left|right)',
+        "Float-based layout",
+        "Floats for layout are legacy. Use flexbox or grid instead — they're easier and more predictable.",
+        "float_layout",
+    ),
+    (
+        r'(?:top|left|right|bottom)\s*:\s*50%.*transform\s*:\s*translate',
+        "Manual centering with position + transform",
+        "Consider using flexbox (display: flex; align-items: center; justify-content: center) or grid (place-items: center) for cleaner centering.",
+        "manual_centering",
+    ),
+]
+
+# File extensions where CSS anti-patterns are relevant
+CSS_EXTENSIONS = {'.css', '.scss', '.sass', '.less', '.styl', '.pcss'}
+STYLE_FILE_PATTERNS = ['style', 'global', 'theme', 'tailwind']
+
+# Files likely to have legitimate hardcoded colors
+COLOR_EXCEPTION_PATTERNS = ['theme', 'tokens', 'variables', 'colors', 'palette', 'global.css', 'tailwind']
+
+
+def is_css_file(file_path):
+    """Check if this is a CSS-like file or a file likely containing styles."""
+    _, ext = os.path.splitext(file_path)
+    if ext.lower() in CSS_EXTENSIONS:
+        return True
+    # Also check styled-components / CSS-in-JS in .tsx/.jsx/.vue/.svelte
+    if ext.lower() in {'.tsx', '.jsx', '.vue', '.svelte', '.astro'}:
+        return True
+    return False
+
+
+def get_state_file(session_id):
+    return os.path.expanduser(f"~/.claude/claudia_css_state_{session_id}.json")
+
+
+def load_state(session_id):
+    state_file = get_state_file(session_id)
+    if os.path.exists(state_file):
+        try:
+            with open(state_file) as f:
+                return set(json.load(f))
+        except (json.JSONDecodeError, IOError):
+            return set()
+    return set()
+
+
+def save_state(session_id, shown):
+    state_file = get_state_file(session_id)
+    try:
+        os.makedirs(os.path.dirname(state_file), exist_ok=True)
+        with open(state_file, "w") as f:
+            json.dump(list(shown), f)
+    except IOError:
+        pass
+
+
+def extract_content(tool_name, tool_input):
+    if tool_name == "Write":
+        return tool_input.get("content", "")
+    elif tool_name == "Edit":
+        return tool_input.get("new_string", "")
+    elif tool_name == "MultiEdit":
+        edits = tool_input.get("edits", [])
+        return " ".join(e.get("new_string", "") for e in edits)
+    return ""
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "default")
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if tool_name not in ("Edit", "Write", "MultiEdit"):
+        sys.exit(0)
+
+    if not is_css_file(file_path):
+        sys.exit(0)
+
+    content = extract_content(tool_name, tool_input)
+    if not content:
+        sys.exit(0)
+
+    # For non-CSS files, only check if content contains style-related code
+    _, ext = os.path.splitext(file_path)
+    if ext.lower() not in CSS_EXTENSIONS:
+        has_styles = bool(re.search(r'(?:styled|css`|className=|class=|<style)', content))
+        if not has_styles:
+            sys.exit(0)
+
+    # Is this a theme/token file where hardcoded colors are expected?
+    basename = os.path.basename(file_path).lower()
+    is_theme_file = any(p in basename for p in COLOR_EXCEPTION_PATTERNS)
+
+    shown = load_state(session_id)
+    warnings = []
+
+    for pattern, description, advice, pattern_id in CSS_ANTI_PATTERNS:
+        # Skip hardcoded color warning in theme/token files
+        if pattern_id == "hardcoded_color" and is_theme_file:
+            continue
+
+        if re.search(pattern, content, re.DOTALL):
+            warning_key = f"{file_path}-{pattern_id}"
+            if warning_key not in shown:
+                shown.add(warning_key)
+                warnings.append(f"- {description}: {advice}")
+
+    if warnings:
+        save_state(session_id, shown)
+        message = "Claudia noticed some CSS patterns worth reviewing:\n" + "\n".join(warnings)
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
+        print(output)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/scripts/check-deps.py

@@ -109,7 +109,7 @@ def main():
     if warnings:
         save_state(session_id, shown)
         message = "Claudia noticed some dependency concerns:\n" + "\n".join(warnings)
-        output = json.dumps({"systemMessage": f"\033[38;5;209m{message}\033[0m"})
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
         print(output)
 
     sys.exit(0)

package/hooks/scripts/check-dockerfile.py

@@ -166,7 +166,7 @@ def main():
     if warnings:
         save_state(session_id, shown)
         message = "Claudia noticed some Dockerfile patterns worth reviewing:\n" + "\n".join(warnings)
-        output = json.dumps({"systemMessage": f"\033[38;5;209m{message}\033[0m"})
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
         print(output)
 
     sys.exit(0)

package/hooks/scripts/check-git-hygiene.py

@@ -134,7 +134,7 @@ def main():
     if warnings:
         save_state(session_id, shown)
         message = "Claudia noticed a git hygiene concern:\n" + "\n".join(warnings)
-        output = json.dumps({"systemMessage": f"\033[38;5;209m{message}\033[0m"})
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
         print(output)
 
     sys.exit(0)

package/hooks/scripts/check-license.py

@@ -156,7 +156,7 @@ def main():
     if warnings:
         save_state(session_id, shown)
         message = "Claudia noticed some license concerns:\n" + "\n".join(warnings)
-        output = json.dumps({"systemMessage": f"\033[38;5;209m{message}\033[0m"})
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
         print(output)
 
     sys.exit(0)

package/hooks/scripts/check-practices.py

@@ -159,7 +159,7 @@ def main():
         save_state(session_id, shown)
         # Advisory output via JSON on stdout (systemMessage)
         message = "Claudia noticed some patterns worth reviewing:\n" + "\n".join(warnings)
-        output = json.dumps({"systemMessage": f"\033[38;5;209m{message}\033[0m"})
+        output = json.dumps({"systemMessage": f"\033[38;5;160m{message}\033[0m"})
         print(output)
 
     sys.exit(0)

package/hooks/scripts/check-secrets.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+Claudia: check-secrets.py
+PreToolUse hook that blocks hardcoded secrets in Edit/Write/MultiEdit operations.
+Exit 2 = block, Exit 0 = allow.
+Session-aware dedup to avoid re-blocking the same file+secret type.
+"""
+
+import json
+import os
+import re
+import sys
+
+# Secret patterns to detect
+# Each: (pattern_regex, description, secret_type)
+SECRET_PATTERNS = [
+    (r'AKIA[0-9A-Z]{16}', "AWS Access Key ID detected", "aws_key"),
+    (r'[0-9a-zA-Z/+]{40}(?=.*AWS)', "AWS Secret Access Key detected", "aws_secret"),
+    (r'sk-[a-zA-Z0-9]{20,}', "OpenAI/Stripe-style secret key detected", "sk_key"),
+    (r'ghp_[a-zA-Z0-9]{36}', "GitHub personal access token detected", "github_pat"),
+    (r'gho_[a-zA-Z0-9]{36}', "GitHub OAuth token detected", "github_oauth"),
+    (r'glpat-[a-zA-Z0-9\-]{20,}', "GitLab personal access token detected", "gitlab_pat"),
+    (r'xox[bpras]-[a-zA-Z0-9\-]{10,}', "Slack token detected", "slack_token"),
+    (r'-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----', "Private key detected", "private_key"),
+    (r'password\s*[=:]\s*["\'][^"\']{8,}["\']', "Hardcoded password detected", "password"),
+    (r'secret\s*[=:]\s*["\'][^"\']{8,}["\']', "Hardcoded secret detected", "secret"),
+    (r'api[_-]?key\s*[=:]\s*["\'][a-zA-Z0-9]{16,}["\']', "Hardcoded API key detected", "api_key"),
+    (r'mongodb(?:\+srv)?://[^/\s]+:[^@\s]+@', "MongoDB connection string with credentials", "mongo_uri"),
+    (r'postgres(?:ql)?://[^/\s]+:[^@\s]+@', "PostgreSQL connection string with credentials", "pg_uri"),
+    (r'mysql://[^/\s]+:[^@\s]+@', "MySQL connection string with credentials", "mysql_uri"),
+]
+
+# File patterns to skip (test/example/fixture files)
+SKIP_PATTERNS = ['test', 'spec', 'fixture', 'mock', '.example', '.sample', '.md']
+
+
+def get_state_file(session_id):
+    return os.path.expanduser(f"~/.claude/claudia_secrets_state_{session_id}.json")
+
+
+def load_state(session_id):
+    state_file = get_state_file(session_id)
+    if os.path.exists(state_file):
+        try:
+            with open(state_file) as f:
+                return set(json.load(f))
+        except (json.JSONDecodeError, IOError):
+            return set()
+    return set()
+
+
+def save_state(session_id, shown):
+    state_file = get_state_file(session_id)
+    try:
+        os.makedirs(os.path.dirname(state_file), exist_ok=True)
+        with open(state_file, "w") as f:
+            json.dump(list(shown), f)
+    except IOError:
+        pass
+
+
+def extract_content(tool_name, tool_input):
+    if tool_name == "Write":
+        return tool_input.get("content", "")
+    elif tool_name == "Edit":
+        return tool_input.get("new_string", "")
+    elif tool_name == "MultiEdit":
+        edits = tool_input.get("edits", [])
+        return " ".join(e.get("new_string", "") for e in edits)
+    return ""
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    session_id = input_data.get("session_id", "default")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if tool_name not in ("Edit", "Write", "MultiEdit"):
+        sys.exit(0)
+
+    content = extract_content(tool_name, tool_input)
+    if not content:
+        sys.exit(0)
+
+    # Skip test files and example/fixture files
+    if any(skip in file_path for skip in SKIP_PATTERNS):
+        sys.exit(0)
+
+    shown = load_state(session_id)
+    found = []
+
+    for pattern, description, secret_type in SECRET_PATTERNS:
+        if re.search(pattern, content):
+            warning_key = f"{file_path}-{secret_type}"
+            if warning_key not in shown:
+                shown.add(warning_key)
+                found.append(description)
+
+    if found:
+        save_state(session_id, shown)
+
+        C = "\033[38;5;160m"
+        R = "\033[0m"
+        if len(found) == 1:
+            print(f"{C}Claudia: {found[0]} in {file_path}.{R}", file=sys.stderr)
+        else:
+            print(f"{C}Claudia: Multiple secrets detected in {file_path}:{R}", file=sys.stderr)
+            for desc in found:
+                print(f"{C}  - {desc}{R}", file=sys.stderr)
+        print("", file=sys.stderr)
+        print(f"{C}Secrets should never be hardcoded in source files. Use:", file=sys.stderr)
+        print("  - Environment variables (.env file, gitignored)", file=sys.stderr)
+        print("  - A secret manager (AWS SSM, Vault, Doppler)", file=sys.stderr)
+        print(f"  - CI/CD secrets for pipelines{R}", file=sys.stderr)
+        print("", file=sys.stderr)
+        print(f"{C}If this is intentionally a test fixture or example, rename the file to include 'test', 'example', or 'fixture'.{R}", file=sys.stderr)
+        sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/scripts/claudia-compact-tip.py

@@ -85,7 +85,7 @@ def main():
         save_state(session_id, state)
         # Only systemMessage here -- additionalContext gets wiped by compaction
         output = json.dumps({
-            "systemMessage": f"\033[38;5;209m{tip}\033[0m",
+            "systemMessage": f"\033[38;5;160m{tip}\033[0m",
         })
         print(output)
 

package/hooks/scripts/claudia-milestones.py

@@ -115,22 +115,15 @@ def count_new_files(message):
     return len(files)
 
 
-def main():
-    try:
-        input_data = json.loads(sys.stdin.read())
-    except json.JSONDecodeError:
-        sys.exit(0)
-
+def check(input_data, proactivity, experience):
+    """Run milestones logic. Returns output dict or None."""
     message = input_data.get("last_assistant_message", "")
 
     if not message:
-        sys.exit(0)
-
-    experience = load_config()
+        return None
 
-    # Gate: beginner only
     if experience != "beginner":
-        sys.exit(0)
+        return None
 
     state = load_state()
     achieved = set(state.get("achieved", []))
@@ -162,19 +155,28 @@ def main():
     if celebration:
         state["achieved"] = list(achieved)
         save_state(state)
-        session_id = input_data.get("session_id", "default")
-        if stop_lock_acquire(session_id):
-            msg = f"Claudia: {celebration}"
-            output = json.dumps({
-                "additionalContext": msg,
-                "systemMessage": f"\033[38;5;209m{msg}\033[0m",
-            })
-            print(output)
+        msg = f"Claudia: {celebration}"
+        return {"additionalContext": msg, "systemMessage": f"\033[38;5;160m{msg}\033[0m"}
 
     # Save state even without celebration (for file_count tracking)
-    elif new_files > 0:
+    if new_files > 0:
         save_state(state)
 
+    return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    _, experience = load_user_config()
+    session_id = input_data.get("session_id", "default")
+    result = check(input_data, None, experience)
+    if result and stop_lock_acquire(session_id):
+        print(json.dumps(result))
+
     sys.exit(0)
 
 

package/hooks/scripts/claudia-next-steps.py

@@ -131,38 +131,29 @@ def load_config():
     return experience
 
 
-def main():
-    try:
-        input_data = json.loads(sys.stdin.read())
-    except json.JSONDecodeError:
-        sys.exit(0)
-
+def check(input_data, proactivity, experience):
+    """Run next-steps logic. Returns output dict or None."""
     session_id = input_data.get("session_id", "default")
     message = input_data.get("last_assistant_message", "")
 
     if not message:
-        sys.exit(0)
-
-    experience = load_config()
+        return None
 
-    # Gate: beginner only
     if experience != "beginner":
-        sys.exit(0)
+        return None
 
     state = load_state(session_id)
 
-    # Max 3 suggestion moments per session
     if state["count"] >= 3:
-        sys.exit(0)
+        return None
 
-    # Check for completion signals
     is_completion = any(
         re.search(pattern, message, re.IGNORECASE)
         for pattern in COMPLETION_PATTERNS
     )
 
     if not is_completion:
-        sys.exit(0)
+        return None
 
     # Find mentioned files to determine context
     file_matches = re.findall(FILENAME_PATTERN, message)
@@ -175,13 +166,11 @@ def main():
             filename = fname
             break
 
-    # Get appropriate next steps
     if ext and ext in NEXT_STEPS:
         steps = NEXT_STEPS[ext]
     else:
         steps = NEXT_STEPS["default"]
 
-    # Format steps with filename if available
     formatted = []
     for step in steps[:3]:
         if filename:
@@ -189,20 +178,30 @@ def main():
         else:
             formatted.append(step.replace(" {filename}", "").replace("{filename}", "the file"))
 
-    if not stop_lock_acquire(session_id):
-        sys.exit(0)
-
     state["count"] += 1
     save_state(session_id, state)
 
     suggestion_text = "Claudia: What's next? Here are some ideas:\n" + "\n".join(
         f"  - {step}" for step in formatted
     )
-    output = json.dumps({
+    return {
         "additionalContext": suggestion_text,
-        "systemMessage": f"\033[38;5;209m{suggestion_text}\033[0m",
-    })
-    print(output)
+        "systemMessage": f"\033[38;5;160m{suggestion_text}\033[0m",
+    }
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    _, experience = load_user_config()
+    session_id = input_data.get("session_id", "default")
+    result = check(input_data, None, experience)
+    if result and stop_lock_acquire(session_id):
+        print(json.dumps(result))
+
     sys.exit(0)
 
 

package/hooks/scripts/claudia-prompt-coach.py

@@ -18,12 +18,19 @@ STUCK_PATTERNS = [
     r'^(help|stuck|idk|i don\'?t know|confused|lost)\s*[.!?]*$',
     r'^(what do i do|where do i start|how do i even|i\'?m stuck|i\'?m lost|i\'?m confused)\s*[.!?]*$',
     r'^(i have no idea|no clue|what now|now what)\s*[.!?]*$',
+    r'^(i give up|this is impossible|nothing works|everything is broken)\s*[.!?]*$',
+    r'^(can you help|please help|help me)\s*[.!?]*$',
+    r'^(i don\'?t understand|i don\'?t get it|makes no sense)\s*[.!?]*$',
+    r'^(where am i|what happened|what went wrong)\s*[.!?]*$',
 ]
 
 # Vague prompt patterns
 VAGUE_PATTERNS = [
     (r'^(fix it|fix this|make it work|help me|do it|just do it)\s*[.!?]*$', "no-context"),
     (r'^(it\'?s? broken|doesn\'?t work|not working|it broke|broken)\s*[.!?]*$', "no-context"),
+    (r'^(change it|update it|redo it|do it again|try again)\s*[.!?]*$', "no-context"),
+    (r'^(it\'?s? wrong|that\'?s wrong|wrong|bad|no good)\s*[.!?]*$', "no-context"),
+    (r'^(make it better|improve it|clean it up)\s*[.!?]*$', "no-context"),
     (r'^(what|why|how)\s*[.!?]*$', "too-short"),
     (r'^(yes|no|ok|okay|sure|yeah|yep|nah|nope)\s*[.!?]*$', "single-word"),
 ]
@@ -153,12 +160,21 @@ def main():
             )
             user_msg = "Claudia noticed you might be frustrated. She's telling Claude to slow down and help."
 
+        # Check for repeated punctuation (frustration/emphasis)
+        if not coaching_note and re.search(r'[!?]{3,}', prompt):
+            coaching_note = (
+                "Claudia note: The user seems emphatic or frustrated. Take a step back — "
+                "summarize what you understand about their problem, confirm you're on the same page, "
+                "then propose ONE concrete next step."
+            )
+            user_msg = "Claudia is telling Claude to check in with you before continuing."
+
     if coaching_note:
         state["count"] += 1
         save_state(session_id, state)
         result = {"additionalContext": coaching_note}
         if user_msg:
-            result["systemMessage"] = f"\033[38;5;209m{user_msg}\033[0m"
+            result["systemMessage"] = f"\033[38;5;160m{user_msg}\033[0m"
         print(json.dumps(result))
 
     sys.exit(0)

package/hooks/scripts/claudia-run-suggest.py

@@ -83,40 +83,29 @@ def load_config():
     return load_user_config()
 
 
-def main():
-    try:
-        input_data = json.loads(sys.stdin.read())
-    except json.JSONDecodeError:
-        sys.exit(0)
-
+def check(input_data, proactivity, experience):
+    """Run run-suggest logic. Returns output dict or None."""
     session_id = input_data.get("session_id", "default")
     message = input_data.get("last_assistant_message", "")
 
     if not message:
-        sys.exit(0)
+        return None
 
-    proactivity, experience = load_config()
     is_beginner = experience == "beginner"
-
-    # Gate: beginner OR high proactivity
     if not is_beginner and proactivity != "high":
-        sys.exit(0)
+        return None
 
     state = load_state(session_id)
     shown_types = set(state.get("shown_types", []))
 
     # Check for package.json mentions
     if "package.json" not in shown_types and re.search(PACKAGE_JSON_PATTERN, message, re.IGNORECASE):
-        if not stop_lock_acquire(session_id):
-            sys.exit(0)
         shown_types.add("package.json")
         state["shown_types"] = list(shown_types)
         save_state(session_id, state)
         suggestion = RUN_SUGGESTIONS["package.json"][1]
         msg = f"Claudia: {suggestion}"
-        output = json.dumps({"additionalContext": msg, "systemMessage": f"\033[38;5;209m{msg}\033[0m"})
-        print(output)
-        sys.exit(0)
+        return {"additionalContext": msg, "systemMessage": f"\033[38;5;160m{msg}\033[0m"}
 
     # Check for file creation patterns
     for pattern in FILE_PATTERNS:
@@ -125,16 +114,27 @@ def main():
             filename = match.group(1)
             ext = match.group(2).lower()
             if ext in RUN_SUGGESTIONS and ext not in shown_types:
-                if not stop_lock_acquire(session_id):
-                    sys.exit(0)
                 shown_types.add(ext)
                 state["shown_types"] = list(shown_types)
                 save_state(session_id, state)
                 suggestion = RUN_SUGGESTIONS[ext][1].format(filename=filename)
                 msg = f"Claudia: {suggestion}"
-                output = json.dumps({"additionalContext": msg, "systemMessage": f"\033[38;5;209m{msg}\033[0m"})
-                print(output)
-                sys.exit(0)
+                return {"additionalContext": msg, "systemMessage": f"\033[38;5;160m{msg}\033[0m"}
+
+    return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    proactivity, experience = load_config()
+    session_id = input_data.get("session_id", "default")
+    result = check(input_data, proactivity, experience)
+    if result and stop_lock_acquire(session_id):
+        print(json.dumps(result))
 
     sys.exit(0)
 

package/hooks/scripts/claudia-session-tips.py

@@ -253,7 +253,7 @@ def main():
             visible_parts.append(tip)
         if visible_parts:
             msg = " | ".join(visible_parts) if greeting and tip else visible_parts[0]
-            result["systemMessage"] = f"\033[38;5;209m{msg}\033[0m"
+            result["systemMessage"] = f"\033[38;5;160m{msg}\033[0m"
         print(json.dumps(result))
 
     sys.exit(0)

package/hooks/scripts/claudia-stop-dispatch.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Claudia: claudia-stop-dispatch.py
+Single dispatcher for all Stop hooks. Runs milestones, run-suggest,
+next-steps, and teach in one process instead of 4 subprocesses.
+First hook with output wins.
+"""
+
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from claudia_config import load_user_config
+
+# Import check() from each Stop hook module
+import importlib
+
+def _import_hook(name):
+    """Import a hook module by filename (without .py)."""
+    return importlib.import_module(name.replace("-", "_").replace(".py", ""))
+
+# Hook execution order (matches original hooks.json order)
+HOOK_MODULES = [
+    "claudia-milestones",
+    "claudia-run-suggest",
+    "claudia-next-steps",
+    "claudia-teach",
+]
+
+
+def stop_lock_acquire(session_id):
+    """Try to acquire the per-turn Stop hook lock. Returns True if acquired."""
+    lock_file = os.path.expanduser(f"~/.claude/claudia_stop_lock_{session_id}.tmp")
+    now = time.time()
+    try:
+        if os.path.exists(lock_file):
+            with open(lock_file) as f:
+                ts = float(f.read().strip())
+            if now - ts < 2.0:
+                return False
+        os.makedirs(os.path.dirname(lock_file), exist_ok=True)
+        with open(lock_file, "w") as f:
+            f.write(str(now))
+        return True
+    except (IOError, ValueError):
+        return True
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "default")
+    proactivity, experience = load_user_config()
+
+    # Try each hook in order; first with output wins
+    for module_name in HOOK_MODULES:
+        try:
+            mod = _import_hook(module_name)
+            result = mod.check(input_data, proactivity, experience)
+            if result:
+                if stop_lock_acquire(session_id):
+                    print(json.dumps(result))
+                sys.exit(0)
+        except Exception:
+            # Don't let one broken hook kill the others
+            continue
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/scripts/claudia-teach.py

@@ -36,15 +36,28 @@ KEYWORDS = {
         "Supabase": "an open-source Firebase alternative built on Postgres",
         "PlanetScale": "a serverless MySQL platform with branching",
         "Prisma": "a TypeScript ORM that generates type-safe database queries",
+        "Drizzle": "a lightweight TypeScript ORM with SQL-like syntax",
+        "Turso": "an edge-hosted SQLite database",
+        "Neon": "serverless Postgres with branching and autoscaling",
+        "Pinecone": "a vector database for AI/ML similarity search",
+        "DynamoDB": "AWS's serverless NoSQL database",
+        "Firestore": "Google's serverless document database (part of Firebase)",
     },
     "frameworks": {
         "Next.js": "a React framework for building full-stack web apps",
         "React": "a JavaScript library for building user interfaces",
         "Vue": "a progressive JavaScript framework for building UIs",
         "Svelte": "a compiler that turns components into efficient JavaScript",
+        "SvelteKit": "a full-stack framework built on Svelte",
         "Astro": "a framework for building content-focused websites",
         "Express": "a minimal Node.js web framework for building APIs",
         "FastAPI": "a modern Python web framework for building APIs",
+        "Django": "a batteries-included Python web framework",
+        "Flask": "a lightweight Python web framework",
+        "Remix": "a full-stack React framework focused on web standards",
+        "Nuxt": "a full-stack Vue framework (like Next.js but for Vue)",
+        "Hono": "an ultrafast web framework that runs anywhere (Cloudflare, Deno, Bun)",
+        "tRPC": "end-to-end typesafe APIs without code generation",
     },
     "tools": {
         "Docker": "a tool for packaging apps into containers that run anywhere",
@@ -53,6 +66,15 @@ KEYWORDS = {
         "GitHub Actions": "CI/CD automation built into GitHub",
         "Webpack": "a module bundler for JavaScript applications",
         "Vite": "a fast build tool and dev server for modern web projects",
+        "Bun": "an all-in-one JavaScript runtime, bundler, and package manager",
+        "Deno": "a secure JavaScript/TypeScript runtime by Node's creator",
+        "pnpm": "a fast, disk-efficient package manager for Node.js",
+        "Turborepo": "a build system for JavaScript/TypeScript monorepos",
+        "ESLint": "a tool for finding and fixing problems in JavaScript code",
+        "Prettier": "an opinionated code formatter",
+        "Tailwind": "a utility-first CSS framework",
+        "Playwright": "a browser automation and testing framework",
+        "Vitest": "a fast unit testing framework powered by Vite",
     },
     "concepts": {
         "API": "Application Programming Interface — how programs talk to each other",
@@ -64,6 +86,20 @@ KEYWORDS = {
         "CI/CD": "Continuous Integration/Delivery — automating testing and deployment",
         "SSR": "Server-Side Rendering — generating HTML on the server for each request",
         "SSG": "Static Site Generation — pre-building HTML pages at build time",
+        "ISR": "Incremental Static Regeneration — rebuilding static pages on demand",
+        "ORM": "Object-Relational Mapping — lets you query databases using code instead of SQL",
+        "CORS": "Cross-Origin Resource Sharing — controls which sites can call your API",
+        "CSP": "Content Security Policy — tells browsers what resources your page can load",
+        "CSRF": "Cross-Site Request Forgery — an attack that tricks users into unwanted actions",
+        "XSS": "Cross-Site Scripting — an attack that injects malicious scripts into web pages",
+        "CDN": "Content Delivery Network — serves your files from servers close to users",
+        "DNS": "Domain Name System — translates domain names to IP addresses",
+        "TLS": "Transport Layer Security — encrypts data in transit (the S in HTTPS)",
+        "WASM": "WebAssembly — lets you run compiled code in the browser at near-native speed",
+        "Edge Functions": "serverless functions that run close to users at CDN edge locations",
+        "Middleware": "code that runs between a request and response, often for auth or logging",
+        "Monorepo": "a single repository containing multiple projects or packages",
+        "Microservices": "an architecture where an app is split into small, independent services",
     },
 }
 
@@ -208,30 +244,21 @@ def load_config():
     return load_user_config()
 
 
-def main():
-    try:
-        input_data = json.loads(sys.stdin.read())
-    except json.JSONDecodeError:
-        sys.exit(0)
-
+def check(input_data, proactivity, experience):
+    """Run teach logic. Returns output dict or None."""
     session_id = input_data.get("session_id", "default")
     message = input_data.get("last_assistant_message", "")
 
     if not message:
-        sys.exit(0)
-
-    # Check proactivity and experience
-    proactivity, experience = load_config()
+        return None
 
-    # Only fire on moderate or high proactivity
     if proactivity == "low":
-        sys.exit(0)
+        return None
 
     is_beginner = experience == "beginner"
 
-    # Non-beginners only get teaching on high proactivity
     if not is_beginner and proactivity != "high":
-        sys.exit(0)
+        return None
 
     state = load_state(session_id)
     shown_keywords = set(state["shown_keywords"])
@@ -241,7 +268,6 @@ def main():
     # Scan for technology keywords
     for category, keywords in KEYWORDS.items():
         for keyword, description in keywords.items():
-            # Word-boundary match, case-insensitive
             pattern = r'\b' + re.escape(keyword) + r'\b'
             if re.search(pattern, message, re.IGNORECASE):
                 if keyword.lower() not in shown_keywords:
@@ -250,7 +276,6 @@ def main():
                         f"I noticed we're talking about {keyword} ({description}). "
                         f"Want me to explain more? Just say `/claudia:explain {keyword.lower()}`"
                     )
-                    # Only one keyword tip per response to avoid noise
                     break
         if tips:
             break
@@ -279,7 +304,6 @@ def main():
                     revealed_commands.add(command)
                     tips.append(reveal["tip"])
                     break
-            # Only one command reveal per response
             if len(tips) > (1 if tips else 0):
                 break
 
@@ -287,19 +311,30 @@ def main():
         state["shown_keywords"] = list(shown_keywords)
         state["revealed_commands"] = list(revealed_commands)
         save_state(session_id, state)
-        if stop_lock_acquire(session_id):
-            tip_text = "\n".join(f"Claudia: {tip}" for tip in tips)
-            colored = "\n".join(f"\033[38;5;209m{line}\033[0m" for line in tip_text.split("\n"))
-            output = json.dumps({
-                "additionalContext": tip_text,
-                "systemMessage": colored,
-            })
-            print(output)
-    elif shown_keywords != set(state["shown_keywords"]) or revealed_commands != set(state["revealed_commands"]):
+        tip_text = "\n".join(f"Claudia: {tip}" for tip in tips)
+        colored = "\n".join(f"\033[38;5;160m{line}\033[0m" for line in tip_text.split("\n"))
+        return {"additionalContext": tip_text, "systemMessage": colored}
+
+    if shown_keywords != set(state["shown_keywords"]) or revealed_commands != set(state["revealed_commands"]):
         state["shown_keywords"] = list(shown_keywords)
         state["revealed_commands"] = list(revealed_commands)
         save_state(session_id, state)
 
+    return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    proactivity, experience = load_config()
+    session_id = input_data.get("session_id", "default")
+    result = check(input_data, proactivity, experience)
+    if result and stop_lock_acquire(session_id):
+        print(json.dumps(result))
+
     sys.exit(0)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudia-mentor",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Proactive technology mentor, security advisor, and prompt coach for Claude Code",
   "author": "Regan O'Malley <regan@reganomalley.com>",
   "license": "MIT",

package/hooks/scripts/check-secrets.sh

@@ -1,118 +0,0 @@
-#!/usr/bin/env bash
-#
-# Claudia: check-secrets.sh
-# PreToolUse hook that blocks hardcoded secrets in Edit/Write/MultiEdit operations.
-# Exit 2 = block, Exit 0 = allow.
-#
-
-set -euo pipefail
-
-# Read JSON input from stdin
-INPUT=$(cat)
-
-TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || echo "")
-SESSION_ID=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id','default'))" 2>/dev/null || echo "default")
-
-# Extract content to scan based on tool type
-CONTENT=$(echo "$INPUT" | python3 -c "
-import sys, json
-data = json.load(sys.stdin)
-tool = data.get('tool_name', '')
-ti = data.get('tool_input', {})
-if tool == 'Write':
-    print(ti.get('content', ''))
-elif tool == 'Edit':
-    print(ti.get('new_string', ''))
-elif tool == 'MultiEdit':
-    edits = ti.get('edits', [])
-    print(' '.join(e.get('new_string', '') for e in edits))
-" 2>/dev/null || echo "")
-
-FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
-
-# Skip if no content to check
-if [ -z "$CONTENT" ]; then
-    exit 0
-fi
-
-# Skip test files and example/fixture files
-case "$FILE_PATH" in
-    *test*|*spec*|*fixture*|*mock*|*.example*|*.sample*|*.md)
-        exit 0
-        ;;
-esac
-
-# State file for session-aware dedup
-STATE_DIR="$HOME/.claude"
-STATE_FILE="$STATE_DIR/claudia_secrets_state_${SESSION_ID}.json"
-
-# Secret patterns to check
-# Each pattern: "REGEX_PATTERN|DESCRIPTION|SECRET_TYPE"
-PATTERNS=(
-    'AKIA[0-9A-Z]{16}|AWS Access Key ID detected|aws_key'
-    '[0-9a-zA-Z/+]{40}(?=.*AWS)|AWS Secret Access Key detected|aws_secret'
-    'sk-[a-zA-Z0-9]{20,}|OpenAI/Stripe-style secret key detected|sk_key'
-    'ghp_[a-zA-Z0-9]{36}|GitHub personal access token detected|github_pat'
-    'gho_[a-zA-Z0-9]{36}|GitHub OAuth token detected|github_oauth'
-    'glpat-[a-zA-Z0-9\-]{20,}|GitLab personal access token detected|gitlab_pat'
-    'xox[bpras]-[a-zA-Z0-9\-]{10,}|Slack token detected|slack_token'
-    '-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----|Private key detected|private_key'
-    'password\s*[=:]\s*["\x27][^"\x27]{8,}["\x27]|Hardcoded password detected|password'
-    'secret\s*[=:]\s*["\x27][^"\x27]{8,}["\x27]|Hardcoded secret detected|secret'
-    'api[_-]?key\s*[=:]\s*["\x27][a-zA-Z0-9]{16,}["\x27]|Hardcoded API key detected|api_key'
-    'mongodb(\+srv)?://[^/\s]+:[^@\s]+@|MongoDB connection string with credentials|mongo_uri'
-    'postgres(ql)?://[^/\s]+:[^@\s]+@|PostgreSQL connection string with credentials|pg_uri'
-    'mysql://[^/\s]+:[^@\s]+@|MySQL connection string with credentials|mysql_uri'
-)
-
-# Check each pattern
-for pattern_line in "${PATTERNS[@]}"; do
-    IFS='|' read -r regex description secret_type <<< "$pattern_line"
-
-    if echo "$CONTENT" | grep -qP "$regex" 2>/dev/null || echo "$CONTENT" | grep -qE "$regex" 2>/dev/null; then
-        # Check dedup state
-        WARNING_KEY="${FILE_PATH}-${secret_type}"
-
-        if [ -f "$STATE_FILE" ]; then
-            if grep -q "\"${WARNING_KEY}\"" "$STATE_FILE" 2>/dev/null; then
-                # Already warned in this session, allow
-                exit 0
-            fi
-        fi
-
-        # Record this warning
-        mkdir -p "$STATE_DIR"
-        if [ -f "$STATE_FILE" ]; then
-            # Append to existing state
-            python3 -c "
-import json
-try:
-    with open('$STATE_FILE') as f:
-        state = json.load(f)
-except:
-    state = []
-state.append('$WARNING_KEY')
-with open('$STATE_FILE', 'w') as f:
-    json.dump(state, f)
-" 2>/dev/null || true
-        else
-            echo "[\"${WARNING_KEY}\"]" > "$STATE_FILE"
-        fi
-
-        # Block with explanation (vermillion colored)
-        C="\033[38;5;209m"
-        R="\033[0m"
-        echo -e "${C}Claudia: ${description} in ${FILE_PATH}.${R}" >&2
-        echo "" >&2
-        echo -e "${C}Secrets should never be hardcoded in source files. Use:" >&2
-        echo "  - Environment variables (.env file, gitignored)" >&2
-        echo "  - A secret manager (AWS SSM, Vault, Doppler)" >&2
-        echo -e "  - CI/CD secrets for pipelines${R}" >&2
-        echo "" >&2
-        echo -e "${C}If this is intentionally a test fixture or example, rename the file to include 'test', 'example', or 'fixture'.${R}" >&2
-        exit 2
-    fi
-done
-
-# No secrets found
-exit 0