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
bash scripts/test-context-recall.sh
```

Expected output: **15/15 tests passed**

## Manual Verification

### 1. Check Hook Files Exist

```bash
ls -la .claude/hooks/
```

Expected files:
- `user-prompt-submit` (executable)
- `task-complete` (executable)
- `README.md`
- `EXAMPLES.md`
- `INSTALL.md` (this file)

### 2. Check Permissions

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

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

If not executable:
```bash
chmod +x .claude/hooks/user-prompt-submit
chmod +x .claude/hooks/task-complete
```

### 3. Check Configuration Exists

```bash
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
bash scripts/setup-context-recall.sh
```

### 4. Test Hooks Manually

**Test user-prompt-submit:**
```bash
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:**
```bash
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

```bash
curl http://localhost:8000/health
```

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

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

### 6. Verify Git Config

```bash
git config --local claude.projectid
```

Expected: A UUID value

If empty, run setup:
```bash
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:**
```bash
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

```bash
# 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!** [OK]

Start using Claude Code and enjoy automatic context recall!