claude-git-hooks 2.3.1 → 2.4.1

package/CHANGELOG.md

@@ -5,6 +5,90 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.1] - 2025-11-19
+
+### 🐛 Fixed
+
+- **Git Bash Windows Support** - Claude hooks now works correctly on Git Bash in Windows
+  - **What changed**:
+    - `--skip-auth` now skips both Claude CLI verification AND authentication (previously only auth)
+    - Windows detection now tries native Claude first, WSL as fallback
+    - `spawn()` now uses `shell: true` to resolve `.cmd`/`.bat` executables
+  - **Why**:
+    - Installation with `--skip-auth` was failing before copying `.md` files and presets
+    - Code assumed Claude must always run via WSL on Windows, ignoring native installations
+    - Git Bash runs Node.js natively on Windows, not in WSL
+    - `spawn()` without shell couldn't find Windows batch files
+  - **Files updated**:
+    - `bin/claude-hooks:512-518` - Skip auth now skips Claude CLI check
+    - `bin/claude-hooks:532-544` - Native Windows Claude detection
+    - `lib/utils/claude-client.js:75-115` - Smart platform detection with fallback
+    - `lib/utils/claude-client.js:145-148` - Added `shell: true` for Windows compatibility
+  - **Impact**: Git Bash users on Windows can now use native Claude (via npm/NVM) instead of requiring WSL
+
+### 🎯 User Experience
+
+- **Installation**: `claude-hooks install --skip-auth` now completes successfully, installing all templates and presets
+- **NVM Compatibility**: Works with Claude CLI installed via npm in current Node version (NVM managed)
+- **Flexible Setup**: Automatically detects and uses best available Claude CLI method (native Windows or WSL)
+
+## [2.4.0] - 2025-11-17
+
+### ⚠️ BREAKING CHANGES
+
+- **Debug Mode** - Environment variable `DEBUG` no longer supported
+  - **What changed**: Removed `DEBUG` environment variable support from `lib/utils/logger.js`
+  - **Why**: Aligns with project philosophy "no environment variables" and provides better user experience
+  - **Migration**: Use `claude-hooks --debug true` instead of `DEBUG=1 git commit`
+  - **Alternative**: Set `"system": { "debug": true }` in `.claude/config.json`
+
+### 🔄 Changed
+
+- **File Size Limit Increased** - Default `maxFileSize` increased from 100KB to 1MB
+  - **What changed**: `analysis.maxFileSize` now defaults to 1000000 (1MB) instead of 100000 (100KB)
+  - **Why**: Previous 100KB limit was too restrictive, rejected many legitimate source files
+  - **Files updated**:
+    - `lib/config.js:29` - Default configuration
+    - All preset configs in `templates/presets/*/config.json`
+    - `templates/config.example.json`
+  - **Impact**: More files will be analyzed without manual config adjustment
+  - **User action**: If you want stricter limits, set `"maxFileSize": 100000` in `.claude/config.json`
+
+### ✨ Added
+
+- **Debug CLI Command** - New `--debug` flag for managing debug mode
+  - **Usage**: `claude-hooks --debug <true|false|status>`
+  - **Purpose**: Enables detailed logging for troubleshooting
+  - **Implementation**: Generic `updateConfig()` function in `bin/claude-hooks:1262`
+  - **Benefits**: Consistent with `--set-preset` pattern, no need to remember env var syntax
+
+- **Generic Config Updater** - Reusable `updateConfig()` function
+  - **Purpose**: Centralized config update logic for all CLI commands
+  - **Location**: `bin/claude-hooks:1262`
+  - **Features**: Dot notation path support, custom validators, custom success messages
+  - **Extensibility**: Easy to add new config commands (`--set-max-files`, `--set-timeout`, etc.)
+
+### 🔄 Changed
+
+- **setPreset() Refactored** - Now uses generic `updateConfig()` function
+  - **Effect**: Less code duplication, consistent error handling
+  - **Location**: `bin/claude-hooks:1349`
+
+- **Debug Mode Activation** - Hooks now enable debug from config
+  - **Files**: `lib/hooks/pre-commit.js:185`, `lib/hooks/prepare-commit-msg.js:124`
+  - **Effect**: Debug logs appear when `config.system.debug` is true
+
+### 📚 Documentation
+
+- **Help Text Updated** - Added `--debug` command documentation
+  - **Location**: `bin/claude-hooks:1170`
+  - **Includes**: Command description, examples, debug mode section
+
+- **README.md Updated** - Debug command documented in multiple sections
+  - **Cheatsheet**: Added debug commands to "Comandos Frecuentes" (line 52-56)
+  - **Tips**: Updated tip #4 with CLI command (line 269)
+  - **Features**: Updated debug mode description (line 492)
+
 ## [2.3.1] - 2025-11-13
 
 ### 🔄 Changed

package/README.md

@@ -48,6 +48,12 @@ claude-hooks --set-preset <name>
 
 # Mostrar preset actual
 claude-hooks preset current
+
+# Activar modo debug
+claude-hooks --debug true
+
+# Ver estado de debug
+claude-hooks --debug status
 ```
 
 ### 📦 Instalación y Gestión
@@ -96,6 +102,10 @@ git commit --no-verify -m "hotfix: corrección urgente"
 git commit --amend
 ```
 
+## 📆 Próximos Desarrollos
+
+Toda idea es bienvenida, aunque parezca espantosa. Si hay bugs, incluirlos también. Dónde? en https://github.com/mscope-S-L/git-hooks/issues/new.
+
 ### ⚠️ Exclusión de Código del Análisis (EXPERIMENTAL/BROKEN)
 
 ```java
@@ -127,7 +137,7 @@ cat > .claude/config.json << 'EOF'
 {
   "preset": "backend",
   "analysis": {
-    "maxFileSize": 150000,
+    "maxFileSize": 1000000,
     "maxFiles": 12,
     "timeout": 150000
   },
@@ -149,14 +159,14 @@ EOF
 
 #### 🎯 Presets Disponibles
 
-| Preset        | Extensiones de Archivo                                                     | Caso de Uso      | Tech Stack                   |
-| ------------- | -------------------------------------------------------------------------- | ---------------- | ---------------------------- |
-| **backend**   | `.java`, `.xml`, `.yml`, `.yaml`                                           | APIs Spring Boot | Spring Boot, JPA, SQL Server |
-| **frontend**  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | Apps React       | React, Redux, Material-UI    |
-| **fullstack** | Todos backend + frontend                                                   | Apps full-stack  | Spring Boot + React          |
-| **database**  | `.sql`                                                                     | Scripts de BD    | SQL Server, T-SQL            |
-| **ai**        | `.js`, `.json`, `.md`, `.sh`                                               | Herramientas CLI | Node.js, Claude API          |
-| **default**   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Propósito general| Lenguajes mixtos             |
+| Preset        | Extensiones de Archivo                                                     | Caso de Uso       | Tech Stack                   |
+| ------------- | -------------------------------------------------------------------------- | ----------------- | ---------------------------- |
+| **backend**   | `.java`, `.xml`, `.yml`, `.yaml`                                           | APIs Spring Boot  | Spring Boot, JPA, SQL Server |
+| **frontend**  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | Apps React        | React, Redux, Material-UI    |
+| **fullstack** | Todos backend + frontend                                                   | Apps full-stack   | Spring Boot + React          |
+| **database**  | `.sql`                                                                     | Scripts de BD     | SQL Server, T-SQL            |
+| **ai**        | `.js`, `.json`, `.md`, `.sh`                                               | Herramientas CLI  | Node.js, Claude API          |
+| **default**   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Propósito general | Lenguajes mixtos             |
 
 ---
 
@@ -260,9 +270,9 @@ git commit -m "fix: resolver issues"
 1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere
 2. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
 3. **Force install**: Usa `--force` para reinstalar sin confirmación
-4. **Debug**: Activa en `.claude/config.json`: `{"system": {"debug": true}}`
-5. **Archivos grandes**: Se omiten automáticamente archivos > 100KB
-6. **Límite de archivos**: Máximo 10 archivos por commit (configurable)
+4. **Debug**: Activa con `claude-hooks --debug true` o en `.claude/config.json`: `{"system": {"debug": true}}`
+5. **Archivos grandes**: Se omiten automáticamente archivos > 1MB
+6. **Límite de archivos**: Máximo 30 archivos por commit (configurable)
 
 ### 🚀 Parallel Analysis (v2.2.0+)
 
@@ -415,9 +425,6 @@ Durante la instalación, Claude Hooks actualiza automáticamente tu `.gitignore`
 ```gitignore
 # Claude Git Hooks
 .claude/
-debug-claude-response.json
-claude_resolution_prompt.md
-.claude-pr-analysis.json
 ```
 
 Esto asegura que:
@@ -435,8 +442,8 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 1. **Intercepta cada intento de commit**
 2. **Extrae y filtra archivos modificados**:
     - Solo analiza: Java, XML, properties, yml, yaml
-    - Omite archivos mayores a 100KB
-    - Límite de 10 archivos por commit
+    - Omite archivos mayores a 1MB
+    - Límite de 30 archivos por commit
 3. **Construye prompt inteligente**:
     - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
     - Lee las pautas desde `.claude/CLAUDE_PRE_COMMIT*.md`
@@ -462,7 +469,7 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - `"auto"`
 2. **Analiza los cambios del staging area**:
     - Lista archivos modificados con estadísticas
-    - Incluye diffs completos para archivos < 100KB
+    - Incluye diffs completos para archivos < 1MB
 3. **Genera mensaje en formato Conventional Commits**:
     - Determina tipo: feat, fix, docs, style, refactor, test, chore
     - Crea título conciso y descriptivo
@@ -483,7 +490,7 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - 📝 Archivo `.claude-pr-analysis.json`
 - **Auto-actualización**: Verificación automática de versiones antes de cada commit con prompt interactivo para actualizar
 - **Comando update**: `claude-hooks update` para actualizar manualmente a la última versión
-- **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
+- **Modo debug**: `claude-hooks --debug true` activa logging detallado para troubleshooting
 - **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
 - **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar
 - **⚠️ Exclusión de código del análisis (EXPERIMENTAL/BROKEN)**: Los marcadores `// SKIP_ANALYSIS_LINE` y `// SKIP_ANALYSIS_BLOCK` no funcionan correctamente. El hook analiza git diff en lugar del archivo completo, por lo que marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
@@ -530,13 +537,13 @@ claude-hooks status
 
 En `lib/hooks/pre-commit.js`:
 
-- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 100KB)
-- **`MAX_FILES`**: Número máximo de archivos por commit (default: 10)
+- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 1MB)
+- **`MAX_FILES`**: Número máximo de archivos por commit (default: 30)
 - **`ALLOWED_EXTENSIONS`**: Extensiones permitidas (default: .java, .xml, .properties, .yml, .yaml)
 
 En `lib/hooks/prepare-commit-msg.js`:
 
-- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 100KB)
+- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 1MB)
 
 ### Pautas de Evaluación
 
@@ -610,34 +617,36 @@ claude-git-hooks/
 
 #### Core Utilities
 
-| Module | Purpose | Key Exports | Usage Context |
-|--------|---------|-------------|---------------|
-| **`config.js`** | Centralized configuration management | `getConfig()`, `defaults` | Priority merging: defaults < user < preset |
-| **`logger.js`** | Structured logging with debug support | `info()`, `warning()`, `error()`, `debug()` | Console output with context tracking |
-| **`git-operations.js`** | Git command abstractions | `getRepoRoot()`, `getStagedFiles()`, `getDiff()` | Safe git operations with error handling |
-| **`file-utils.js`** | File system operations | `ensureDir()`, `writeFile()` | Repo-root-relative path handling |
-| **`claude-client.js`** | Claude CLI integration | `analyzeCode()`, `analyzeCodeParallel()` | Prompt execution with timeout/retry |
-| **`prompt-builder.js`** | Template-based prompts | `buildAnalysisPrompt()`, `loadTemplate()` | Dynamic prompt construction from .md files |
-| **`preset-loader.js`** | Preset system | `loadPreset()`, `listPresets()`, `loadTemplate()` | Metadata, config, template loading |
-| **`resolution-prompt.js`** | Issue resolution prompts | `generateResolutionPrompt()` | AI-friendly error remediation prompts |
-| **`installation-diagnostics.js`** | Installation error diagnostics | `formatError()`, `getInstallationDiagnostics()` | Installation error formatting with remediation |
-| **`claude-diagnostics.js`** | Claude CLI error diagnostics | `detectClaudeError()`, `formatClaudeError()` | Rate limit, auth, network error detection |
+| Module                            | Purpose                               | Key Exports                                       | Usage Context                                  |
+| --------------------------------- | ------------------------------------- | ------------------------------------------------- | ---------------------------------------------- |
+| **`config.js`**                   | Centralized configuration management  | `getConfig()`, `defaults`                         | Priority merging: defaults < user < preset     |
+| **`logger.js`**                   | Structured logging with debug support | `info()`, `warning()`, `error()`, `debug()`       | Console output with context tracking           |
+| **`git-operations.js`**           | Git command abstractions              | `getRepoRoot()`, `getStagedFiles()`, `getDiff()`  | Safe git operations with error handling        |
+| **`file-utils.js`**               | File system operations                | `ensureDir()`, `writeFile()`                      | Repo-root-relative path handling               |
+| **`claude-client.js`**            | Claude CLI integration                | `analyzeCode()`, `analyzeCodeParallel()`          | Prompt execution with timeout/retry            |
+| **`prompt-builder.js`**           | Template-based prompts                | `buildAnalysisPrompt()`, `loadTemplate()`         | Dynamic prompt construction from .md files     |
+| **`preset-loader.js`**            | Preset system                         | `loadPreset()`, `listPresets()`, `loadTemplate()` | Metadata, config, template loading             |
+| **`resolution-prompt.js`**        | Issue resolution prompts              | `generateResolutionPrompt()`                      | AI-friendly error remediation prompts          |
+| **`installation-diagnostics.js`** | Installation error diagnostics        | `formatError()`, `getInstallationDiagnostics()`   | Installation error formatting with remediation |
+| **`claude-diagnostics.js`**       | Claude CLI error diagnostics          | `detectClaudeError()`, `formatClaudeError()`      | Rate limit, auth, network error detection      |
 
 #### Using Utilities in Other Claude Instances
 
 **Example: Check installation health**
+
 ```javascript
 import { formatError } from './lib/utils/installation-diagnostics.js';
 
 try {
-  // ... operation that may fail
+    // ... operation that may fail
 } catch (error) {
-  console.error(formatError('Operation failed', ['Additional context line']));
-  process.exit(1);
+    console.error(formatError('Operation failed', ['Additional context line']));
+    process.exit(1);
 }
 ```
 
 **Example: Load configuration**
+
 ```javascript
 import { getConfig } from './lib/config.js';
 
@@ -646,6 +655,7 @@ const maxFiles = config.analysis.maxFiles;
 ```
 
 **Example: Execute git operations**
+
 ```javascript
 import { getRepoRoot, getStagedFiles } from './lib/utils/git-operations.js';
 
@@ -654,13 +664,14 @@ const files = getStagedFiles({ extensions: ['.js', '.ts'] });
 ```
 
 **Example: Build custom prompts**
+
 ```javascript
 import { buildAnalysisPrompt } from './lib/utils/prompt-builder.js';
 
 const prompt = await buildAnalysisPrompt({
-  templateName: 'CUSTOM_PROMPT.md',
-  files: filesData,
-  metadata: { REPO_NAME: 'my-repo' }
+    templateName: 'CUSTOM_PROMPT.md',
+    files: filesData,
+    metadata: { REPO_NAME: 'my-repo' }
 });
 ```
 

package/bin/claude-hooks

@@ -468,6 +468,7 @@ async function install(args) {
   console.log('  📝 Edit .claude/config.json to customize settings');
   console.log('  🎯 Use presets: backend, frontend, fullstack, database, ai, default');
   console.log('  🚀 Enable parallel analysis: set subagents.enabled = true');
+  console.log('  🐛 Enable debug mode: claude-hooks --debug true');
   console.log('\n📖 Example config.json:');
   console.log('  {');
   console.log('    "preset": "backend",');
@@ -508,14 +509,12 @@ async function checkAndInstallDependencies(sudoPassword = null, skipAuth = false
 
   // v2.0.0+: Unix tools (sed, awk, grep, etc.) no longer needed (pure Node.js implementation)
 
-  // Check and install Claude CLI
-  await checkAndInstallClaude();
-
-  // Check Claude authentication (if not skipped)
+  // Check and install Claude CLI (skip if --skip-auth)
   if (!skipAuth) {
+    await checkAndInstallClaude();
     await checkClaudeAuth();
   } else {
-    warning('Skipping Claude authentication verification (--skip-auth)');
+    warning('Skipping Claude CLI verification and authentication (--skip-auth)');
   }
 
   // Clear password from memory
@@ -529,9 +528,19 @@ function isWindows() {
 }
 
 // Get Claude command based on platform
-// Why: On Windows, Claude CLI runs in WSL, so we need 'wsl claude'
+// Why: On Windows, try native Claude first, then WSL as fallback
 function getClaudeCommand() {
-  return isWindows() ? 'wsl claude' : 'claude';
+  if (isWindows()) {
+    // Try native Windows Claude first
+    try {
+      execSync('claude --version', { stdio: 'ignore', timeout: 3000 });
+      return 'claude';
+    } catch (e) {
+      // Fallback to WSL
+      return 'wsl claude';
+    }
+  }
+  return 'claude';
 }
 
 // Check if we need to install dependencies
@@ -1167,6 +1176,7 @@ Commands:
   presets              List all available presets
   --set-preset <name>  Set the active preset
   preset current       Show the current active preset
+  --debug <value>      Set debug mode (true, false, or status)
   --version, -v        Show the current version
   help                 Show this help
 
@@ -1185,6 +1195,8 @@ Examples:
   claude-hooks presets              # List available presets
   claude-hooks --set-preset backend # Set backend preset
   claude-hooks preset current       # Show current preset
+  claude-hooks --debug true         # Enable debug mode
+  claude-hooks --debug status       # Check debug status
 
 Commit use cases:
   git commit -m "message"           # Manual message + blocking analysis
@@ -1236,6 +1248,12 @@ Parallel Analysis (v2.2.0+):
   - batchSize: 4+ → Fewer API calls but slower
   - Speed improvement: up to 4x faster with batchSize: 1
 
+Debug Mode:
+  Enable detailed logging for troubleshooting:
+  - CLI: claude-hooks --debug true
+  - Config: "system": { "debug": true } in .claude/config.json
+  - Check status: claude-hooks --debug status
+
 Customization:
   Override prompts by copying to .claude/:
     cp templates/COMMIT_MESSAGE.md .claude/
@@ -1247,6 +1265,68 @@ More information: https://github.com/pablorovito/claude-git-hooks
 `);
 }
 
+// Configuration Management Functions
+
+/**
+ * Updates a configuration value in .claude/config.json
+ * Why: Centralized config update logic for all CLI commands
+ *
+ * @param {string} propertyPath - Dot notation path (e.g., 'preset', 'system.debug')
+ * @param {any} value - Value to set
+ * @param {Object} options - Optional settings
+ * @param {Function} options.validator - Custom validation function, receives value, throws on invalid
+ * @param {Function} options.successMessage - Function that receives value and returns success message
+ */
+async function updateConfig(propertyPath, value, options = {}) {
+  const { validator, successMessage } = options;
+
+  try {
+    // Validate value if validator provided
+    if (validator) {
+      await validator(value);
+    }
+
+    // Get repo root
+    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    const configDir = path.join(repoRoot, '.claude');
+    const configPath = path.join(configDir, 'config.json');
+
+    // Ensure .claude directory exists
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+
+    // Load existing config or create new
+    let config = {};
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+
+    // Set value at propertyPath (support dot notation like 'system.debug')
+    const pathParts = propertyPath.split('.');
+    let current = config;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      const part = pathParts[i];
+      if (!current[part] || typeof current[part] !== 'object') {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+    current[pathParts[pathParts.length - 1]] = value;
+
+    // Save config
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+    // Show success message
+    const message = successMessage ? await successMessage(value) : 'Configuration updated';
+    success(message);
+    info(`Configuration saved to ${configPath}`);
+  } catch (err) {
+    error(`Failed to update configuration: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 // Preset Management Functions
 
 /**
@@ -1282,6 +1362,7 @@ async function showPresets() {
 
 /**
  * Sets the active preset
+ * Why: Configures tech-stack specific analysis settings
  */
 async function setPreset(presetName) {
   if (!presetName) {
@@ -1289,45 +1370,24 @@ async function setPreset(presetName) {
     return;
   }
 
-  try {
-    // Verify preset exists
-    const presets = await listPresets();
-    const preset = presets.find(p => p.name === presetName);
-
-    if (!preset) {
-      error(`Preset "${presetName}" not found`);
-      info('Available presets:');
-      presets.forEach(p => console.log(`  - ${p.name}`));
-      process.exit(1);
-    }
-
-    // Update .claude/config.json
-    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
-    const configDir = path.join(repoRoot, '.claude');
-    const configPath = path.join(configDir, 'config.json');
-
-    // Ensure .claude directory exists
-    if (!fs.existsSync(configDir)) {
-      fs.mkdirSync(configDir, { recursive: true });
-    }
-
-    // Load existing config or create new
-    let config = {};
-    if (fs.existsSync(configPath)) {
-      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  await updateConfig('preset', presetName, {
+    validator: async (name) => {
+      const presets = await listPresets();
+      const preset = presets.find(p => p.name === name);
+      if (!preset) {
+        error(`Preset "${name}" not found`);
+        info('Available presets:');
+        presets.forEach(p => console.log(`  - ${p.name}`));
+        throw new Error(`Invalid preset: ${name}`);
+      }
+      return preset;
+    },
+    successMessage: async (name) => {
+      const presets = await listPresets();
+      const preset = presets.find(p => p.name === name);
+      return `Preset '${preset.displayName}' activated`;
     }
-
-    // Set preset
-    config.preset = presetName;
-
-    // Save config
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-
-    success(`Preset '${preset.displayName}' activated`);
-    info(`Configuration saved to ${configPath}`);
-  } catch (err) {
-    error(`Failed to set preset: ${err.message}`);
-  }
+  });
 }
 
 /**
@@ -1354,6 +1414,45 @@ async function currentPreset() {
   }
 }
 
+/**
+ * Sets debug mode
+ * Why: Enables detailed logging for troubleshooting
+ */
+async function setDebug(value) {
+  if (!value) {
+    error('Please specify a value: claude-hooks --debug <true|false|status>');
+    return;
+  }
+
+  const normalizedValue = value.toLowerCase();
+
+  // Handle status check
+  if (normalizedValue === 'status') {
+    try {
+      const config = await getConfig();
+      const isEnabled = config.system.debug || false;
+      console.log('');
+      info(`Debug mode: ${isEnabled ? colors.green + 'enabled' + colors.reset : colors.red + 'disabled' + colors.reset}`);
+      console.log('');
+    } catch (err) {
+      error(`Failed to check debug status: ${err.message}`);
+    }
+    return;
+  }
+
+  // Validate and convert to boolean
+  if (normalizedValue !== 'true' && normalizedValue !== 'false') {
+    error('Invalid value. Use: true, false, or status');
+    return;
+  }
+
+  const debugValue = normalizedValue === 'true';
+
+  await updateConfig('system.debug', debugValue, {
+    successMessage: (val) => `Debug mode ${val ? 'enabled' : 'disabled'}`
+  });
+}
+
 // Main
 async function main() {
   const args = process.argv.slice(2);
@@ -1395,6 +1494,9 @@ async function main() {
         error(`Unknown preset subcommand: ${args[1]}`);
       }
       break;
+    case '--debug':
+      await setDebug(args[1]);
+      break;
     case '--version':
     case '-v':
     case 'version':

package/lib/config.js

@@ -26,9 +26,9 @@ const __dirname = path.dirname(__filename);
 const defaults = {
     // Analysis configuration
     analysis: {
-        maxFileSize: 100000,              // 100KB - max file size to analyze
-        maxFiles: 10,                      // Max number of files per commit
-        timeout: 120000,                   // 2 minutes - Claude analysis timeout
+        maxFileSize: 1000000,              // 1MB - max file size to analyze
+        maxFiles: 20,                      // Max number of files per commit
+        timeout: 300000,                   // 3 minutes - Claude analysis timeout
         contextLines: 3,                   // Git diff context lines
         ignoreExtensions: [],              // Extensions to exclude (e.g., ['.min.js', '.lock'])
         // NOTE: allowedExtensions comes from preset/template, not here
@@ -37,14 +37,14 @@ const defaults = {
     // Commit message generation
     commitMessage: {
         autoKeyword: 'auto',               // Keyword to trigger auto-generation
-        timeout: 180000,                   
+        timeout: 300000,
     },
 
     // Subagent configuration (parallel analysis)
     subagents: {
-        enabled: true,                     // Enable parallel file analysis
+        enabled: false,                    // Enable parallel file analysis
         model: 'haiku',                    // haiku (fast), sonnet (balanced), opus (thorough)
-        batchSize: 3,                      // Parallel subagents per batch
+        batchSize: 1,                      // Parallel subagents per batch
     },
 
     // Template paths

package/lib/hooks/pre-commit.js

@@ -181,12 +181,38 @@ const main = async () => {
         // Load configuration
         const config = await getConfig();
 
+        // Enable debug mode from config
+        if (config.system.debug) {
+            logger.setDebugMode(true);
+        }
+
         // Display configuration info
         const version = await getVersion();
         console.log(`\n🤖 claude-git-hooks v${version}`);
 
         logger.info('Starting code quality analysis...');
 
+        // DEBUG: Log working directories
+        const repoRoot = await import('../utils/git-operations.js').then(m => m.getRepoRoot());
+        const { getRepoRoot } = await import('../utils/git-operations.js');
+
+        // Normalize paths for comparison (handle Windows backslash vs forward slash)
+        const normalizePath = (p) => p.replace(/\\/g, '/').toLowerCase();
+        const cwdNormalized = normalizePath(process.cwd());
+        const repoRootNormalized = normalizePath(repoRoot);
+
+        logger.debug(
+            'pre-commit - main',
+            'Working directory info',
+            {
+                'process.cwd()': process.cwd(),
+                'repo root': repoRoot,
+                'cwd (normalized)': cwdNormalized,
+                'repo root (normalized)': repoRootNormalized,
+                'match': cwdNormalized === repoRootNormalized
+            }
+        );
+
         logger.debug(
             'pre-commit - main',
             'Configuration',
@@ -237,6 +263,14 @@ const main = async () => {
         });
 
         const validFiles = filteredFiles.filter(f => f.valid);
+        const invalidFiles = filteredFiles.filter(f => !f.valid);
+
+        // Show user-facing warnings for rejected files
+        if (invalidFiles.length > 0) {
+            invalidFiles.forEach(file => {
+                logger.warning(`Skipping ${file.path}: ${file.reason}`);
+            });
+        }
 
         if (validFiles.length === 0) {
             logger.warning('No valid files found to review');

package/lib/hooks/prepare-commit-msg.js

@@ -120,6 +120,11 @@ const main = async () => {
     // Load configuration (includes preset + user overrides)
     const config = await getConfig();
 
+    // Enable debug mode from config
+    if (config.system.debug) {
+        logger.setDebugMode(true);
+    }
+
     try {
         // Get hook arguments
         const args = process.argv.slice(2);