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:

{
  "prompt": "string"
}

Output format:

{
  "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:

{
  "tool": "Bash",
  "parameters": {
    "command": "string"
  }
}

Output format:

{
  "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:

{
  "tool": "string",
  "parameters": {},
  "success": boolean,
  "error": "string",
  "execution_time": number
}

Output format:

{
  "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:

{}

Output format:

{
  "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:

{
  "hooks": {
    "UserPromptSubmit": "string",
    "PreToolUse": {
      "Bash": "string"
    },
    "PostToolUse": {
      "*": "string"
    },
    "Stop": "string"
  }
}

---

config/settings.json

Configuration parameters for hook behavior.

Schema:

{
  "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

{
  "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

{
  "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
    }
  ]
}