docs: Add File Watcher Hooks Quick Start Guide
- Documents the automatic hook setup in initialize-project
- Shows before/after comparison
- Provides default folder mappings for each MCP type
- Includes troubleshooting guide and testing procedures
- Lists API endpoints for manual hook management
- Adds FAQ section
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bob Roberts
parent
b6d86f2f60
commit
9058cab4d1
1 changed files with 230 additions and 0 deletions
230
HOOK_SETUP_QUICK_START.md
Normal file
230
HOOK_SETUP_QUICK_START.md
Normal file
|
|
@ -0,0 +1,230 @@
|
|||
# File Watcher Hooks - Quick Start Guide
|
||||
|
||||
## What Changed?
|
||||
|
||||
The `initialize-project` skill now **automatically configures file watchers** for your project's knowledge bases. No more manual setup needed!
|
||||
|
||||
## Before vs After
|
||||
|
||||
### Before (Manual Setup Required)
|
||||
```bash
|
||||
# Initialize project
|
||||
initialize-project: 1
|
||||
|
||||
# Then manually enable hooks via API
|
||||
curl -X POST http://localhost:8051/api/projects/1/hooks/knowledge_docs/enable \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"folder_path": "/path/to/knowledge_docs"}'
|
||||
|
||||
# Then manually start the file watcher
|
||||
curl -X POST http://localhost:8051/api/watcher/start/1
|
||||
|
||||
# Only THEN would new files auto-sync
|
||||
```
|
||||
|
||||
### After (Fully Automatic)
|
||||
```bash
|
||||
# Initialize project
|
||||
initialize-project: 1
|
||||
|
||||
# ✨ File watchers are now automatically configured!
|
||||
# New files will be auto-synced immediately
|
||||
```
|
||||
|
||||
## How File Watchers Work
|
||||
|
||||
When you initialize a project, the system automatically:
|
||||
|
||||
1. **Creates hooks for all 4 MCP types:**
|
||||
- `knowledge_docs` → Watches your project's documentation folder
|
||||
- `project_profile` → Watches `.claude-os/project-profile/`
|
||||
- `project_index` → Watches `.claude-os/project-index/`
|
||||
- `project_memories` → Watches `.claude-os/memories/`
|
||||
|
||||
2. **Starts the file watcher service**
|
||||
- Monitors all configured folders
|
||||
- Detects file changes within ~2 seconds
|
||||
- Automatically syncs changes to knowledge bases
|
||||
|
||||
3. **Creates the necessary folders**
|
||||
- Project folders are created if they don't exist
|
||||
- Ready to accept new files immediately
|
||||
|
||||
## Default Folder Mappings
|
||||
|
||||
| MCP Type | Default Folder | Behavior |
|
||||
|----------|---|---|
|
||||
| `knowledge_docs` | `docs/` (or `documentation/`) | Watches for markdown, text, PDF files |
|
||||
| `project_profile` | `.claude-os/project-profile/` | Auto-created, stores profile docs |
|
||||
| `project_index` | `.claude-os/project-index/` | Auto-created, stores code index |
|
||||
| `project_memories` | `.claude-os/memories/` | Auto-created, stores insights |
|
||||
|
||||
## Using Custom Folders
|
||||
|
||||
If you want to use a different folder for `knowledge_docs`:
|
||||
|
||||
```bash
|
||||
# Create your custom folder
|
||||
mkdir my-docs
|
||||
|
||||
# Enable hook for custom folder
|
||||
curl -X POST "http://localhost:8051/api/projects/1/hooks/knowledge_docs/enable" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"folder_path": "/path/to/my-docs"}'
|
||||
|
||||
# Restart the watcher to pick up changes
|
||||
curl -X POST "http://localhost:8051/api/watcher/restart/1"
|
||||
```
|
||||
|
||||
## Verify Hooks Are Working
|
||||
|
||||
### Check Watcher Status
|
||||
```bash
|
||||
curl http://localhost:8051/api/watcher/status
|
||||
```
|
||||
|
||||
Expected output shows your project is being watched:
|
||||
```json
|
||||
{
|
||||
"status": {
|
||||
"enabled": true,
|
||||
"projects_watched": 1,
|
||||
"projects": {
|
||||
"1": {
|
||||
"watched_paths": {
|
||||
"knowledge_docs": "/path/to/docs",
|
||||
"project_profile": "/path/to/.claude-os/project-profile",
|
||||
...
|
||||
},
|
||||
"event_handlers": ["knowledge_docs", "project_profile", ...]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Check Hooks Configuration
|
||||
```bash
|
||||
cat /path/to/project/.claude-os/hooks.json
|
||||
```
|
||||
|
||||
Should show something like:
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"project_id": 1,
|
||||
"hooks": {
|
||||
"knowledge_docs": {
|
||||
"enabled": true,
|
||||
"folder_path": "/path/to/docs",
|
||||
"synced_files": {}
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Auto-Sync
|
||||
|
||||
### Test knowledge_docs Auto-Sync
|
||||
```bash
|
||||
# Create a test file
|
||||
echo "# Test Document" > /path/to/docs/test.md
|
||||
|
||||
# Wait 2-3 seconds for the watcher to pick it up
|
||||
|
||||
# Verify it was indexed
|
||||
sqlite3 /path/to/claude-os/data/claude-os.db \
|
||||
"SELECT COUNT(*) FROM documents WHERE doc_id LIKE 'test.md%' AND kb_id = 1"
|
||||
```
|
||||
|
||||
Should show a count > 0 if successfully indexed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hooks not triggering auto-sync?
|
||||
|
||||
1. **Check if watcher is running:**
|
||||
```bash
|
||||
curl http://localhost:8051/api/watcher/status
|
||||
```
|
||||
If `"enabled": false`, start it:
|
||||
```bash
|
||||
curl -X POST "http://localhost:8051/api/watcher/start/1"
|
||||
```
|
||||
|
||||
2. **Check hooks configuration:**
|
||||
```bash
|
||||
cat .claude-os/hooks.json
|
||||
```
|
||||
Verify `"enabled": true` for your MCP type
|
||||
|
||||
3. **Check folder permissions:**
|
||||
- Ensure folder is readable by the MCP server
|
||||
- Try creating a test file manually
|
||||
|
||||
4. **Check MCP server logs:**
|
||||
- Look for errors in `/private/tmp/` or application logs
|
||||
- Check if server is running: `ps aux | grep python | grep server`
|
||||
|
||||
### Files not appearing in search?
|
||||
|
||||
1. **Verify files were indexed:**
|
||||
```bash
|
||||
sqlite3 /path/to/claude-os/data/claude-os.db \
|
||||
"SELECT COUNT(*) FROM documents WHERE kb_id = 1"
|
||||
```
|
||||
|
||||
2. **Check file format is supported:**
|
||||
- Default: `.md`, `.txt`, `.pdf`, `.py`, `.js`, `.ts`, `.json`, `.yaml`
|
||||
- Configure custom patterns in hooks.json `file_patterns` array
|
||||
|
||||
3. **Manually trigger sync:**
|
||||
```bash
|
||||
curl -X POST "http://localhost:8051/api/projects/1/hooks/sync?mcp_type=knowledge_docs"
|
||||
```
|
||||
|
||||
## Advanced: Restart Watchers
|
||||
|
||||
If watchers stop responding:
|
||||
|
||||
```bash
|
||||
# Restart a specific project's watcher
|
||||
curl -X POST "http://localhost:8051/api/watcher/restart/1"
|
||||
|
||||
# Or restart all watchers
|
||||
# (Note: not available via API, requires server restart)
|
||||
```
|
||||
|
||||
## Git Integration
|
||||
|
||||
The system also installs **git post-commit hooks** that:
|
||||
- Auto-index changed files on each commit
|
||||
- Periodically expand the index with new files (every 10 commits)
|
||||
- Track commit count for smart indexing
|
||||
|
||||
This works seamlessly with the file watcher hooks.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Do I need to restart anything after running initialize-project?**
|
||||
A: No! Everything is set up automatically. File watchers start immediately.
|
||||
|
||||
**Q: Can I add files while the watcher is running?**
|
||||
A: Yes! Add files anytime. They'll be indexed within ~2 seconds.
|
||||
|
||||
**Q: What if I want to disable auto-sync for a folder?**
|
||||
A: Disable the hook via API:
|
||||
```bash
|
||||
curl -X POST "http://localhost:8051/api/projects/1/hooks/knowledge_docs/disable"
|
||||
```
|
||||
|
||||
**Q: Can multiple projects have watchers running?**
|
||||
A: Yes! The system can monitor multiple projects simultaneously.
|
||||
|
||||
**Q: Do file watchers persist after server restart?**
|
||||
A: No, watchers stop when the server restarts. They'll restart automatically when projects are loaded.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** October 28, 2025
|
||||
Loading…
Add table
Reference in a new issue