claude-mem 3.3.7 → 3.3.9

package/docs/reference/claude-code/cc-status-line.md

@@ -0,0 +1,202 @@
+# Status line configuration
+
+> Create a custom status line for Claude Code to display contextual information
+
+Make Claude Code your own with a custom status line that displays at the bottom of the Claude Code interface, similar to how terminal prompts (PS1) work in shells like Oh-my-zsh.
+
+## Create a custom status line
+
+You can either:
+
+* Run `/statusline` to ask Claude Code to help you set up a custom status line. By default, it will try to reproduce your terminal's prompt, but you can provide additional instructions about the behavior you want to Claude Code, such as `/statusline show the model name in orange`
+
+* Directly add a `statusLine` command to your `.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.sh",
+    "padding": 0 // Optional: set to 0 to let status line go to edge
+  }
+}
+```
+
+## How it Works
+
+* The status line is updated when the conversation messages update
+* Updates run at most every 300ms
+* The first line of stdout from your command becomes the status line text
+* ANSI color codes are supported for styling your status line
+* Claude Code passes contextual information about the current session (model, directories, etc.) as JSON to your script via stdin
+
+## JSON Input Structure
+
+Your status line command receives structured data via stdin in JSON format:
+
+```json
+{
+  "hook_event_name": "Status",
+  "session_id": "abc123...",
+  "transcript_path": "/path/to/transcript.json",
+  "cwd": "/current/working/directory",
+  "model": {
+    "id": "claude-opus-4-1",
+    "display_name": "Opus"
+  },
+  "workspace": {
+    "current_dir": "/current/working/directory",
+    "project_dir": "/original/project/directory"
+  },
+  "version": "1.0.80",
+  "output_style": {
+    "name": "default"
+  },
+  "cost": {
+    "total_cost_usd": 0.01234,
+    "total_duration_ms": 45000,
+    "total_api_duration_ms": 2300,
+    "total_lines_added": 156,
+    "total_lines_removed": 23
+  }
+}
+```
+
+## Example Scripts
+
+### Simple Status Line
+
+```bash
+#!/bin/bash
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract values using jq
+MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
+CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
+
+echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}"
+```
+
+### Git-Aware Status Line
+
+```bash
+#!/bin/bash
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract values using jq
+MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
+CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
+
+# Show git branch if in a git repo
+GIT_BRANCH=""
+if git rev-parse --git-dir > /dev/null 2>&1; then
+    BRANCH=$(git branch --show-current 2>/dev/null)
+    if [ -n "$BRANCH" ]; then
+        GIT_BRANCH=" | 🌿 $BRANCH"
+    fi
+fi
+
+echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}$GIT_BRANCH"
+```
+
+### Python Example
+
+```python
+#!/usr/bin/env python3
+import json
+import sys
+import os
+
+# Read JSON from stdin
+data = json.load(sys.stdin)
+
+# Extract values
+model = data['model']['display_name']
+current_dir = os.path.basename(data['workspace']['current_dir'])
+
+# Check for git branch
+git_branch = ""
+if os.path.exists('.git'):
+    try:
+        with open('.git/HEAD', 'r') as f:
+            ref = f.read().strip()
+            if ref.startswith('ref: refs/heads/'):
+                git_branch = f" | 🌿 {ref.replace('ref: refs/heads/', '')}"
+    except:
+        pass
+
+print(f"[{model}] 📁 {current_dir}{git_branch}")
+```
+
+### Node.js Example
+
+```javascript
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+    const data = JSON.parse(input);
+    
+    // Extract values
+    const model = data.model.display_name;
+    const currentDir = path.basename(data.workspace.current_dir);
+    
+    // Check for git branch
+    let gitBranch = '';
+    try {
+        const headContent = fs.readFileSync('.git/HEAD', 'utf8').trim();
+        if (headContent.startsWith('ref: refs/heads/')) {
+            gitBranch = ` | 🌿 ${headContent.replace('ref: refs/heads/', '')}`;
+        }
+    } catch (e) {
+        // Not a git repo or can't read HEAD
+    }
+    
+    console.log(`[${model}] 📁 ${currentDir}${gitBranch}`);
+});
+```
+
+### Helper Function Approach
+
+For more complex bash scripts, you can create helper functions:
+
+```bash
+#!/bin/bash
+# Read JSON input once
+input=$(cat)
+
+# Helper functions for common extractions
+get_model_name() { echo "$input" | jq -r '.model.display_name'; }
+get_current_dir() { echo "$input" | jq -r '.workspace.current_dir'; }
+get_project_dir() { echo "$input" | jq -r '.workspace.project_dir'; }
+get_version() { echo "$input" | jq -r '.version'; }
+get_cost() { echo "$input" | jq -r '.cost.total_cost_usd'; }
+get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }
+get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }
+get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }
+
+# Use the helpers
+MODEL=$(get_model_name)
+DIR=$(get_current_dir)
+echo "[$MODEL] 📁 ${DIR##*/}"
+```
+
+## Tips
+
+* Keep your status line concise - it should fit on one line
+* Use emojis (if your terminal supports them) and colors to make information scannable
+* Use `jq` for JSON parsing in Bash (see examples above)
+* Test your script by running it manually with mock JSON input: `echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/test"}}' | ./statusline.sh`
+* Consider caching expensive operations (like git status) if needed
+
+## Troubleshooting
+
+* If your status line doesn't appear, check that your script is executable (`chmod +x`)
+* Ensure your script outputs to stdout (not stderr)

package/docs/reference/claude-code/hook-configuration.md

@@ -0,0 +1,173 @@
+# Claude Code Hook Configuration Documentation
+
+**LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits**
+
+## Official Documentation Reference
+
+- **Source**: Claude Code Hooks API Documentation
+- **Version**: v2025
+- **Last Verified**: 2025-08-31
+- **Official URL**: https://docs.anthropic.com/en/docs/claude-code/hooks
+
+## Hook Configuration Structure
+
+### Two Categories of Hooks
+
+Claude Code hooks are divided into two distinct categories with different configuration structures:
+
+#### 1. Tool-Related Hooks
+These hooks are triggered in relation to tool usage and require a `matcher` field:
+- `PreToolUse`: Executed before a tool is invoked
+- `PostToolUse`: Executed after a tool completes
+
+**Configuration Structure:**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/path/to/script.js",
+            "timeout": 60000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 2. Non-Tool Hooks
+These hooks are triggered by system events and **MUST NOT** have a `matcher` or `pattern` field:
+- `PreCompact`: Before conversation compaction
+- `SessionStart`: When a new session begins
+- `SessionEnd`: When a session ends
+- `UserPromptSubmit`: When user submits a prompt
+- `Notification`: For system notifications
+- `Stop`: When Claude is stopping
+- `SubagentStop`: When a subagent is stopping
+
+**Configuration Structure:**
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/path/to/script.js",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Common Configuration Mistakes
+
+### ❌ INCORRECT: Adding `pattern` field to non-tool hooks
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "pattern": "*",  // WRONG: Non-tool hooks don't use patterns
+        "hooks": [...]
+      }
+    ]
+  }
+}
+```
+
+### ✅ CORRECT: Non-tool hooks without matcher
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/path/to/pre-compact.js",
+            "timeout": 180000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Hook Field Reference
+
+### Common Fields (All Hooks)
+- `type`: Always `"command"` for external scripts
+- `command`: Absolute path to the executable script
+- `timeout`: Optional timeout in milliseconds (default: 60000)
+
+### Tool Hook Specific
+- `matcher`: Regex pattern to match tool names
+  - Example: `"Edit|MultiEdit|Write"`
+  - Example: `"mcp__.*__write.*"`
+  - Example: `"Bash"`
+
+### Environment Variables Available to Hooks
+- `$CLAUDE_PROJECT_DIR`: Project root directory
+- Standard environment variables from the shell
+
+## Hook Input/Output
+
+### Input (via stdin)
+All hooks receive JSON input with common fields:
+```json
+{
+  "session_id": "string",
+  "transcript_path": "string",
+  "cwd": "string",
+  "hook_event_name": "string",
+  // Additional event-specific fields
+}
+```
+
+### Output Options
+Hooks can output:
+1. **Plain text** (stdout): Added as context
+2. **JSON** (stdout): Structured response for decisions
+3. **Exit codes**:
+   - `0`: Success, continue normally
+   - `1`: General error
+   - `2`: Block operation (for PreToolUse)
+
+## Implementation Notes
+
+### File Locations
+- User settings: `~/.claude/settings.json`
+- Project settings: `./.claude/settings.json`
+- Local settings: `./.claude/settings.local.json`
+
+### Settings Precedence (Highest to Lowest)
+1. Enterprise managed policies
+2. Command line arguments
+3. Local project settings
+4. Shared project settings
+5. User settings
+
+## Cross-References
+
+- Code Implementation: `/Users/alexnewman/Scripts/claude-mem/src/commands/install.ts:263-320`
+- Hook Files: `/Users/alexnewman/Scripts/claude-mem/hooks/`
+- User Guide: `/Users/alexnewman/Scripts/claude-mem/README-npm.md`
+
+## Version History
+
+- **2025-08-31**: Fixed hook configuration to remove incorrect `pattern` field from non-tool hooks
+- **2025-08-31**: Documented official hook structure requirements per Claude Code API
+
+---
+*This documentation is maintained by @docs-agent and verified against official Anthropic documentation.*

package/docs/reference/claude-code/hook-responses.md

@@ -0,0 +1,127 @@
+# Claude Code Hook Response Format Documentation
+## Source: Official Claude Code Docs v2025
+## Last Verified: 2025-08-31
+
+## Common Hook Response Fields
+
+All hooks can return these common fields:
+
+```json
+{
+  "continue": true,              // Whether Claude should continue (default: true)
+  "stopReason": "string",        // Message shown when continue is false
+  "suppressOutput": true,        // Hide stdout from transcript (default: false)
+  "systemMessage": "string"      // Optional warning message shown to user
+}
+```
+
+## Hook-Specific Response Formats
+
+### PreCompact Hook
+**IMPORTANT**: PreCompact does NOT support `hookSpecificOutput`
+
+```json
+{
+  "continue": true,
+  "suppressOutput": true
+}
+```
+
+### SessionStart Hook
+SessionStart DOES support `hookSpecificOutput`:
+
+```json
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "Context string to add to session"
+  }
+}
+```
+
+### PreToolUse Hook
+```json
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow" | "deny" | "ask",
+    "permissionDecisionReason": "Reason for decision"
+  }
+}
+```
+
+### PostToolUse Hook
+```json
+{
+  "decision": "block",  // Optional - blocks further processing
+  "reason": "Explanation",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Additional information for Claude"
+  }
+}
+```
+
+### UserPromptSubmit Hook
+```json
+{
+  "decision": "block",  // Optional - blocks the prompt
+  "reason": "Security policy violation",
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Additional context for the prompt"
+  }
+}
+```
+
+## Exit Codes
+
+- `0`: Success - hook executed successfully
+- `1`: Error - shown to user with stdout
+- `2`: Error - shown to Claude with stderr
+
+## Common Mistakes to Avoid
+
+### \u274c INCORRECT: Using wrong field names
+```javascript
+// WRONG
+{
+  "decision": "block",      // \u274c Wrong field
+  "reason": "Error message"  // \u274c Wrong field
+}
+```
+
+### \u2705 CORRECT: Using official field names
+```javascript
+// RIGHT
+{
+  "continue": false,
+  "stopReason": "Error message"
+}
+```
+
+### \u274c INCORRECT: Adding hookSpecificOutput to PreCompact
+```javascript
+// WRONG - PreCompact doesn't support this
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreCompact",
+    "status": "success"
+  }
+}
+```
+
+### \u2705 CORRECT: Simple response for PreCompact
+```javascript
+// RIGHT
+{
+  "continue": true,
+  "suppressOutput": true
+}
+```
+
+## References
+- Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
+- Hook Examples: https://docs.anthropic.com/en/docs/claude-code/hooks-guide

package/docs/reference/claude-code/hooks.md

@@ -0,0 +1,175 @@
+# Claude Code Hooks Configuration Documentation
+## Source: Official Claude Code Docs v2025
+## Last Verified: 2025-08-31
+
+## Hook Configuration Structure
+
+### For Tool-Based Hooks (PreToolUse, PostToolUse)
+These hooks use the `matcher` field to match tool patterns:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "ToolPattern",  // Required for tool hooks
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command-here",
+            "timeout": 60000  // Optional, in milliseconds
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### For Non-Tool Hooks (PreCompact, SessionStart, etc.)
+These hooks DO NOT use matcher/pattern fields:
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        // NO matcher or pattern field!
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/path/to/script.js",
+            "timeout": 180000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Available Hook Events
+
+### Tool-Related Hooks (use matcher)
+- **PreToolUse**: Before tool execution
+- **PostToolUse**: After tool execution
+
+### System Event Hooks (no matcher)
+- **PreCompact**: Before conversation compaction
+- **SessionStart**: When session begins
+- **SessionEnd**: When session ends (not in official docs)
+- **UserPromptSubmit**: When user submits prompt
+- **Notification**: When Claude needs user input
+- **Stop**: When stop is requested
+- **SubagentStop**: When subagent stop is requested
+
+## Hook Payload Structure
+
+### Common Fields (all hooks)
+```json
+{
+  "session_id": "string",
+  "transcript_path": "string",
+  "hook_event_name": "string",
+  "cwd": "string"  // Current working directory
+}
+```
+
+### PreCompact Specific
+```json
+{
+  "hook_event_name": "PreCompact",
+  "trigger": "manual" | "auto",
+  "custom_instructions": "string"
+}
+```
+
+### SessionStart Specific
+```json
+{
+  "hook_event_name": "SessionStart",
+  "source": "startup" | "compact" | "vscode" | "web"
+}
+```
+
+### PreToolUse/PostToolUse Specific
+```json
+{
+  "tool_name": "string",
+  "tool_input": { /* tool specific */ },
+  "tool_response": { /* PostToolUse only */ }
+}
+```
+
+## Common Configuration Mistakes
+
+### \u274c INCORRECT: Using 'pattern' for non-tool hooks
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      "pattern": "*",  // \u274c WRONG - non-tool hooks don't use this
+      "hooks": [...]
+    }]
+  }
+}
+```
+
+### \u2705 CORRECT: No matcher for non-tool hooks
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      // No pattern or matcher field
+      "hooks": [...]
+    }]
+  }
+}
+```
+
+### \u274c INCORRECT: Wrong matcher field name
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "pattern": "Bash",  // \u274c WRONG field name
+      "hooks": [...]
+    }]
+  }
+}
+```
+
+### \u2705 CORRECT: Using 'matcher' for tool hooks
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",  // \u2705 Correct field name
+      "hooks": [...]
+    }]
+  }
+}
+```
+
+## Matcher Patterns for Tool Hooks
+
+- **Exact match**: `"Bash"` - matches only Bash tool
+- **Multiple tools**: `"Edit|MultiEdit|Write"` - matches any of these
+- **MCP tools**: `"mcp__memory__.*"` - matches all memory server tools
+- **All tools**: `"*"` - matches everything
+
+## Environment Variables
+
+Hooks have access to:
+- `$CLAUDE_PROJECT_DIR` - Project root directory
+
+## Settings File Locations
+
+1. **User settings**: `~/.claude/settings.json`
+2. **Project settings**: `./.claude/settings.json`
+3. **Local settings**: `./.claude/settings.local.json`
+4. **Managed settings**: `/Library/Application Support/ClaudeCode/managed-settings.json`
+
+## References
+- Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
+- Hook Guide: https://docs.anthropic.com/en/docs/claude-code/hooks-guide