claude-hooks/docs/reference/cli-commands.md

# 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
    }
  ]
}
```