claudia-mentor 0.8.0 → 0.9.0

package/README.md

@@ -4,7 +4,7 @@
 
 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. 205+ tests. Beginner-friendly.**
+**10 knowledge domains. 15 hooks. 11 commands. 264 tests. Beginner-friendly.**
 
 ## What Claudia Does
 
@@ -60,7 +60,7 @@ Claudia automatically activates when you:
 
 ### Hooks (Always Active)
 
-**7 file-check hooks** (run on every file write):
+**8 file-check hooks** (run on every file write):
 
 | Hook | Type | What it catches |
 |------|------|-----------------|
@@ -71,6 +71,7 @@ Claudia automatically activates when you:
 | Git hygiene | blocks | .env writes, merge conflict markers. Warns on large binaries |
 | Accessibility | warns | Missing alt text, unlabeled inputs, icon-only buttons, div click handlers |
 | License compliance | warns | GPL/AGPL dependencies in permissive-licensed projects |
+| CSS anti-patterns | warns | `!important` overuse, magic numbers, deep nesting, inline styles in templates |
 
 **7 proactive hooks** (watch your conversation):
 
@@ -86,7 +87,7 @@ Claudia automatically activates when you:
 
 ## Beginner Mode
 
-Set `"experience": "beginner"` in `~/.claude/claudia-context.json` (or run `/claudia:setup`) and Claudia adapts:
+Set `"experience": "beginner"` in `~/.claude/claudia.json` (or `~/.claude/claudia-context.json`, or run `/claudia:setup`) and Claudia adapts:
 
 - **Simplified greeting** -- No command list on startup. Just "Claudia is here. Just build. I'm watching."
 - **Stuck detection** -- Type "I'm stuck" or "help" and she asks one clarifying question, then suggests one small next step
@@ -165,12 +166,19 @@ Override Claudia's personality and proactivity level:
 ```json
 {
   "proactivity": "high",
+  "experience": "beginner",
   "personality": {
     "tone": "casual"
-  }
+  },
+  "suppress_topics": ["Netlify", "hosting"],
+  "suppress_hooks": ["next-steps", "milestones"]
 }
 ```
 
+`suppress_topics` silences teach tips for specific keywords (e.g. `"Netlify"`) or entire categories (e.g. `"hosting"`). Case-insensitive. Each tip includes a dismiss hint showing how to add it.
+
+`suppress_hooks` silences entire proactive hooks by name. Valid names: `teach`, `prompt-coach`, `next-steps`, `run-suggest`, `milestones`, `session-tips`, `compact-tip`. Each hook occasionally shows a dismiss hint telling you how.
+
 ### Per-project (`.claudia.json` in project root)
 
 ```json

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

@@ -37,7 +37,7 @@ def save_state(session_id, state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, load_suppress_hooks
 
 
 def load_config():
@@ -56,6 +56,10 @@ def main():
     proactivity, experience = load_config()
     is_beginner = experience == "beginner"
 
+    # Bail if hook is suppressed
+    if "compact-tip" in load_suppress_hooks():
+        sys.exit(0)
+
     # Non-beginners at moderate or low proactivity: skip entirely
     if not is_beginner:
         sys.exit(0)

package/hooks/scripts/claudia-milestones.py

@@ -94,7 +94,7 @@ def save_state(state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, dismiss_hint
 
 
 def load_config():
@@ -156,7 +156,8 @@ def check(input_data, proactivity, experience):
         state["achieved"] = list(achieved)
         save_state(state)
         msg = f"Claudia: {celebration}"
-        return {"additionalContext": msg, "systemMessage": f"\033[38;5;160m{msg}\033[0m"}
+        user_hint, claude_hint = dismiss_hint("milestones")
+        return {"additionalContext": msg + "\n" + claude_hint, "systemMessage": f"\033[38;5;160m{msg}\n{user_hint}\033[0m"}
 
     # Save state even without celebration (for file_count tracking)
     if new_files > 0:

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

@@ -14,25 +14,28 @@ import time
 
 # Completion signals
 COMPLETION_PATTERNS = [
-    r"I've created",
-    r"I have created",
-    r"I've written",
-    r"I've built",
-    r"I've set up",
-    r"I've added",
-    r"I've updated",
-    r"I've fixed",
-    r"I've implemented",
-    r"Done[.!]",
-    r"Here's your",
-    r"Here is your",
-    r"All set[.!]",
-    r"That's done",
-    r"It's ready",
-    r"The [\w\s]+ is ready",
-    r"Your [\w\s]+ is ready",
+    r"^I've created",
+    r"^I have created",
+    r"^I've written",
+    r"^I've built",
+    r"^I've set up",
+    r"^I've added",
+    r"^I've updated",
+    r"^I've fixed",
+    r"^I've implemented",
+    r"^Done[.!]",
+    r"^Here's your",
+    r"^Here is your",
+    r"^All set[.!]",
+    r"^That's done",
+    r"^It's ready",
+    r"^The [\w\s]+ is ready",
+    r"^Your [\w\s]+ is ready",
 ]
 
+# Long messages are summaries, not single-action completions
+MAX_COMPLETION_LENGTH = 800
+
 # File type -> contextual next steps
 NEXT_STEPS = {
     "html": [
@@ -123,7 +126,7 @@ def save_state(session_id, state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, dismiss_hint
 
 
 def load_config():
@@ -147,8 +150,12 @@ def check(input_data, proactivity, experience):
     if state["count"] >= 3:
         return None
 
+    # Long messages are summaries/changelogs, not single-action completions
+    if len(message) > MAX_COMPLETION_LENGTH:
+        return None
+
     is_completion = any(
-        re.search(pattern, message, re.IGNORECASE)
+        re.search(pattern, message, re.IGNORECASE | re.MULTILINE)
         for pattern in COMPLETION_PATTERNS
     )
 
@@ -184,9 +191,15 @@ def check(input_data, proactivity, experience):
     suggestion_text = "Claudia: What's next? Here are some ideas:\n" + "\n".join(
         f"  - {step}" for step in formatted
     )
+    system_msg = suggestion_text
+    context = suggestion_text
+    if state["count"] % 3 == 0:
+        user_hint, claude_hint = dismiss_hint("next-steps")
+        system_msg += "\n" + user_hint
+        context += "\n" + claude_hint
     return {
-        "additionalContext": suggestion_text,
-        "systemMessage": f"\033[38;5;160m{suggestion_text}\033[0m",
+        "additionalContext": context,
+        "systemMessage": f"\033[38;5;160m{system_msg}\033[0m",
     }
 
 

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

@@ -64,7 +64,7 @@ def save_state(session_id, state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, load_suppress_hooks, dismiss_hint
 
 
 def load_config():
@@ -85,6 +85,10 @@ def main():
 
     proactivity, experience = load_config()
 
+    # Bail if hook is suppressed
+    if "prompt-coach" in load_suppress_hooks():
+        sys.exit(0)
+
     # Skip slash commands — user is using the system correctly
     if prompt.startswith("/"):
         sys.exit(0)
@@ -144,7 +148,7 @@ def main():
 
         # Check for very short prompts (< 15 chars) that aren't slash commands
         if not coaching_note and len(prompt) < 15 and is_beginner:
-            if not re.match(r'^(yes|no|ok|okay|sure|yeah|yep|nah|nope|thanks|ty|thx)\b', prompt, re.IGNORECASE):
+            if not re.match(r'^(yes|no|ok|okay|sure|yeah|yep|nah|nope|thanks|ty|thx|commit this|push it|push this|run tests|run it|do this|ship it|test it|build it|deploy it|lint it|format it|save it|merge it|revert it|undo that)\b', prompt, re.IGNORECASE):
                 coaching_note = (
                     "Claudia note: The user's prompt is quite short. They might benefit from "
                     "a gentle nudge to be more specific. Before responding, consider asking: "
@@ -174,7 +178,12 @@ def main():
         save_state(session_id, state)
         result = {"additionalContext": coaching_note}
         if user_msg:
-            result["systemMessage"] = f"\033[38;5;160m{user_msg}\033[0m"
+            system_msg = user_msg
+            if state["count"] % 2 == 0:
+                user_hint, claude_hint = dismiss_hint("prompt-coach")
+                system_msg += "\n" + user_hint
+                result["additionalContext"] += "\n" + claude_hint
+            result["systemMessage"] = f"\033[38;5;160m{system_msg}\033[0m"
         print(json.dumps(result))
 
     sys.exit(0)

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

@@ -76,7 +76,7 @@ def save_state(session_id, state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, dismiss_hint
 
 
 def load_config():
@@ -98,6 +98,10 @@ def check(input_data, proactivity, experience):
     state = load_state(session_id)
     shown_types = set(state.get("shown_types", []))
 
+    user_hint, claude_hint = dismiss_hint("run-suggest")
+    hint = "\n" + user_hint
+    ctx_hint = "\n" + claude_hint
+
     # Check for package.json mentions
     if "package.json" not in shown_types and re.search(PACKAGE_JSON_PATTERN, message, re.IGNORECASE):
         shown_types.add("package.json")
@@ -105,7 +109,7 @@ def check(input_data, proactivity, experience):
         save_state(session_id, state)
         suggestion = RUN_SUGGESTIONS["package.json"][1]
         msg = f"Claudia: {suggestion}"
-        return {"additionalContext": msg, "systemMessage": f"\033[38;5;160m{msg}\033[0m"}
+        return {"additionalContext": msg + ctx_hint, "systemMessage": f"\033[38;5;160m{msg}{hint}\033[0m"}
 
     # Check for file creation patterns
     for pattern in FILE_PATTERNS:
@@ -119,7 +123,7 @@ def check(input_data, proactivity, experience):
                 save_state(session_id, state)
                 suggestion = RUN_SUGGESTIONS[ext][1].format(filename=filename)
                 msg = f"Claudia: {suggestion}"
-                return {"additionalContext": msg, "systemMessage": f"\033[38;5;160m{msg}\033[0m"}
+                return {"additionalContext": msg + ctx_hint, "systemMessage": f"\033[38;5;160m{msg}{hint}\033[0m"}
 
     return None
 

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

@@ -154,7 +154,7 @@ def save_state(session_id, state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config, load_project_context
+from claudia_config import load_user_config, load_project_context, load_suppress_hooks
 
 
 def load_config():
@@ -173,6 +173,10 @@ def main():
     proactivity, experience = load_config()
     is_beginner = experience == "beginner"
 
+    # Bail if hook is suppressed
+    if "session-tips" in load_suppress_hooks():
+        sys.exit(0)
+
     # Low proactivity: skip tips, but still show greeting on startup
     if proactivity == "low" and source != "startup":
         sys.exit(0)

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

@@ -12,7 +12,7 @@ import sys
 import time
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, load_suppress_topics, load_suppress_hooks
 
 # Import check() from each Stop hook module
 import importlib
@@ -56,9 +56,22 @@ def main():
 
     session_id = input_data.get("session_id", "default")
     proactivity, experience = load_user_config()
+    input_data["suppress_topics"] = load_suppress_topics()
+    suppress_hooks = load_suppress_hooks()
+
+    # Map module names to hook names for suppress check
+    MODULE_TO_HOOK = {
+        "claudia-milestones": "milestones",
+        "claudia-run-suggest": "run-suggest",
+        "claudia-next-steps": "next-steps",
+        "claudia-teach": "teach",
+    }
 
     # Try each hook in order; first with output wins
     for module_name in HOOK_MODULES:
+        hook_name = MODULE_TO_HOOK.get(module_name, module_name)
+        if hook_name in suppress_hooks:
+            continue
         try:
             mod = _import_hook(module_name)
             result = mod.check(input_data, proactivity, experience)

package/hooks/scripts/claudia-teach.py

@@ -237,7 +237,7 @@ def save_state(session_id, state):
 
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from claudia_config import load_user_config
+from claudia_config import load_user_config, dismiss_hint
 
 
 def load_config():
@@ -265,16 +265,25 @@ def check(input_data, proactivity, experience):
     revealed_commands = set(state["revealed_commands"])
     tips = []
 
+    # Build suppressed topics set (case-insensitive)
+    suppress_topics = input_data.get("suppress_topics", [])
+    suppressed = {t.lower() for t in suppress_topics if isinstance(t, str)}
+
     # Scan for technology keywords
     for category, keywords in KEYWORDS.items():
+        if category.lower() in suppressed:
+            continue
         for keyword, description in keywords.items():
+            if keyword.lower() in suppressed:
+                continue
             pattern = r'\b' + re.escape(keyword) + r'\b'
             if re.search(pattern, message, re.IGNORECASE):
                 if keyword.lower() not in shown_keywords:
                     shown_keywords.add(keyword.lower())
                     tips.append(
                         f"I noticed we're talking about {keyword} ({description}). "
-                        f"Want me to explain more? Just say `/claudia:explain {keyword.lower()}`"
+                        f"Want me to explain more? Just say `/claudia:explain {keyword.lower()}`\n"
+                        f"(To stop tips about {keyword}, add \"{keyword}\" to \"suppress_topics\" in ~/.claude/claudia.json)"
                     )
                     break
         if tips:
@@ -312,8 +321,14 @@ def check(input_data, proactivity, experience):
         state["revealed_commands"] = list(revealed_commands)
         save_state(session_id, state)
         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}
+        system_text = tip_text
+        context = tip_text
+        if len(shown_keywords) % 3 == 0:
+            user_hint, claude_hint = dismiss_hint("teach")
+            system_text += "\n" + user_hint
+            context += "\n" + claude_hint
+        colored = "\n".join(f"\033[38;5;160m{line}\033[0m" for line in system_text.split("\n"))
+        return {"additionalContext": context, "systemMessage": colored}
 
     if shown_keywords != set(state["shown_keywords"]) or revealed_commands != set(state["revealed_commands"]):
         state["shown_keywords"] = list(shown_keywords)

package/hooks/scripts/claudia_config.py

@@ -47,8 +47,57 @@ def resolve_project():
 
 # --- User Config ---
 
+def load_suppress_topics():
+    """Load suppress_topics list from ~/.claude/claudia.json.
+
+    Returns:
+        list of topic strings to suppress (empty if not set or file missing).
+    """
+    config_path = os.path.expanduser("~/.claude/claudia.json")
+    if os.path.exists(config_path):
+        try:
+            with open(config_path) as f:
+                data = json.load(f)
+                topics = data.get("suppress_topics", [])
+                if isinstance(topics, list):
+                    return topics
+        except (json.JSONDecodeError, IOError):
+            pass
+    return []
+
+
+def load_suppress_hooks():
+    """Load suppress_hooks list from ~/.claude/claudia.json.
+
+    Returns:
+        set of lowercase hook name strings to suppress (empty if not set or file missing).
+    """
+    config_path = os.path.expanduser("~/.claude/claudia.json")
+    if os.path.exists(config_path):
+        try:
+            with open(config_path) as f:
+                data = json.load(f)
+                hooks = data.get("suppress_hooks", [])
+                if isinstance(hooks, list):
+                    return {h.lower() for h in hooks if isinstance(h, str)}
+        except (json.JSONDecodeError, IOError):
+            pass
+    return set()
+
+
+def dismiss_hint(hook_name):
+    """Return a user-visible dismiss hint and Claude-visible instruction."""
+    user_hint = f'(Say "silence {hook_name}" to turn this off)'
+    claude_hint = (
+        f'If the user asks to silence or stop {hook_name} tips, '
+        f'add "{hook_name}" to the "suppress_hooks" list in ~/.claude/claudia.json '
+        f'(create the file/key if missing).'
+    )
+    return user_hint, claude_hint
+
+
 def load_user_config():
-    """Load proactivity from ~/.claude/claudia.json, experience from context.
+    """Load proactivity and experience from ~/.claude/claudia.json, fallback to context.
 
     Returns:
         (proactivity, experience) tuple with string values.
@@ -58,17 +107,22 @@ def load_user_config():
     experience = "intermediate"
 
     config_path = os.path.expanduser("~/.claude/claudia.json")
+    experience_set = False
     if os.path.exists(config_path):
         try:
             with open(config_path) as f:
                 data = json.load(f)
                 proactivity = data.get("proactivity", proactivity)
+                if "experience" in data:
+                    experience = data["experience"]
+                    experience_set = True
         except (json.JSONDecodeError, IOError):
             pass
 
-    # Experience comes from project context (tries project-scoped first, then global)
-    ctx = load_project_context()
-    experience = ctx.get("experience", experience)
+    # Experience falls back to project context if not set in claudia.json
+    if not experience_set:
+        ctx = load_project_context()
+        experience = ctx.get("experience", experience)
 
     return proactivity, experience
 

package/package.json

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