Initial commit: Claude Code Hooks with Diátaxis documentation
✨ Features: - 🧠 Shadow learner that builds intelligence from command patterns - 🛡️ Smart command validation with safety checks - 💾 Automatic context monitoring and backup system - 🔄 Session continuity across Claude restarts 📚 Documentation: - Complete Diátaxis-organized documentation - Learning-oriented tutorial for getting started - Task-oriented how-to guides for specific problems - Information-oriented reference for quick lookup - Understanding-oriented explanations of architecture 🚀 Installation: - One-command installation script - Bootstrap prompt for installation via Claude - Cross-platform compatibility - Comprehensive testing suite 🎯 Ready for real-world use and community feedback! 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
commit
162ca67098
34 changed files with 5904 additions and 0 deletions
394
docs/reference/cli-commands.md
Normal file
394
docs/reference/cli-commands.md
Normal file
|
|
@ -0,0 +1,394 @@
|
|||
# CLI Commands Reference
|
||||
|
||||
## claude-hooks
|
||||
|
||||
Main command-line interface for managing Claude Hooks.
|
||||
|
||||
### Synopsis
|
||||
|
||||
```
|
||||
claude-hooks <command> [options]
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
#### status
|
||||
Display current session status and metrics.
|
||||
|
||||
**Usage**: `claude-hooks status`
|
||||
|
||||
**Output**:
|
||||
- Session ID and duration
|
||||
- Context usage percentage
|
||||
- Tool execution count
|
||||
- Files modified count
|
||||
- Commands executed count
|
||||
- Backup recommendation status
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Success
|
||||
- `1` - Error accessing session data
|
||||
|
||||
---
|
||||
|
||||
#### list-backups
|
||||
List all available backups with metadata.
|
||||
|
||||
**Usage**: `claude-hooks list-backups`
|
||||
|
||||
**Output format**:
|
||||
```
|
||||
🗂️ backup_YYYYMMDD_HHMMSS
|
||||
📅 ISO timestamp
|
||||
📝 backup reason
|
||||
```
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Success, backups listed
|
||||
- `0` - Success, no backups found
|
||||
|
||||
---
|
||||
|
||||
#### patterns
|
||||
Display learned command and context patterns.
|
||||
|
||||
**Usage**: `claude-hooks patterns [--limit N]`
|
||||
|
||||
**Options**:
|
||||
- `--limit N` - Show only top N patterns (default: 10)
|
||||
|
||||
**Output sections**:
|
||||
- Command Patterns: Command name, confidence %, evidence count, success rate %
|
||||
- Context Patterns: Error type, confidence %, evidence count
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Success
|
||||
- `1` - Error accessing patterns database
|
||||
|
||||
---
|
||||
|
||||
#### clear-patterns
|
||||
Remove all learned patterns from the database.
|
||||
|
||||
**Usage**: `claude-hooks clear-patterns`
|
||||
|
||||
**Interactive confirmation**: Prompts for `y/N` confirmation before deletion.
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Success, patterns cleared
|
||||
- `0` - Success, operation cancelled by user
|
||||
- `1` - Error accessing patterns database
|
||||
|
||||
---
|
||||
|
||||
#### export
|
||||
Export all hook data to a directory.
|
||||
|
||||
**Usage**: `claude-hooks export [directory]`
|
||||
|
||||
**Arguments**:
|
||||
- `directory` - Target directory (default: `claude_hooks_export`)
|
||||
|
||||
**Creates**:
|
||||
- `session_data.json` - Current session state and history
|
||||
- `patterns.json` - All learned patterns
|
||||
- `logs/` - Copy of all log files
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Success
|
||||
- `1` - Export failed
|
||||
- `2` - Permission denied
|
||||
|
||||
---
|
||||
|
||||
## Hook Scripts
|
||||
|
||||
### context_monitor.py
|
||||
|
||||
**Type**: UserPromptSubmit hook
|
||||
**Purpose**: Monitor context usage and trigger backups
|
||||
|
||||
**Input format**:
|
||||
```json
|
||||
{
|
||||
"prompt": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Output format**:
|
||||
```json
|
||||
{
|
||||
"allow": true,
|
||||
"message": "Context usage: X.X%"
|
||||
}
|
||||
```
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Always (non-blocking hook)
|
||||
|
||||
---
|
||||
|
||||
### command_validator.py
|
||||
|
||||
**Type**: PreToolUse[Bash] hook
|
||||
**Purpose**: Validate bash commands for safety and success probability
|
||||
|
||||
**Input format**:
|
||||
```json
|
||||
{
|
||||
"tool": "Bash",
|
||||
"parameters": {
|
||||
"command": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Output format**:
|
||||
```json
|
||||
{
|
||||
"allow": boolean,
|
||||
"message": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Command allowed
|
||||
- `1` - Command blocked
|
||||
|
||||
**Messages**:
|
||||
- `⛔ Command blocked: <reason>` - Dangerous pattern detected
|
||||
- `⚠️ <warning>` - Suspicious pattern detected
|
||||
- `🚨 <warning>` - High-confidence failure prediction
|
||||
- `💡 Suggestion: <alternative>` - Alternative command suggested
|
||||
|
||||
---
|
||||
|
||||
### session_logger.py
|
||||
|
||||
**Type**: PostToolUse[*] hook
|
||||
**Purpose**: Log tool executions and update learning data
|
||||
|
||||
**Input format**:
|
||||
```json
|
||||
{
|
||||
"tool": "string",
|
||||
"parameters": {},
|
||||
"success": boolean,
|
||||
"error": "string",
|
||||
"execution_time": number
|
||||
}
|
||||
```
|
||||
|
||||
**Output format**:
|
||||
```json
|
||||
{
|
||||
"allow": true,
|
||||
"message": "Logged <tool> execution"
|
||||
}
|
||||
```
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Always (post-execution hook)
|
||||
|
||||
---
|
||||
|
||||
### session_finalizer.py
|
||||
|
||||
**Type**: Stop hook
|
||||
**Purpose**: Create session documentation and save state
|
||||
|
||||
**Input format**:
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
**Output format**:
|
||||
```json
|
||||
{
|
||||
"allow": true,
|
||||
"message": "Session finalized. Modified X files, used Y tools."
|
||||
}
|
||||
```
|
||||
|
||||
**Exit codes**:
|
||||
- `0` - Always (cleanup hook)
|
||||
|
||||
**Side effects**:
|
||||
- Creates/updates `LAST_SESSION.md`
|
||||
- Creates/updates `ACTIVE_TODOS.md`
|
||||
- May create `RECOVERY_GUIDE.md`
|
||||
- Saves patterns database
|
||||
- Logs session completion
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### config/hooks.json.template
|
||||
|
||||
Template for Claude Code hooks configuration.
|
||||
|
||||
**Template variables**:
|
||||
- `{{INSTALL_PATH}}` - Absolute path to claude-hooks installation
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": "string",
|
||||
"PreToolUse": {
|
||||
"Bash": "string"
|
||||
},
|
||||
"PostToolUse": {
|
||||
"*": "string"
|
||||
},
|
||||
"Stop": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### config/settings.json
|
||||
|
||||
Configuration parameters for hook behavior.
|
||||
|
||||
**Schema**:
|
||||
```json
|
||||
{
|
||||
"context_monitor": {
|
||||
"backup_threshold": number, // 0.0-1.0, default 0.85
|
||||
"emergency_threshold": number, // 0.0-1.0, default 0.95
|
||||
"max_context_tokens": number, // default 200000
|
||||
"tokens_per_char": number, // default 0.25
|
||||
"tool_overhead": number, // default 200
|
||||
"system_overhead": number // default 500
|
||||
},
|
||||
"backup_manager": {
|
||||
"max_backups": number, // default 10
|
||||
"backup_on_critical_ops": boolean, // default true
|
||||
"git_enabled": boolean, // default true
|
||||
"filesystem_backup_enabled": boolean // default true
|
||||
},
|
||||
"shadow_learner": {
|
||||
"max_patterns": number, // default 10000
|
||||
"confidence_threshold": number, // 0.0-1.0, default 0.8
|
||||
"evidence_threshold": number, // default 5
|
||||
"cache_ttl_seconds": number, // default 300
|
||||
"learning_enabled": boolean // default true
|
||||
},
|
||||
"security": {
|
||||
"dangerous_commands_blocked": boolean, // default true
|
||||
"suspicious_commands_warned": boolean, // default true
|
||||
"path_traversal_protection": boolean, // default true
|
||||
"system_files_protection": boolean // default true
|
||||
},
|
||||
"performance": {
|
||||
"rate_limit_ms": number, // default 100
|
||||
"max_hook_execution_time": number, // milliseconds, default 5000
|
||||
"async_logging": boolean, // default true
|
||||
"cache_predictions": boolean // default true
|
||||
},
|
||||
"logging": {
|
||||
"log_level": "DEBUG|INFO|WARNING|ERROR", // default "INFO"
|
||||
"log_executions": boolean, // default true
|
||||
"log_retention_days": number, // default 7
|
||||
"detailed_errors": boolean // default false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
### Runtime Data
|
||||
|
||||
- `.claude_hooks/` - Main data directory
|
||||
- `backups/` - Session backup files
|
||||
- `logs/` - Execution and error logs
|
||||
- `patterns/` - Learned patterns database
|
||||
- `session_state.json` - Current session state
|
||||
|
||||
### Generated Files
|
||||
|
||||
- `LAST_SESSION.md` - Session summary for continuity
|
||||
- `ACTIVE_TODOS.md` - Persistent task list
|
||||
- `RECOVERY_GUIDE.md` - Created when session interrupted
|
||||
|
||||
### Log Files
|
||||
|
||||
- `.claude_hooks/logs/executions_YYYYMMDD.jsonl` - Daily execution logs
|
||||
- `.claude_hooks/logs/session_completions.jsonl` - Session completion events
|
||||
- `.claude_hooks/backups/backup.log` - Backup operation log
|
||||
|
||||
---
|
||||
|
||||
## Data Formats
|
||||
|
||||
### Pattern Database Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"command_patterns": {
|
||||
"command_name": {
|
||||
"pattern_id": "string",
|
||||
"pattern_type": "command_execution",
|
||||
"trigger": {"command": "string"},
|
||||
"prediction": {
|
||||
"success_count": number,
|
||||
"failure_count": number,
|
||||
"common_errors": ["string"]
|
||||
},
|
||||
"confidence": number,
|
||||
"evidence_count": number,
|
||||
"last_seen": "ISO timestamp",
|
||||
"success_rate": number
|
||||
}
|
||||
},
|
||||
"context_patterns": {
|
||||
"pattern_id": {
|
||||
"pattern_type": "context_error",
|
||||
"trigger": {
|
||||
"tool": "string",
|
||||
"error_type": "string"
|
||||
},
|
||||
"prediction": {
|
||||
"likely_error": "string",
|
||||
"suggestions": ["string"]
|
||||
},
|
||||
"confidence": number,
|
||||
"evidence_count": number,
|
||||
"last_seen": "ISO timestamp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Session State Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "string",
|
||||
"start_time": "ISO timestamp",
|
||||
"last_activity": "ISO timestamp",
|
||||
"modified_files": ["string"],
|
||||
"commands_executed": [
|
||||
{
|
||||
"command": "string",
|
||||
"timestamp": "ISO timestamp"
|
||||
}
|
||||
],
|
||||
"tool_usage": {
|
||||
"tool_name": number
|
||||
},
|
||||
"backup_history": [
|
||||
{
|
||||
"backup_id": "string",
|
||||
"timestamp": "ISO timestamp",
|
||||
"reason": "string",
|
||||
"success": boolean
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue