mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
feat: Add core memory clustering visualization and hooks configuration
- Implemented core memory clustering visualization in core-memory-clusters.js - Added functions for loading, rendering, and managing clusters and their members - Created example hooks configuration in hooks-config-example.json for session management - Developed test script for hooks integration in test-hooks.js - Included error handling and notifications for user interactions
This commit is contained in:
catlog22
294
ccw/docs/hooks-integration.md
Normal file
294
ccw/docs/hooks-integration.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Hooks Integration for Progressive Disclosure
|
||||
|
||||
This document describes how to integrate session hooks with CCW's progressive disclosure system.
|
||||
|
||||
## Overview
|
||||
|
||||
CCW now supports automatic context injection via hooks. When a session starts, the system can automatically provide a progressive disclosure index showing related sessions from the same cluster.
|
||||
|
||||
## Features
|
||||
|
||||
- **Automatic Context Injection**: Session start hooks inject cluster context
|
||||
- **Progressive Disclosure**: Shows related sessions, their summaries, and recovery commands
|
||||
- **Silent Failure**: Hook failures don't block session start (< 5 seconds timeout)
|
||||
- **Multiple Hook Types**: Supports `session-start`, `context`, and custom hooks
|
||||
|
||||
## Hook Configuration
|
||||
|
||||
### Location
|
||||
|
||||
Place hook configurations in `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"session-start": [
|
||||
{
|
||||
"name": "Progressive Disclosure",
|
||||
"description": "Injects progressive disclosure index at session start",
|
||||
"enabled": true,
|
||||
"handler": "internal:context",
|
||||
"timeout": 5000,
|
||||
"failMode": "silent"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Hook Types
|
||||
|
||||
#### `session-start`
|
||||
Triggered when a new session begins. Ideal for injecting context.
|
||||
|
||||
#### `context`
|
||||
Triggered on explicit context requests. Same handler as `session-start`.
|
||||
|
||||
#### `session-end`
|
||||
Triggered when a session ends. Useful for updating cluster metadata.
|
||||
|
||||
#### `file-modified`
|
||||
Triggered when files are modified. Can be used for auto-commits or notifications.
|
||||
|
||||
### Hook Properties
|
||||
|
||||
- **`name`**: Human-readable hook name
|
||||
- **`description`**: What the hook does
|
||||
- **`enabled`**: Boolean to enable/disable the hook
|
||||
- **`handler`**: `internal:context` for built-in context generation, or use `command` field
|
||||
- **`command`**: Shell command to execute (alternative to `handler`)
|
||||
- **`timeout`**: Maximum execution time in milliseconds (default: 5000)
|
||||
- **`failMode`**: How to handle failures
|
||||
- `silent`: Ignore errors, don't log
|
||||
- `log`: Log errors but continue
|
||||
- `fail`: Abort on error
|
||||
- **`async`**: Run in background without blocking (default: false)
|
||||
|
||||
### Available Variables
|
||||
|
||||
In `command` fields, use these variables:
|
||||
|
||||
- `$SESSION_ID`: Current session ID
|
||||
- `$FILE_PATH`: File path (for file-modified hooks)
|
||||
- `$PROJECT_PATH`: Current project path
|
||||
- `$CLUSTER_ID`: Active cluster ID (if available)
|
||||
|
||||
## API Endpoint
|
||||
|
||||
### Trigger Hook
|
||||
|
||||
```bash
|
||||
POST http://localhost:3456/api/hook
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"type": "session-start",
|
||||
"sessionId": "WFS-20241218-001",
|
||||
"projectPath": "/path/to/project"
|
||||
}
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"type": "context",
|
||||
"format": "markdown",
|
||||
"content": "<ccw-session-context>...</ccw-session-context>",
|
||||
"sessionId": "WFS-20241218-001"
|
||||
}
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
- `?path=/project/path`: Override project path
|
||||
- `?format=markdown|json`: Response format (default: markdown)
|
||||
|
||||
## Progressive Disclosure Output Format
|
||||
|
||||
The hook returns a structured Markdown document:
|
||||
|
||||
```markdown
|
||||
<ccw-session-context>
|
||||
## 📋 Related Sessions Index
|
||||
|
||||
### 🔗 Active Cluster: {cluster_name} ({member_count} sessions)
|
||||
**Intent**: {cluster_intent}
|
||||
|
||||
| # | Session | Type | Summary | Tokens |
|
||||
|---|---------|------|---------|--------|
|
||||
| 1 | WFS-001 | Workflow | Implement auth | ~1200 |
|
||||
| 2 | CLI-002 | CLI | Fix login bug | ~800 |
|
||||
|
||||
**Resume Commands**:
|
||||
```bash
|
||||
# Load specific session
|
||||
ccw core-memory load {session_id}
|
||||
|
||||
# Load entire cluster context
|
||||
ccw core-memory load-cluster {cluster_id}
|
||||
```
|
||||
|
||||
### 📊 Timeline
|
||||
```
|
||||
2024-12-15 ─●─ WFS-001 (Implement auth)
|
||||
│
|
||||
2024-12-16 ─●─ CLI-002 (Fix login bug) ← Current
|
||||
```
|
||||
|
||||
---
|
||||
**Tip**: Use `ccw core-memory search <keyword>` to find more sessions
|
||||
</ccw-session-context>
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Basic Session Start Hook
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"session-start": [
|
||||
{
|
||||
"name": "Progressive Disclosure",
|
||||
"enabled": true,
|
||||
"handler": "internal:context",
|
||||
"timeout": 5000,
|
||||
"failMode": "silent"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: Custom Command Hook
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"session-end": [
|
||||
{
|
||||
"name": "Update Cluster",
|
||||
"enabled": true,
|
||||
"command": "ccw core-memory update-cluster --session $SESSION_ID",
|
||||
"timeout": 30000,
|
||||
"async": true,
|
||||
"failMode": "log"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 3: File Modification Hook
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"file-modified": [
|
||||
{
|
||||
"name": "Auto Commit",
|
||||
"enabled": false,
|
||||
"command": "git add $FILE_PATH && git commit -m '[Auto] Save: $FILE_PATH'",
|
||||
"timeout": 10000,
|
||||
"async": true,
|
||||
"failMode": "log"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Handler: `internal:context`
|
||||
|
||||
The built-in context handler:
|
||||
|
||||
1. Determines the current session ID
|
||||
2. Queries `SessionClusteringService` for related clusters
|
||||
3. Retrieves cluster members and their metadata
|
||||
4. Generates a progressive disclosure index
|
||||
5. Returns formatted Markdown within `<ccw-session-context>` tags
|
||||
|
||||
### Timeout Behavior
|
||||
|
||||
- Hooks have a maximum execution time (default: 5 seconds)
|
||||
- If timeout is exceeded, the hook is terminated
|
||||
- Behavior depends on `failMode`:
|
||||
- `silent`: Continues without notification
|
||||
- `log`: Logs timeout error
|
||||
- `fail`: Aborts session start (not recommended)
|
||||
|
||||
### Error Handling
|
||||
|
||||
All errors are caught and handled according to `failMode`. The system ensures that hook failures never block the main workflow.
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Hook Trigger
|
||||
|
||||
```bash
|
||||
# Using curl
|
||||
curl -X POST http://localhost:3456/api/hook \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"type":"session-start","sessionId":"test-001"}'
|
||||
|
||||
# Using ccw (if CLI command exists)
|
||||
ccw core-memory context --format markdown
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
|
||||
If a cluster exists:
|
||||
- Table of related sessions
|
||||
- Resume commands
|
||||
- Timeline visualization
|
||||
|
||||
If no cluster exists:
|
||||
- Message indicating no cluster found
|
||||
- Commands to search or trigger clustering
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook Not Triggering
|
||||
|
||||
1. Check that hooks are enabled in `.claude/settings.json`
|
||||
2. Verify the hook type matches the event
|
||||
3. Ensure the server is running on the correct port
|
||||
|
||||
### Timeout Issues
|
||||
|
||||
1. Increase `timeout` value for slow operations
|
||||
2. Use `async: true` for long-running commands
|
||||
3. Check logs for performance issues
|
||||
|
||||
### Empty Context
|
||||
|
||||
1. Ensure clustering has been run: `ccw core-memory cluster --auto`
|
||||
2. Verify session metadata exists
|
||||
3. Check that the session has been added to a cluster
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Progressive disclosure index generation is fast (< 1 second typical)
|
||||
- Uses cached metadata to avoid full session parsing
|
||||
- Timeout enforced to prevent blocking
|
||||
- Failures return empty content instead of errors
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **Dynamic Clustering**: Real-time cluster updates during session
|
||||
- **Multi-Cluster Support**: Show sessions from multiple related clusters
|
||||
- **Relevance Scoring**: Sort sessions by relevance to current task
|
||||
- **Token Budget**: Calculate total token usage for context loading
|
||||
- **Hook Chains**: Execute multiple hooks in sequence
|
||||
- **Conditional Hooks**: Execute hooks based on project state
|
||||
|
||||
## References
|
||||
|
||||
- **Session Clustering**: See `session-clustering-service.ts`
|
||||
- **Core Memory Store**: See `core-memory-store.ts`
|
||||
- **Hook Routes**: See `routes/hooks-routes.ts`
|
||||
- **Example Configuration**: See `hooks-config-example.json`
|
||||
Reference in New Issue
Block a user