claudetools/.claude/hooks/INSTALL.md

Hook Installation Verification

This document helps verify that Claude Code hooks are properly installed.

Quick Check

Run this command to verify installation:

bash scripts/test-context-recall.sh

Expected output: 15/15 tests passed

Manual Verification

1. Check Hook Files Exist

ls -la .claude/hooks/

Expected files:

• user-prompt-submit (executable)
• task-complete (executable)
• README.md
• EXAMPLES.md
• INSTALL.md (this file)

2. Check Permissions

ls -l .claude/hooks/user-prompt-submit
ls -l .claude/hooks/task-complete

Both should show: -rwxr-xr-x (executable)

If not executable:

chmod +x .claude/hooks/user-prompt-submit
chmod +x .claude/hooks/task-complete

3. Check Configuration Exists

cat .claude/context-recall-config.env

Should show:

• CLAUDE_API_URL=http://localhost:8000
• JWT_TOKEN=... (should have a value)
• CONTEXT_RECALL_ENABLED=true

If file missing, run setup:

bash scripts/setup-context-recall.sh

4. Test Hooks Manually

Test user-prompt-submit:

source .claude/context-recall-config.env
bash .claude/hooks/user-prompt-submit

Expected: Either context output or silent success (if no contexts exist)

Test task-complete:

source .claude/context-recall-config.env
export TASK_SUMMARY="Test task"
bash .claude/hooks/task-complete

Expected: Silent success or "✓ Context saved to database"

5. Check API Connectivity

curl http://localhost:8000/health

Expected: {"status":"healthy"} or similar

If fails: Start API with uvicorn api.main:app --reload

6. Verify Git Config

git config --local claude.projectid

Expected: A UUID value

If empty, run setup:

bash scripts/setup-context-recall.sh

Common Issues

Hooks Not Executing

Problem: Hooks don't run when using Claude Code

Solutions:

1. Verify Claude Code supports hooks (see docs)
2. Check hook permissions: chmod +x .claude/hooks/*
3. Test hooks manually (see above)

Context Not Appearing

Problem: No context injected in Claude Code

Solutions:

1. Check API is running: curl http://localhost:8000/health
2. Check JWT token is valid: Run setup again
3. Enable debug: echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env
4. Check if contexts exist: Run a few tasks first

Context Not Saving

Problem: Contexts not persisted to database

Solutions:

1. Check project ID: git config --local claude.projectid
2. Test manually: bash .claude/hooks/task-complete
3. Check API logs for errors
4. Verify JWT token: Run setup again

Permission Denied

Problem: Permission denied when running hooks

Solution:

chmod +x .claude/hooks/user-prompt-submit
chmod +x .claude/hooks/task-complete

API Connection Refused

Problem: Connection refused errors

Solutions:

1. Start API: uvicorn api.main:app --reload
2. Check API URL in config
3. Verify firewall settings

Troubleshooting Commands

# Full system test
bash scripts/test-context-recall.sh

# Check all permissions
ls -la .claude/hooks/ scripts/

# Re-run setup
bash scripts/setup-context-recall.sh

# Enable debug mode
echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env

# Test API
curl http://localhost:8000/health
curl -H "Authorization: Bearer $JWT_TOKEN" http://localhost:8000/api/projects

# View configuration
cat .claude/context-recall-config.env

# Test hooks with debug
bash -x .claude/hooks/user-prompt-submit
bash -x .claude/hooks/task-complete

Expected Workflow

When properly installed:

1. You start Claude Code → user-prompt-submit runs
2. Hook queries database → Retrieves relevant contexts
3. Context injected → You see previous work context
4. You work normally → Claude has full context
5. Task completes → task-complete runs
6. Context saved → Available for next session

All automatic, zero user action required!

Documentation

• Quick Start: .claude/CONTEXT_RECALL_QUICK_START.md
• Full Setup: CONTEXT_RECALL_SETUP.md
• Architecture: .claude/CONTEXT_RECALL_ARCHITECTURE.md
• Hook Details: .claude/hooks/README.md
• Examples: .claude/hooks/EXAMPLES.md

Support

If issues persist after following this guide:

1. Review full documentation (see above)
2. Run full test suite: bash scripts/test-context-recall.sh
3. Check API logs for errors
4. Enable debug mode for verbose output

Success Checklist

• Hook files exist in .claude/hooks/
• Hooks are executable (chmod +x)
• Configuration file exists (.claude/context-recall-config.env)
• JWT token is set in configuration
• Project ID detected or set
• API is running (curl http://localhost:8000/health)
• Test script passes (bash scripts/test-context-recall.sh)
• Hooks execute manually without errors

If all items checked: Installation is complete! ✅

Start using Claude Code and enjoy automatic context recall!