trace-mcp 1.2.1 → 1.5.3

package/hooks/trace-mcp-guard.cmd

@@ -0,0 +1,195 @@
+@echo off
+REM trace-mcp-guard v0.4.0
+REM trace-mcp PreToolUse guard (Windows)
+REM Blocks Read/Grep/Glob/Bash on source code files - redirects to trace-mcp tools.
+REM Allows: non-code files, Read before Edit, safe Bash commands (git, npm, build, test).
+REM
+REM Consultation markers: trace-mcp server writes markers when tools access files.
+REM If a marker exists, Read is allowed immediately.
+REM
+REM Install: add to ~\.claude\settings.json or .claude\settings.local.json
+REM See README.md for setup instructions.
+
+setlocal enabledelayedexpansion
+
+REM Read JSON from stdin into a temp file
+set "TMPINPUT=%TEMP%\trace-mcp-guard-input-%RANDOM%.json"
+more > "%TMPINPUT%"
+
+REM Get tool name from env or parse from JSON
+if defined CLAUDE_TOOL_NAME (
+    set "TOOL_NAME=%CLAUDE_TOOL_NAME%"
+) else (
+    for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_name"`) do set "TOOL_NAME=%%i"
+)
+
+if "%TOOL_NAME%"=="" goto :allow
+
+REM --- Read ---
+if /i not "%TOOL_NAME%"=="Read" goto :check_grep
+
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.file_path"`) do set "FILE_PATH=%%i"
+
+REM Block .env files
+echo "%FILE_PATH%" | findstr /i /r "\.env" >nul 2>&1
+if %errorlevel%==0 (
+    set "REL_PATH=%FILE_PATH%"
+    call :deny "Use get_env_vars for .env files - it masks sensitive values (passwords, API keys, tokens)." "trace-mcp alternatives: get_env_vars to list keys + types without exposing secrets."
+    goto :cleanup
+)
+
+REM Allow non-code files
+echo "%FILE_PATH%" | findstr /i /r "\.md$ \.json$ \.jsonc$ \.yaml$ \.yml$ \.toml$ \.ini$ \.cfg$ \.txt$ \.html$ \.xml$ \.csv$ \.svg$ \.lock$ \.log$ \.sh$ \.bash$ \.zsh$ \.fish$ \.ps1$ \.bat$ \.cmd$" >nul 2>&1
+if %errorlevel%==0 goto :allow
+
+REM Allow files in non-source dirs
+echo "%FILE_PATH%" | findstr /i /r "node_modules\\ vendor\\ dist\\ build\\ \.git\\" >nul 2>&1
+if %errorlevel%==0 goto :allow
+
+REM Block code file reads - redirect to trace-mcp
+echo "%FILE_PATH%" | findstr /i /r "\.ts$ \.tsx$ \.js$ \.jsx$ \.mjs$ \.cjs$ \.py$ \.pyi$ \.go$ \.rs$ \.java$ \.kt$ \.kts$ \.rb$ \.php$ \.cs$ \.cpp$ \.c$ \.h$ \.hpp$ \.swift$ \.scala$ \.vue$ \.svelte$ \.astro$" >nul 2>&1
+if not %errorlevel%==0 goto :allow
+
+REM Check consultation markers (trace-mcp server writes these when get_outline/get_symbol called)
+for /f "usebackq delims=" %%h in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%CD%'))).Replace('-','').Substring(0,12).ToLower()"`) do set "PROJ_HASH=%%h"
+set "REL_FOR_HASH=%FILE_PATH%"
+set "REL_FOR_HASH=!REL_FOR_HASH:%CD%\=!"
+set "REL_FOR_HASH=!REL_FOR_HASH:\=/!"
+for /f "usebackq delims=" %%h in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('!REL_FOR_HASH!'))).Replace('-','').ToLower()"`) do set "FILE_HASH=%%h"
+if exist "%TEMP%\trace-mcp-consulted-!PROJ_HASH!\!FILE_HASH!" goto :allow
+
+REM Allow on second attempt (agent needs full content for Edit)
+set "SESSION_ID=default"
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "try { (Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).session_id } catch { 'default' }"`) do set "SESSION_ID=%%i"
+set "DENY_DIR=%TEMP%\trace-mcp-guard-%SESSION_ID%"
+if not exist "%DENY_DIR%" mkdir "%DENY_DIR%" 2>nul
+
+REM Create a hash of the file path for the marker
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%FILE_PATH%'))).Replace('-','').ToLower()"`) do set "MARKER_HASH=%%i"
+set "DENY_MARKER=%DENY_DIR%\%MARKER_HASH%"
+
+if exist "%DENY_MARKER%" (
+    del "%DENY_MARKER%" 2>nul
+    goto :allow
+)
+echo.> "%DENY_MARKER%"
+
+call :deny "Use trace-mcp for code reading - it returns only what you need, saving tokens." "trace-mcp alternatives: get_outline, get_symbol, search, get_feature_context. If you need full file content before editing, retry Read - it will be allowed."
+goto :cleanup
+
+:check_grep
+REM --- Grep ---
+if /i not "%TOOL_NAME%"=="Grep" goto :check_glob
+
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.path"`) do set "GREP_PATH=%%i"
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.glob"`) do set "GREP_GLOB=%%i"
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.type"`) do set "GREP_TYPE=%%i"
+
+REM Block grep on .env files
+echo "%GREP_GLOB%" | findstr /i /r "\.env" >nul 2>&1
+if %errorlevel%==0 (
+    call :deny "Use get_env_vars for .env files - it masks sensitive values." "trace-mcp alternatives: get_env_vars with pattern filter."
+    goto :cleanup
+)
+echo "%GREP_PATH%" | findstr /i /r "\.env" >nul 2>&1
+if %errorlevel%==0 (
+    call :deny "Use get_env_vars for .env files - it masks sensitive values." "trace-mcp alternatives: get_env_vars with pattern filter."
+    goto :cleanup
+)
+
+REM Allow grep on non-code file types
+echo "%GREP_GLOB%" | findstr /i /r "\.md \.json \.ya*ml \.toml \.txt \.html \.xml \.csv \.cfg \.ini \.lock \.log" >nul 2>&1
+if %errorlevel%==0 goto :allow
+
+REM Allow grep on non-code type filter
+if /i "%GREP_TYPE%"=="md" goto :allow
+if /i "%GREP_TYPE%"=="json" goto :allow
+if /i "%GREP_TYPE%"=="yaml" goto :allow
+if /i "%GREP_TYPE%"=="toml" goto :allow
+if /i "%GREP_TYPE%"=="xml" goto :allow
+if /i "%GREP_TYPE%"=="html" goto :allow
+if /i "%GREP_TYPE%"=="csv" goto :allow
+
+REM Allow grep on config dirs
+echo "%GREP_PATH%" | findstr /i /r "node_modules vendor dist build \.git" >nul 2>&1
+if %errorlevel%==0 goto :allow
+
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.pattern"`) do set "PATTERN=%%i"
+call :deny "Use trace-mcp for code search - it understands symbols and relationships." "trace-mcp alternatives: search, find_usages, get_call_graph. Use Grep only for non-code files (.md, .json, .yaml, config)."
+goto :cleanup
+
+:check_glob
+REM --- Glob ---
+if /i not "%TOOL_NAME%"=="Glob" goto :check_bash
+
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.pattern"`) do set "GLOB_PATTERN=%%i"
+
+REM Block glob on .env patterns
+echo "%GLOB_PATTERN%" | findstr /i /r "\.env" >nul 2>&1
+if %errorlevel%==0 (
+    call :deny "Use get_env_vars for .env files - it masks sensitive values." "trace-mcp alternatives: get_env_vars to list all env vars across all .env files."
+    goto :cleanup
+)
+
+REM Allow glob for non-code patterns
+echo "%GLOB_PATTERN%" | findstr /i /r "\.md \.json \.ya*ml \.toml \.txt \.html \.xml \.csv \.cfg \.ini \.lock \.log" >nul 2>&1
+if %errorlevel%==0 goto :allow
+
+call :deny "Use trace-mcp for code file discovery - it knows your project structure." "trace-mcp alternatives: get_project_map, search with file_pattern, get_outline. Use Glob only for non-code file patterns."
+goto :cleanup
+
+:check_bash
+REM --- Bash ---
+if /i not "%TOOL_NAME%"=="Bash" goto :allow
+
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.command"`) do set "COMMAND=%%i"
+
+REM Allow safe commands
+echo "%COMMAND%" | findstr /i /r /c:"^git " /c:"^npm " /c:"^npx " /c:"^pnpm " /c:"^yarn " /c:"^bun " /c:"^node " /c:"^deno " /c:"^cargo " /c:"^go " /c:"^make " /c:"^mvn " /c:"^gradle " /c:"^docker " /c:"^kubectl " /c:"^helm " /c:"^terraform " /c:"^pip " /c:"^poetry " /c:"^uv " /c:"^pytest " /c:"^vitest " /c:"^jest " /c:"^phpunit " /c:"^composer " /c:"^artisan " /c:"^rails " /c:"^bundle " /c:"^mix " /c:"^dotnet " /c:"^cmake " >nul 2>&1
+if %errorlevel%==0 goto :allow
+
+REM Block bash commands targeting .env files - prevent secret leakage
+echo "%COMMAND%" | findstr /i /r "\.env" >nul 2>&1
+if %errorlevel%==0 (
+    call :deny "Use get_env_vars for .env files - it masks sensitive values (passwords, API keys, tokens)." "trace-mcp alternatives: get_env_vars to list keys + types without exposing secrets. Never access .env files via shell."
+    goto :cleanup
+)
+
+REM Block code exploration via bash
+set "HAS_EXPLORE=0"
+echo "%COMMAND%" | findstr /i /r "grep rg find cat head tail less more awk sed" >nul 2>&1
+if %errorlevel%==0 set "HAS_EXPLORE=1"
+
+set "HAS_CODE=0"
+echo "%COMMAND%" | findstr /i /r "\.ts \.tsx \.js \.jsx \.py \.go \.rs \.java \.rb \.php \.cs \.cpp \.c \.h \.swift \.scala \.vue \.svelte" >nul 2>&1
+if %errorlevel%==0 set "HAS_CODE=1"
+
+if "%HAS_EXPLORE%"=="1" if "%HAS_CODE%"=="1" (
+    call :deny "Use trace-mcp instead of shell commands for code exploration." "trace-mcp has structured tools: search, get_symbol, get_outline, find_usages. Use Bash only for builds, tests, git, and system commands."
+    goto :cleanup
+)
+
+goto :allow
+
+REM --- Helpers ---
+
+:deny
+set "REASON=%~1"
+set "CONTEXT=%~2"
+echo {
+echo   "hookSpecificOutput": {
+echo     "hookEventName": "PreToolUse",
+echo     "permissionDecision": "deny",
+echo     "permissionDecisionReason": "%REASON%",
+echo     "additionalContext": "%CONTEXT%"
+echo   }
+echo }
+goto :eof
+
+:allow
+del "%TMPINPUT%" 2>nul
+exit /b 0
+
+:cleanup
+del "%TMPINPUT%" 2>nul
+exit /b 0

package/hooks/trace-mcp-guard.sh

@@ -1,9 +1,13 @@
 #!/usr/bin/env bash
-# trace-mcp-guard v0.1.0
+# trace-mcp-guard v0.4.0
 # trace-mcp PreToolUse guard
 # Blocks Read/Grep/Glob/Bash on source code files → redirects to trace-mcp tools.
 # Allows: non-code files, Read before Edit, safe Bash commands (git, npm, build, test).
 #
+# Consultation markers: trace-mcp server writes markers when tools access files
+# (get_outline, get_symbol, etc.). If a marker exists for a file, Read is allowed
+# immediately — the agent already consulted trace-mcp for this file.
+#
 # Install: add to ~/.claude/settings.json or .claude/settings.local.json
 # See README.md for setup instructions.
 
@@ -16,11 +20,19 @@ TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | jq -r '.tool_name // empty')}"
 CODE_EXT_RE='\.(ts|tsx|js|jsx|mjs|cjs|py|pyi|go|rs|java|kt|kts|rb|php|cs|cpp|c|h|hpp|swift|scala|vue|svelte|astro|blade\.php)$'
 
 # Non-code extensions — always allow
-NONCODE_EXT_RE='\.(md|json|jsonc|yaml|yml|toml|ini|cfg|env|txt|html|xml|csv|svg|lock|log|sh|bash|zsh|fish|ps1|bat|cmd|dockerfile|dockerignore|gitignore|gitattributes|editorconfig|prettierrc|eslintrc|stylelintrc)$'
+NONCODE_EXT_RE='\.(md|json|jsonc|yaml|yml|toml|ini|cfg|txt|html|xml|csv|svg|lock|log|sh|bash|zsh|fish|ps1|bat|cmd|dockerfile|dockerignore|gitignore|gitattributes|editorconfig|prettierrc|eslintrc|stylelintrc)$'
+
+# .env files — always route through trace-mcp to prevent secret leakage
+ENV_FILE_RE='\.env(\.[a-zA-Z0-9._-]+)?$'
 
 # Safe bash command prefixes — never block
 SAFE_BASH_RE='^(git |npm |npx |pnpm |yarn |bun |node |deno |cargo |go |make |mvn |gradle |docker |kubectl |helm |terraform |pip |poetry |uv |pytest |vitest |jest |phpunit |composer |artisan |rails |bundle |mix |dotnet |cmake |ninja |meson )'
 
+# Cross-platform sha256 hash (Linux: sha256sum, macOS: shasum)
+file_sha256() {
+  echo -n "$1" | sha256sum 2>/dev/null | cut -d' ' -f1 || echo -n "$1" | shasum -a 256 2>/dev/null | cut -d' ' -f1
+}
+
 deny() {
   local reason="$1"
   local context="$2"
@@ -42,10 +54,31 @@ SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "default"')
 DENY_DIR="/tmp/trace-mcp-guard-${SESSION_ID}"
 mkdir -p "$DENY_DIR" 2>/dev/null
 
+# Consultation markers: trace-mcp server writes these when get_outline/get_symbol/etc. are called.
+# If a file was already consulted via trace-mcp, allow Read immediately (agent needs full content for Edit).
+# Dir format: $TMPDIR/trace-mcp-consulted-{sha256(projectRoot)[:12]}/{sha256(relPath)}
+PROJECT_ROOT="$(pwd)"
+if command -v sha256sum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | sha256sum | cut -c1-12)
+elif command -v shasum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)
+else
+  PROJECT_HASH=""
+fi
+CONSULTED_DIR="${TMPDIR:-/tmp}/trace-mcp-consulted-${PROJECT_HASH}"
+
 # --- Read ---
 if [[ "$TOOL_NAME" == "Read" ]]; then
   FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
+  # Block .env files — prevent secret leakage to AI model context
+  if echo "$FILE_PATH" | grep -qiE "$ENV_FILE_RE"; then
+    REL_PATH=$(echo "$FILE_PATH" | sed "s|^$(pwd)/||")
+    deny \
+      "Use get_env_vars for .env files — it masks sensitive values (passwords, API keys, tokens)." \
+      "trace-mcp alternatives for ${REL_PATH}:\\n- get_env_vars { \\\"file\\\": \\\"${REL_PATH}\\\" } — list keys + types without exposing secrets\\n- get_env_vars { \\\"pattern\\\": \\\"DB_\\\" } — filter by key prefix\\nNever read .env files directly — secrets will leak into AI model context."
+  fi
+
   # Allow non-code files
   if echo "$FILE_PATH" | grep -qiE "$NONCODE_EXT_RE"; then
     exit 0
@@ -59,8 +92,18 @@ if [[ "$TOOL_NAME" == "Read" ]]; then
 
   # Block code file reads → redirect to trace-mcp
   if echo "$FILE_PATH" | grep -qiE "$CODE_EXT_RE"; then
+    # Compute relative path for consultation marker check (server writes markers keyed by relative path)
+    REL_PATH_FOR_HASH=$(echo "$FILE_PATH" | sed "s|^${PROJECT_ROOT}/||")
+    CONSULTED_HASH=$(file_sha256 "$REL_PATH_FOR_HASH")
+
+    # Check if file was already consulted via trace-mcp (get_outline, get_symbol, etc.)
+    if [[ -n "$PROJECT_HASH" && -f "$CONSULTED_DIR/$CONSULTED_HASH" ]]; then
+      # File was consulted via trace-mcp → allow Read (agent needs full content for Edit)
+      exit 0
+    fi
+
     # Allow on second attempt — agent needs full content for Edit
-    DENY_MARKER="$DENY_DIR/$(echo "$FILE_PATH" | md5sum | cut -d' ' -f1)"
+    DENY_MARKER="$DENY_DIR/$(file_sha256 "$FILE_PATH")"
     if [[ -f "$DENY_MARKER" ]]; then
       rm -f "$DENY_MARKER"
       exit 0
@@ -82,8 +125,15 @@ if [[ "$TOOL_NAME" == "Grep" ]]; then
   GREP_GLOB=$(echo "$INPUT" | jq -r '.tool_input.glob // empty')
   GREP_TYPE=$(echo "$INPUT" | jq -r '.tool_input.type // empty')
 
+  # Block grep on .env files — prevent secret leakage
+  if echo "$GREP_GLOB" | grep -qiE '\.env' || echo "$GREP_PATH" | grep -qiE "$ENV_FILE_RE"; then
+    deny \
+      "Use get_env_vars for .env files — it masks sensitive values." \
+      "trace-mcp alternatives:\\n- get_env_vars { \\\"pattern\\\": \\\"search_term\\\" } — find env vars by key pattern without exposing values"
+  fi
+
   # Allow grep on non-code file types
-  if echo "$GREP_GLOB" | grep -qiE '\.(md|json|ya?ml|toml|env|txt|html|xml|csv|cfg|ini|lock|log)'; then
+  if echo "$GREP_GLOB" | grep -qiE '\.(md|json|ya?ml|toml|txt|html|xml|csv|cfg|ini|lock|log)'; then
     exit 0
   fi
 
@@ -108,8 +158,15 @@ fi
 if [[ "$TOOL_NAME" == "Glob" ]]; then
   GLOB_PATTERN=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty')
 
+  # Block glob on .env patterns
+  if echo "$GLOB_PATTERN" | grep -qiE '\.env'; then
+    deny \
+      "Use get_env_vars for .env files — it masks sensitive values." \
+      "trace-mcp alternatives:\\n- get_env_vars {} — list all env vars across all .env files"
+  fi
+
   # Allow glob for non-code patterns
-  if echo "$GLOB_PATTERN" | grep -qiE '\.(md|json|ya?ml|toml|env|txt|html|xml|csv|cfg|ini|lock|log)'; then
+  if echo "$GLOB_PATTERN" | grep -qiE '\.(md|json|ya?ml|toml|txt|html|xml|csv|cfg|ini|lock|log)'; then
     exit 0
   fi
 
@@ -128,6 +185,13 @@ if [[ "$TOOL_NAME" == "Bash" ]]; then
     exit 0
   fi
 
+  # Block bash commands targeting .env files — prevent secret leakage
+  if echo "$COMMAND" | grep -qiE "$ENV_FILE_RE"; then
+    deny \
+      "Use get_env_vars for .env files — it masks sensitive values (passwords, API keys, tokens)." \
+      "trace-mcp alternatives:\\n- get_env_vars {} — list all env vars across all .env files\\n- get_env_vars { \\\"pattern\\\": \\\"DB_\\\" } — filter by key prefix\\nNever access .env files via shell — secrets will leak into AI model context."
+  fi
+
   # Block code exploration via bash (grep, find, cat, head, tail on code files)
   if echo "$COMMAND" | grep -qE '(^|\|)\s*(grep|rg|find|cat|head|tail|less|more|awk|sed)\s' && echo "$COMMAND" | grep -qiE "$CODE_EXT_RE"; then
     deny \

package/hooks/trace-mcp-precompact.cmd

@@ -0,0 +1,33 @@
+@echo off
+REM trace-mcp-precompact v0.1.0
+REM trace-mcp PreCompact hook (Windows)
+REM Injects session snapshot into compacted context to prevent "compaction amnesia".
+REM Reads the live snapshot file written by the running trace-mcp MCP server and
+REM returns it via the systemMessage field in Claude Code's hook output schema.
+REM
+REM Install: add to ~\.claude\settings.json or .claude\settings.local.json under PreCompact
+REM See README.md for setup instructions.
+
+setlocal enabledelayedexpansion
+
+REM Determine project root from working directory
+set "PROJECT_ROOT=%CD%"
+
+REM Compute project hash using PowerShell (sha256, first 12 hex chars)
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%PROJECT_ROOT%'))).Replace('-','').Substring(0,12).ToLower()"`) do set "PROJECT_HASH=%%i"
+
+if "%PROJECT_HASH%"=="" goto :done
+
+set "SNAPSHOT_FILE=%USERPROFILE%\.trace-mcp\sessions\%PROJECT_HASH%-snapshot.json"
+
+if not exist "%SNAPSHOT_FILE%" goto :done
+
+REM Read markdown from snapshot file and output as systemMessage
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "$j = Get-Content '%SNAPSHOT_FILE%' -Raw | ConvertFrom-Json; if ($j.markdown) { $j.markdown }"`) do set "MARKDOWN=%%i"
+
+if "%MARKDOWN%"=="" goto :done
+
+powershell -NoProfile -Command "$m = (Get-Content '%SNAPSHOT_FILE%' -Raw | ConvertFrom-Json).markdown; @{systemMessage=$m} | ConvertTo-Json -Compress"
+
+:done
+exit /b 0

package/hooks/trace-mcp-precompact.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# trace-mcp-precompact v0.1.0
+# trace-mcp PreCompact hook
+# Injects session snapshot into compacted context to prevent "compaction amnesia".
+# Reads the live snapshot file written by the running trace-mcp MCP server and
+# returns it via the systemMessage field in Claude Code's hook output schema.
+#
+# Install: add to ~/.claude/settings.json or .claude/settings.local.json under PreCompact
+# See README.md for setup instructions.
+
+set -euo pipefail
+
+# Determine project root from working directory
+PROJECT_ROOT="$(pwd)"
+
+# Compute project hash (same algorithm as trace-mcp: sha256, first 12 hex chars)
+if command -v sha256sum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | sha256sum | cut -c1-12)
+elif command -v shasum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)
+else
+  # Fallback: no hash available, exit silently
+  exit 0
+fi
+
+SNAPSHOT_FILE="$HOME/.trace-mcp/sessions/${PROJECT_HASH}-snapshot.json"
+
+# If no snapshot file exists, exit silently (no session data yet)
+if [[ ! -f "$SNAPSHOT_FILE" ]]; then
+  exit 0
+fi
+
+# Check file freshness — skip if older than 10 minutes (stale session)
+if command -v stat >/dev/null 2>&1; then
+  if [[ "$(uname)" == "Darwin" ]]; then
+    FILE_MTIME=$(stat -f %m "$SNAPSHOT_FILE" 2>/dev/null || echo 0)
+  else
+    FILE_MTIME=$(stat -c %Y "$SNAPSHOT_FILE" 2>/dev/null || echo 0)
+  fi
+  NOW=$(date +%s)
+  AGE=$(( NOW - FILE_MTIME ))
+  if [[ $AGE -gt 600 ]]; then
+    exit 0
+  fi
+fi
+
+# Read the markdown snapshot from the JSON file
+MARKDOWN=$(jq -r '.markdown // empty' "$SNAPSHOT_FILE" 2>/dev/null)
+
+if [[ -z "$MARKDOWN" ]]; then
+  exit 0
+fi
+
+# Output systemMessage for Claude Code to inject into compacted context
+jq -n --arg msg "$MARKDOWN" '{ "systemMessage": $msg }'
+
+exit 0

package/hooks/trace-mcp-reindex.cmd

@@ -0,0 +1,43 @@
+@echo off
+REM trace-mcp-reindex v0.1.0
+REM trace-mcp PostToolUse auto-reindex hook (Windows)
+REM Triggers incremental reindex after Edit/Write/MultiEdit on code files.
+REM Runs trace-mcp index-file in the background - non-blocking.
+REM
+REM Install: add to ~\.claude\settings.json or .claude\settings.local.json under PostToolUse
+REM See README.md for setup instructions.
+
+setlocal enabledelayedexpansion
+
+REM Read JSON from stdin into a temp file
+set "TMPINPUT=%TEMP%\trace-mcp-reindex-input-%RANDOM%.json"
+more > "%TMPINPUT%"
+
+REM Get tool name from env or parse from JSON
+if defined CLAUDE_TOOL_NAME (
+    set "TOOL_NAME=%CLAUDE_TOOL_NAME%"
+) else (
+    for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_name"`) do set "TOOL_NAME=%%i"
+)
+
+REM Only handle edit-like tools
+if /i not "%TOOL_NAME%"=="Edit" if /i not "%TOOL_NAME%"=="Write" if /i not "%TOOL_NAME%"=="MultiEdit" goto :done
+
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "(Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).tool_input.file_path"`) do set "FILE_PATH=%%i"
+
+if "%FILE_PATH%"=="" goto :done
+
+REM Skip non-code files
+echo "%FILE_PATH%" | findstr /i /r "\.md$ \.json$ \.jsonc$ \.yaml$ \.yml$ \.toml$ \.ini$ \.cfg$ \.env \.txt$ \.html$ \.xml$ \.csv$ \.svg$ \.lock$ \.log$ \.sh$ \.bash$ \.zsh$ \.fish$ \.ps1$ \.bat$ \.cmd$" >nul 2>&1
+if %errorlevel%==0 goto :done
+
+REM Skip if not a recognised code file
+echo "%FILE_PATH%" | findstr /i /r "\.ts$ \.tsx$ \.js$ \.jsx$ \.mjs$ \.cjs$ \.py$ \.pyi$ \.go$ \.rs$ \.java$ \.kt$ \.kts$ \.rb$ \.php$ \.cs$ \.cpp$ \.c$ \.h$ \.hpp$ \.swift$ \.scala$ \.vue$ \.svelte$ \.astro$" >nul 2>&1
+if not %errorlevel%==0 goto :done
+
+REM Reindex in background - non-blocking, silent
+start /b "" cmd /c "trace-mcp index-file "%FILE_PATH%" >nul 2>&1"
+
+:done
+del "%TMPINPUT%" 2>nul
+exit /b 0

package/hooks/trace-mcp-worktree.cmd

@@ -0,0 +1,33 @@
+@echo off
+REM trace-mcp-worktree v0.1.0
+REM trace-mcp WorktreeCreate / WorktreeRemove hook
+REM On WorktreeCreate: registers and indexes the new worktree.
+REM On WorktreeRemove: deregisters the worktree project.
+
+setlocal enabledelayedexpansion
+
+set "INPUT="
+for /f "delims=" %%i in ('more') do set "INPUT=!INPUT!%%i"
+
+REM Extract event type
+for /f "delims=" %%e in ('echo !INPUT! ^| jq -r ".hook_event_name // .event // empty" 2^>nul') do set "EVENT=%%e"
+if not defined CLAUDE_HOOK_EVENT set "CLAUDE_HOOK_EVENT=%EVENT%"
+if defined CLAUDE_HOOK_EVENT set "EVENT=%CLAUDE_HOOK_EVENT%"
+
+REM Extract worktree path
+for /f "delims=" %%p in ('echo !INPUT! ^| jq -r ".tool_input.path // .worktree_path // .path // .cwd // empty" 2^>nul') do set "WPATH=%%p"
+
+if "%WPATH%"=="" exit /b 0
+
+if "%EVENT%"=="WorktreeCreate" (
+  start /b trace-mcp add "%WPATH%" --force --json >nul 2>&1
+) else if "%EVENT%"=="WorktreeRemove" (
+  REM Clean up worktree DB file if it exists
+  for /f "delims=" %%h in ('echo %WPATH%^| certutil -hashfile - SHA256 2^>nul ^| findstr /v "hash"') do set "PHASH=%%h"
+  if defined PHASH (
+    set "PHASH=!PHASH:~0,12!"
+    del /q "%USERPROFILE%\.trace-mcp\db\!PHASH!.db" "%USERPROFILE%\.trace-mcp\db\!PHASH!.db-shm" "%USERPROFILE%\.trace-mcp\db\!PHASH!.db-wal" 2>nul
+  )
+)
+
+exit /b 0

package/hooks/trace-mcp-worktree.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# trace-mcp-worktree v0.1.0
+# trace-mcp WorktreeCreate / WorktreeRemove hook
+# On WorktreeCreate: registers and indexes the new worktree so trace-mcp tools work immediately.
+# On WorktreeRemove: deregisters the worktree project from the registry.
+#
+# Install: add to ~/.claude/settings.json or .claude/settings.local.json
+# See README.md for setup instructions.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Claude Code passes the event type via CLAUDE_HOOK_EVENT or hook_event_name
+EVENT="${CLAUDE_HOOK_EVENT:-}"
+if [[ -z "$EVENT" ]]; then
+  EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // .event // empty' 2>/dev/null)
+fi
+
+# Extract worktree path from hook input
+WORKTREE_PATH=$(echo "$INPUT" | jq -r '.tool_input.path // .worktree_path // .path // empty' 2>/dev/null)
+
+if [[ -z "$WORKTREE_PATH" ]]; then
+  # Fallback: use working directory from input
+  WORKTREE_PATH=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+fi
+
+if [[ -z "$WORKTREE_PATH" ]]; then
+  exit 0
+fi
+
+# Resolve to absolute path
+WORKTREE_PATH=$(cd "$WORKTREE_PATH" 2>/dev/null && pwd || echo "$WORKTREE_PATH")
+
+case "$EVENT" in
+  WorktreeCreate|worktree_create|create)
+    # Register and index the new worktree in the background
+    # --force: re-register even if parent repo is already known (worktree is a different root)
+    nohup trace-mcp add "$WORKTREE_PATH" --force --json >/dev/null 2>&1 &
+    ;;
+  WorktreeRemove|worktree_remove|remove)
+    # Clean up the worktree DB file if it exists.
+    # The global registry entry becomes stale but is harmless — next `trace-mcp add` overwrites it.
+    PROJECT_HASH=""
+    if command -v sha256sum >/dev/null 2>&1; then
+      PROJECT_HASH=$(echo -n "$WORKTREE_PATH" | sha256sum | cut -c1-12)
+    elif command -v shasum >/dev/null 2>&1; then
+      PROJECT_HASH=$(echo -n "$WORKTREE_PATH" | shasum -a 256 | cut -c1-12)
+    fi
+    if [[ -n "$PROJECT_HASH" ]]; then
+      DB_FILE="$HOME/.trace-mcp/db/${PROJECT_HASH}.db"
+      rm -f "$DB_FILE" "$DB_FILE-shm" "$DB_FILE-wal" 2>/dev/null
+    fi
+    ;;
+esac
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-mcp",
-  "version": "1.2.1",
+  "version": "1.5.3",
   "description": "Framework-aware code intelligence MCP server — 48+ frameworks, 68 languages",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,7 @@
     "prepublishOnly": "npm run build"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=18.0.0"
   },
   "license": "ELv2",
   "author": "Nikolai Vysotskyi",