Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
319 lines (231 loc) · 5.93 KB

TROUBLESHOOTING.md

File metadata and controls

319 lines (231 loc) · 5.93 KB
Raw

Troubleshooting Guide

Common issues and solutions for Claude Context Kit.

Quick Diagnostics

Run these commands to check your installation:

# Check hooks installed
ls ~/.claude/hooks/

# Check commands installed
ls ~/.claude/commands/

# Check settings configured
cat ~/.claude/settings.json | grep -A 20 "hooks"

# Check daemon files
ls ~/.claude/memory/daemon/

# Test daemon health (if running)
curl http://localhost:8741/health

Common Issues

Hooks Not Firing

Symptoms:

  • Sessions not appearing in registry
  • Memory not being injected
  • No handoff files created

Solutions:

  1. Check settings.json has hooks configured:

    cat ~/.claude/settings.json

    Should contain "hooks": { "SessionStart": [...], ... }

  2. Verify hook files exist:

    # Unix
ls -la ~/.claude/hooks/*.sh

# Windows
dir %USERPROFILE%\.claude\hooks\*.ps1

  3. Check file permissions (Unix):

    chmod +x ~/.claude/hooks/*.sh

  4. Check PowerShell execution policy (Windows):

    Get-ExecutionPolicy
# If restricted:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  5. Test hook manually:

    # Unix
~/.claude/hooks/session-start.sh

# Windows PowerShell
& "$env:USERPROFILE\.claude\hooks\session-start.ps1"

Daemon Not Starting

Symptoms:

  • /fork-detect returns no results
  • Memory injection not working
  • Connection refused errors

Solutions:

  1. Check Python version:

    python3 --version  # Should be 3.8+

  2. Install dependencies:

    pip install flask sentence-transformers torch

  3. Start daemon manually:

    cd ~/.claude/memory/daemon
python server.py

  4. Check for port conflicts:

    # Unix
lsof -i :8741

# Windows
netstat -ano | findstr :8741

  5. Try different port: Edit ~/.claude/context-kit/config.json:

    { "daemon": { "port": 8742 } }

Memory Recall Not Working

Symptoms:

  • No <recalled-learnings> in responses
  • Memories stored but not retrieved

Solutions:

  1. Verify daemon is running:

    curl http://localhost:8741/health

  2. Check database exists:

    ls ~/.claude/memory/semantic-memory.db

  3. Check memories exist:

    sqlite3 ~/.claude/memory/semantic-memory.db "SELECT COUNT(*) FROM memories;"

  4. Lower recall threshold: Edit ~/.claude/context-kit/config.json:

    { "memory": { "minConfidence": 0.30 } }

Fork Detection Returns No Results

Symptoms:

  • /fork-detect shows no matches
  • "No similar sessions found"

Solutions:

  1. Check sessions are indexed:

    sqlite3 ~/.claude/memory/semantic-memory.db "SELECT COUNT(*) FROM transcript_chunks;"

  2. Run migration for existing sessions:

    /migrate-sessions

  3. Lower similarity threshold: Edit config:

    { "forkDetect": { "minSimilarity": 0.30 } }

  4. Check session registry:

    cat ~/.claude/session-registry.json | head -50

Session Handoff Files Missing

Symptoms:

  • /resume shows no pending sessions
  • Handoff not created after compaction

Solutions:

  1. Check handoff directory:

    ls ~/.claude/session-handoff/pending/

  2. Verify PreCompact hook is registered:

    cat ~/.claude/settings.json | grep PreCompact

  3. Check for orphaned transcripts:

    ls ~/.claude/session-handoff/orphaned/

  4. Manually trigger handoff: Run /post-compact after seeing compaction message

Windows-Specific Issues

Path Errors

Symptom: Scripts fail with "file not found" errors

Solution: Ensure paths in settings.json use proper escaping:

{
  "hooks": {
    "SessionStart": [
      { "command": "powershell.exe -ExecutionPolicy Bypass -File \"C:\\Users\\name\\.claude\\hooks\\session-start.ps1\"" }
    ]
  }
}

Git Bash Compatibility

Symptom: Scripts work in PowerShell but not Git Bash

Solution: The kit uses PowerShell scripts on Windows. Ensure hooks reference .ps1 files, not .sh.

macOS-Specific Issues

Apple Silicon (M1/M2/M3)

Symptom: Slow embedding generation

Solution: Ensure using Metal acceleration:

{ "embedding": { "device": "mps" } }

Homebrew Python

Symptom: Wrong Python version used

Solution: Specify full path:

/opt/homebrew/bin/python3 -m pip install ...

Linux-Specific Issues

CUDA Not Detected

Symptom: Using CPU instead of GPU

Solutions:

  1. Check NVIDIA driver:

    nvidia-smi

  2. Install CUDA toolkit:

    # Ubuntu
sudo apt install nvidia-cuda-toolkit

  3. Install PyTorch with CUDA:

    pip install torch --index-url https://download.pytorch.org/whl/cu118

Reset Installation

If issues persist, try a clean reinstall:

# Backup current config
cp ~/.claude/settings.json ~/.claude/settings.backup.json
cp ~/.claude/context-kit/config.json ~/.claude/context-kit/config.backup.json

# Remove installed components
rm -rf ~/.claude/hooks/session-start*
rm -rf ~/.claude/hooks/pre-compact*
rm -rf ~/.claude/hooks/user-prompt-submit*
rm -rf ~/.claude/hooks/stop*
rm -rf ~/.claude/memory/daemon
rm -rf ~/.claude/context-kit

# Re-run installer
cd claude-context-kit
node install.js

Getting Help

If you can't resolve an issue:

  1. Check existing issues: https://github.com/your-username/claude-context-kit/issues

  2. Create new issue with:

    • OS and version
    • Node.js version (node -v)
    • Python version (python3 --version)
    • Relevant error messages
    • Output of diagnostic commands above

  3. Include debug logs: Enable debug mode:

    { "debug": { "enabled": true, "logLevel": "debug" } }