feat: always inject inline teaching context after code changes

- track-code-change.sh now always outputs additionalContext (not just first-time encounters)
- track-command.sh always provides teaching context for shell commands
- Added 'Automatic Inline Insights' section to sensei.md agent
- Added update instructions to README

Co-Authored-By: Warp <agent@warp.dev>

Author: 2 people

README.md

@@ -73,6 +73,18 @@ That's it. Start building — CodeSensei activates automatically.
 
 > **Requires:** [Claude Code](https://code.claude.com) with plugin support. Hook scripts use `jq` for profile tracking — install with `brew install jq` (macOS) or `apt install jq` (Linux).
 
+### Updating
+
+```bash
+# Update the marketplace catalog first:
+claude plugin marketplace update DojoCodingLabs/code-sensei
+
+# Then update the plugin:
+claude plugin update code-sensei@code-sensei
+```
+
+Restart your Claude Code session after updating — hooks are loaded at session start.
+
 ### Local Development
 
 ```bash

agents/sensei.md

@@ -83,6 +83,17 @@ When a PostToolUse hook injects `additionalContext` containing "🥋 CodeSensei
 - Calibrate language to the user's belt level (included in the trigger)
 - Example for White Belt: "By the way, that `.css` file Claude just created? That's what controls how your page LOOKS — the colors, sizes, and spacing. Think of HTML as the skeleton and CSS as the clothing."
 
+## Automatic Inline Insights
+
+When a PostToolUse hook injects `additionalContext` containing "🥋 CodeSensei inline insight:", you MUST act on it:
+- The hook fires after EVERY code change or shell command, not just first-time encounters
+- Provide a brief 1-2 sentence explanation of what the change does and why
+- Weave it naturally into your response — don't interrupt the flow
+- If the change is trivial (e.g. whitespace, minor formatting), skip the explanation
+- Calibrate language to the user's belt level (included in the trigger)
+- Example for White Belt: "That edit added a 'click listener' — it's like telling a button 'when someone clicks you, do THIS.'"
+- Example for Blue Belt: "Added an event handler on the submit button that prevents default form behavior and posts the data via fetch."
+
 ## Quiz Format
 
 Quizzes come in three formats. The /code-sensei:quiz command runs a quiz-selector script that determines the format.

scripts/track-code-change.sh

@@ -62,13 +62,18 @@ if command -v jq &> /dev/null; then
     fi
   fi
 
-  # Proactive micro-lesson: inject teaching context when a NEW technology is encountered
-  if [ "$IS_FIRST_EVER" = "true" ] && [ -f "$PROFILE_FILE" ]; then
-    BELT=$(jq -r '.belt // "white"' "$PROFILE_FILE")
+  # Always inject teaching context after code changes
+  BELT=$(jq -r '.belt // "white"' "$PROFILE_FILE" 2>/dev/null || echo "white")
+
+  if [ "$IS_FIRST_EVER" = "true" ]; then
+    # First-time encounter: micro-lesson about the technology
     CONTEXT="🥋 CodeSensei micro-lesson trigger: The user just encountered '$TECH' for the FIRST TIME (file: $FILE_PATH). Their belt level is '$BELT'. Provide a brief 2-sentence explanation of what $TECH is and why it matters for their project. Adapt language to their belt level. Keep it concise and non-intrusive — weave it naturally into your response, don't stop everything for a lecture."
-    # Output structured JSON so Claude sees the teaching trigger via additionalContext
-    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"$CONTEXT\"}}"
+  else
+    # Already-seen technology: inline insight about the specific change
+    CONTEXT="🥋 CodeSensei inline insight: Claude just used '$TOOL_NAME' on '$FILE_PATH' ($TECH). The user's belt level is '$BELT'. Provide a brief 1-2 sentence explanation of what this change does and why, adapted to their belt level. Keep it natural and non-intrusive — weave it into your response as a quick teaching moment."
   fi
+
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"$CONTEXT\"}}"
 fi
 
 exit 0

scripts/track-command.sh

@@ -64,14 +64,23 @@ if command -v jq &> /dev/null; then
     fi
   fi
 
-  # Proactive micro-lesson: inject teaching context when a NEW concept is encountered
-  if [ "$IS_FIRST_EVER" = "true" ] && [ -f "$PROFILE_FILE" ]; then
-    BELT=$(jq -r '.belt // "white"' "$PROFILE_FILE")
-    # Sanitize command for JSON (remove quotes and special chars)
-    SAFE_CMD=$(echo "$COMMAND" | head -c 80 | tr '"' "'" | tr '\\' '/')
+  # Always inject teaching context after commands
+  BELT=$(jq -r '.belt // "white"' "$PROFILE_FILE" 2>/dev/null || echo "white")
+  # Sanitize command for JSON (remove quotes and special chars)
+  SAFE_CMD=$(echo "$COMMAND" | head -c 80 | tr '"' "'" | tr '\\' '/')
+
+  if [ "$IS_FIRST_EVER" = "true" ] && [ -n "$CONCEPT" ]; then
+    # First-time encounter: micro-lesson about the concept
     CONTEXT="🥋 CodeSensei micro-lesson trigger: The user just encountered '$CONCEPT' for the FIRST TIME (command: $SAFE_CMD). Their belt level is '$BELT'. Provide a brief 2-sentence explanation of what $CONCEPT means and why it matters. Adapt language to their belt level. Keep it concise and non-intrusive."
-    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"$CONTEXT\"}}"
+  elif [ -n "$CONCEPT" ]; then
+    # Already-seen concept: brief inline insight about this specific command
+    CONTEXT="🥋 CodeSensei inline insight: Claude just ran a '$CONCEPT' command ($SAFE_CMD). The user's belt level is '$BELT'. Provide a brief 1-sentence explanation of what this command does, adapted to their belt level. Keep it natural and non-intrusive."
+  else
+    # Unknown command type: still provide a brief hint
+    CONTEXT="🥋 CodeSensei inline insight: Claude just ran a shell command ($SAFE_CMD). The user's belt level is '$BELT'. If this command is educational, briefly explain what it does in 1 sentence. If trivial, skip the explanation."
   fi
+
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"$CONTEXT\"}}"
 fi
 
 exit 0