claude-git-hooks 2.16.0 → 2.17.1

package/CHANGELOG.md

@@ -5,9 +5,37 @@ 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.17.1] - 2026-03-02
+
+### 🐛 Fixed
+
+- Installer no longer crashes with `ENOTDIR` when running inside a Git worktree where `.git` is a file pointer instead of a directory
+- Hook management commands (`enable`, `disable`, `status`, `uninstall`) now correctly resolve the hooks path in worktree repos
+
+### 🔧 Changed
+
+- Extracted `getGitHooksPath()` to `helpers.js` — uses `git rev-parse --git-common-dir` to find the shared hooks directory in both regular repos and worktrees
+
+## [2.17.0] - 2026-02-16
+
+### ✨ Added
+
+- Automatic GitHub token setup now runs after installation
+
+### 🔧 Changed
+
+- Simplified CLI help output to show concise command reference instead of verbose documentation
+- Commands in help output are now listed in alphabetical order for easier navigation
+- Installation success message now shows single help reference instead of detailed usage examples
+
+### 🗑️ Removed
+
+- Removed extensive inline documentation from help output (use README for detailed docs)
+
 ## [2.16.0] - 2026-02-15
 
 ### ✨ Added
+
 - Multi-file version discovery with recursive scanning up to 3 levels deep
 - Per-file version editing with `--interactive` flag for advanced control
 - Support for additional project types: build.gradle, build.gradle.kts, pyproject.toml, Cargo.toml, version.sbt
@@ -18,22 +46,25 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - New UI components: `promptToggleList()` and `promptEditField()` in interactive-ui.js
 
 ### 🔧 Changed
+
 - Refactored version-manager.js to use new discovery-based API with `discoverVersionFiles()`, `updateVersionFiles()`, and `modifySuffix()`
 - Bump-version workflow now supports selecting specific files to update
 - Each file can have an independent target version when using per-file editing mode
 - Updated CLAUDE.md documentation with new version bump flow and API changes
 
 ### ⚠️ Deprecated
-- Legacy version-manager functions `detectProjectType()`, `getCurrentVersion()`, `updateVersion()`, and `getDiscoveredPaths()` replaced by new discovery API
 
+- Legacy version-manager functions `detectProjectType()`, `getCurrentVersion()`, `updateVersion()`, and `getDiscoveredPaths()` replaced by new discovery API
 
 ## [2.15.5] - 2026-02-12
 
 ### ✨ Added
+
 - Added comprehensive CI-safe integration test suite that runs without Claude CLI dependency
 - Added new test scripts: `test:integration:ci` for CI environments and `test:changed` for testing only modified files
 
 ### 🔧 Changed
+
 - Optimized CI matrix to run full OS/Node.js combinations only on push events, reducing PR build times
 - Refactored integration tests to verify installation workflow, hook lifecycle, config persistence, and CLI routing
 - Improved timeout handling in Claude CLI client by clearing timeouts consistently on all exit paths
@@ -41,35 +72,37 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - Reduced Jest verbosity and coverage reporters for cleaner CI output
 
 ### 🐛 Fixed
+
 - Fixed potential timeout leak in claude-client.js where timeouts were not cleared on error or stdin failures
 
 ### 🗑️ Removed
-- Removed unused variables and parameters across multiple modules (analyze-diff, create-pr, install, config, changelog-generator, claude-client, claude-diagnostics, file-utils, git-operations, prompt-builder)
 
+- Removed unused variables and parameters across multiple modules (analyze-diff, create-pr, install, config, changelog-generator, claude-client, claude-diagnostics, file-utils, git-operations, prompt-builder)
 
 ## [2.15.4] - 2026-02-11
 
 ### ✨ Added
+
 - Added comprehensive unit tests for claude-diagnostics.js covering error detection, formatting, and recovery classification
 - Added unit tests for file-utils.js covering directory creation and file writing operations
 
-
 ## [2.15.3] - 2026-02-10
 
 ### ✨ Added
+
 - Unit tests for `generate-changelog.js` command covering CHANGELOG generation, version detection, and error handling
 - Unit tests for `github-client.js` covering CODEOWNERS parsing, reviewer detection, and GitHub repo parsing
 - Unit tests for `hooks.js` command covering enable, disable, status, and uninstall operations
 
-
 ## [2.15.2] - 2026-02-10
 
 ### 🔧 Changed
+
 - The bump-version command now uses the configured default branch (from github.pr.defaultBase) in the 'Next steps' output instead of hardcoded 'main'
 
 ### 🐛 Fixed
-- Fixed cross-platform path assertions in unit tests to use partial matching instead of exact paths, improving Windows compatibility
 
+- Fixed cross-platform path assertions in unit tests to use partial matching instead of exact paths, improving Windows compatibility
 
 ## [2.15.1] - 2026-02-10
 

package/README.md

@@ -243,8 +243,11 @@ claude-hooks --help   # Full command reference
 | `helpers.js` | **Shared CLI utilities** - colors, output, platform detection | `colors`, `error()`, `success()`, `info()`, `checkGitRepo()`, `Entertainment` |
 | `install.js` | **Installation logic** - dependencies, hooks, templates | `runInstall()`, `extractLegacySettings()` |
 | `hooks.js` | **Hook management** - enable, disable, status, uninstall | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()` |
+| `analyze.js` | **Interactive code analysis** - analyze before committing | `runAnalyze()` |
 | `analyze-diff.js` | **Diff analysis** - generate PR metadata from git diff | `runAnalyzeDiff()` |
 | `create-pr.js` | **PR creation** - full workflow via Octokit | `runCreatePr()` |
+| `bump-version.js` | **Version management** - bump with CHANGELOG and Git tag | `runBumpVersion()` |
+| `generate-changelog.js` | **CHANGELOG generation** - standalone command | `runGenerateChangelog()` |
 | `setup-github.js` | **Token setup** - interactive GitHub configuration | `runSetupGitHub()` |
 | `presets.js` | **Preset management** - list, set, show current | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()` |
 | `update.js` | **Self-update** - check and install latest version | `runUpdate()` |

package/lib/commands/help.js

@@ -24,176 +24,40 @@ Claude Git Hooks - Code analysis and automatic messages with Claude CLI
 Usage: claude-hooks <command> [options]
 
 Commands:
-  install [options]    Install hooks in the current repository
-    --force           Reinstall even if they already exist
-    --skip-auth       Skip Claude authentication verification
-  update               Update to the latest available version
-  uninstall            Uninstall hooks from the repository
-  enable [hook]        Enable hooks (all or one specific)
-  disable [hook]       Disable hooks (all or one specific)
-  status               Show the status of hooks
-  analyze-diff [base]  Analyze differences between branches and generate PR info
-  create-pr [base]     Create pull request with auto-generated metadata and reviewers
-  bump-version <type>  Bump version with automatic CHANGELOG and Git tag
-    major             Bump major version (1.0.0 → 2.0.0)
-    minor             Bump minor version (1.0.0 → 1.1.0)
-    patch             Bump patch version (1.0.0 → 1.0.1)
-    --suffix <value>  Add version suffix (e.g., SNAPSHOT, RC)
-    --update-changelog [branch]  Generate CHANGELOG entry (default: main)
-    --dry-run         Preview changes without applying
-    --no-tag          Skip Git tag creation
-    --no-push         Create tag but don't push to remote
-  generate-changelog [version]  Generate CHANGELOG entry independently
-    --base-branch <branch>  Compare against branch (default: main)
-    --release         Mark as released (no [Unreleased] header)
-  setup-github         Setup GitHub login (required for create-pr)
-  presets              List all available presets
-  --set-preset <name>  Set the active preset
-  preset current       Show the current active preset
-  telemetry [action]   Telemetry management (show or clear)
-  --debug <value>      Set debug mode (true, false, or status)
-  --version, -v        Show the current version
-  help                 Show this help
-
-Available hooks:
-  pre-commit           Code analysis before commit
-  prepare-commit-msg   Automatic message generation
-
-Examples:
-  claude-hooks install              # Install all hooks
-  claude-hooks install --skip-auth  # Install without verifying authentication
-  claude-hooks update               # Update to the latest version
-  claude-hooks disable pre-commit   # Disable only pre-commit
-  claude-hooks enable               # Enable all hooks
-  claude-hooks status               # View current status
-  claude-hooks analyze-diff main    # Analyze differences with main
-  claude-hooks setup-github         # Configure GitHub token for PR creation
-  claude-hooks create-pr develop    # Create PR targeting develop branch
-  claude-hooks bump-version minor   # Bump minor version with tag
-  claude-hooks bump-version patch --suffix SNAPSHOT  # Add SNAPSHOT version
-  claude-hooks bump-version major --update-changelog # Bump and update CHANGELOG
-  claude-hooks generate-changelog   # Generate CHANGELOG for current version
-  claude-hooks generate-changelog 2.7.0 --release  # Generate for specific release
-  claude-hooks presets              # List available presets
-  claude-hooks --set-preset backend # Set backend preset
-  claude-hooks preset current       # Show current preset
-  claude-hooks telemetry show       # Show telemetry statistics
-  claude-hooks telemetry clear      # Clear telemetry data
-  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
-  git commit -m "auto"              # Automatic message + blocking analysis
-  git commit --no-verify -m "auto"  # Automatic message without analysis
-  git commit --no-verify -m "msg"   # Manual message without analysis
-
-Analyze-diff use case:
-  claude-hooks analyze-diff main    # Analyze changes vs main and generate:
-    → PR Title: "feat: add user authentication module"
-    → PR Description: "## Summary\n- Added JWT authentication..."
-    → Suggested branch: "feature/user-authentication"
-
-Create-pr use case (v2.5.0+):
-  claude-hooks create-pr develop    # Create PR targeting develop:
-    → Validates GitHub token
-    → Extracts task-id from branch (IX-123, #456, LIN-123)
-    → Checks version alignment (package.json, pom.xml, CHANGELOG, tags)
-    → Detects and prompts to push unpushed tags
-    → Analyzes diff and generates PR metadata with Claude
-    → Creates PR directly via GitHub API (Octokit)
-    → Adds labels based on preset
-    → Returns PR URL
-
-  Token configuration:
-    → .claude/settings.local.json (recommended, gitignored)
-    → GITHUB_TOKEN environment variable
-    → Claude Desktop config (auto-detected)
-
-Bump-version use case (v2.12.0+):
-  claude-hooks bump-version patch --update-changelog
-    → Validates prerequisites (clean working dir, valid branch, remote)
-    → Detects project type (Node.js, Maven, or both)
-    → Increments version (major/minor/patch)
-    → Updates package.json and/or pom.xml
-    → Generates CHANGELOG entry with Claude (if --update-changelog)
-    → Creates annotated Git tag (v2.7.0)
-    → Pushes tag to remote
-
-  Version workflow examples:
-    2.7.0 → 2.8.0-SNAPSHOT  # Start development
-    2.8.0-SNAPSHOT → 2.8.0-RC  # Release candidate
-    2.8.0-RC → 2.8.0  # Final release
-
-  Integration with create-pr:
-    → Automatically detects version misalignment
-    → Prompts to push unpushed tags before PR creation
-    → Warns if local version <= remote version
-
-Generate-changelog use case (v2.12.0+):
-  claude-hooks generate-changelog [version]
-    → Standalone CHANGELOG generation (no version bump)
-    → Auto-detects version from package.json or pom.xml
-    → Analyzes commits since last tag using Claude
-    → Updates CHANGELOG.md with categorized entries
-    → Useful when bump-version CHANGELOG step fails
-    → Can mark as released or unreleased
-
-  Examples:
-    claude-hooks generate-changelog  # Use current version
-    claude-hooks generate-changelog 2.7.0 --release  # Specific release
-    claude-hooks generate-changelog --base-branch develop  # Compare vs develop
-
-Presets (v2.3.0+):
-  Built-in tech-stack specific configurations:
-  - backend: Spring Boot + SQL Server (.java, .xml, .yml)
-  - frontend: React + Material-UI (.js, .jsx, .ts, .tsx, .css)
-  - fullstack: Backend + Frontend with API consistency checks
-  - database: SQL Server migrations and procedures (.sql)
-  - ai: Node.js + Claude CLI integration (.js, .json, .md)
-  - default: General-purpose mixed languages
-
-Configuration (v2.2.0+):
-  Create .claude/config.json in your project to customize:
-  - Preset selection
-  - Analysis settings (maxFileSize, maxFiles, timeout)
-  - Commit message generation (autoKeyword, timeout)
-  - Parallel execution (enabled, model, batchSize)
-  - Template paths and output files
-  - Debug mode
-
-  Example: .claude/config.json
-  {
-    "preset": "backend",
-    "analysis": { "maxFiles": 30, "timeout": 180000 },
-    "subagents": {
-      "enabled": true,      // Enable parallel execution
-      "model": "haiku",     // haiku (fast) | sonnet | opus
-      "batchSize": 2        // Files per batch (1=fastest)
-    },
-    "system": { "debug": true }
-  }
-
-Parallel Analysis (v2.2.0+):
-  When analyzing 3+ files, parallel execution runs multiple Claude CLI
-  processes simultaneously for faster analysis:
-  - batchSize: 1 → Maximum speed (1 file per process)
-  - batchSize: 2 → Balanced (2 files per process)
-  - 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/
-    cp templates/ANALYZE_DIFF.md .claude/
-    cp templates/CLAUDE_PRE_COMMIT.md .claude/
-    # Edit as needed - system uses .claude/ version if exists
+  analyze [--unstaged | --all]           Analyze code interactively before committing
+  analyze-diff [base]                    Analyze diff and generate PR metadata
+  bump-version [type] [options]          Bump version with CHANGELOG and Git tag
+    <type>: major | minor | patch        (optional for suffix-only operations)
+    --dry-run                            Preview changes without applying
+    --interactive                        Force file selection menu
+    --no-commit                          Skip automatic commit
+    --no-tag                             Skip Git tag creation
+    --push                               Push tag to remote
+    --remove-suffix                      Remove version suffix (no type required)
+    --set-suffix <value>                 Set/replace version suffix (no type required)
+    --suffix <value>                     Add version suffix (e.g., SNAPSHOT)
+    --update-changelog [branch]          Generate CHANGELOG entry
+  create-pr [base]                       Create PR with auto-generated metadata
+  --debug <true | false | status>        Toggle debug mode
+  disable [hook]                         Disable hooks (all or specific)
+  enable [hook]                          Enable hooks (all or specific)
+  generate-changelog [version]           Generate CHANGELOG entry independently
+    --base-branch <branch>               Compare against branch (default: main)
+    --release                            Mark as released
+  help, --help, -h                       Show this help
+  install [options]                       Install hooks in current repository
+    --force                              Reinstall even if already exist
+    --skip-auth                          Skip Claude authentication check
+  migrate-config                         Migrate legacy config to v2.8.0 format
+  preset current                         Show current active preset
+  presets                                List all available presets
+  --set-preset <name>                    Set the active preset
+  setup-github                           Configure GitHub token for PR creation
+  status                                 Show hook status
+  telemetry [show | clear]               View or clear telemetry data
+  uninstall                              Remove hooks from repository
+  update                                 Update to latest version
+  --version, -v                          Show current version
 
 More information: https://github.com/pablorovito/claude-git-hooks
 `);

package/lib/commands/helpers.js

@@ -95,6 +95,26 @@ export function getTemplatesPath() {
     return path.join(__dirname, '..', '..', 'templates');
 }
 
+/**
+ * Get the git hooks directory, correctly handling worktrees.
+ * In a worktree, hooks live in the main repo's .git/hooks, not the worktree's .git file.
+ * Uses `git rev-parse --git-common-dir` to find the shared git directory.
+ * @returns {string} Path to the git hooks directory
+ */
+export function getGitHooksPath() {
+    try {
+        let gitCommonDir = execSync('git rev-parse --git-common-dir', { encoding: 'utf8' }).trim();
+        // Handle Windows paths when running under WSL (e.g. C:\... -> /mnt/c/...)
+        if (/^[A-Za-z]:/.test(gitCommonDir)) {
+            gitCommonDir = gitCommonDir.replace(/^([A-Za-z]):/, (_, drive) => `/mnt/${drive.toLowerCase()}`);
+            gitCommonDir = gitCommonDir.replace(/\\/g, '/');
+        }
+        return path.join(gitCommonDir, 'hooks');
+    } catch (e) {
+        return path.join('.git', 'hooks');
+    }
+}
+
 /**
  * Detect if running on Windows
  * Why: Need to use 'wsl claude' instead of 'claude' on Windows

package/lib/commands/hooks.js

@@ -10,7 +10,8 @@ import {
     success,
     info,
     warning,
-    checkGitRepo
+    checkGitRepo,
+    getGitHooksPath
 } from './helpers.js';
 
 /**
@@ -22,11 +23,12 @@ export function runEnable(hookName) {
         error('You are not in a Git repository.');
     }
 
+    const hooksDir = getGitHooksPath();
     const hooks = hookName ? [hookName] : ['pre-commit', 'prepare-commit-msg'];
 
     hooks.forEach(hook => {
-        const disabledPath = `.git/hooks/${hook}.disabled`;
-        const enabledPath = `.git/hooks/${hook}`;
+        const disabledPath = path.join(hooksDir, `${hook}.disabled`);
+        const enabledPath = path.join(hooksDir, hook);
 
         if (fs.existsSync(disabledPath)) {
             fs.renameSync(disabledPath, enabledPath);
@@ -48,11 +50,12 @@ export function runDisable(hookName) {
         error('You are not in a Git repository.');
     }
 
+    const hooksDir = getGitHooksPath();
     const hooks = hookName ? [hookName] : ['pre-commit', 'prepare-commit-msg'];
 
     hooks.forEach(hook => {
-        const enabledPath = `.git/hooks/${hook}`;
-        const disabledPath = `.git/hooks/${hook}.disabled`;
+        const enabledPath = path.join(hooksDir, hook);
+        const disabledPath = path.join(hooksDir, `${hook}.disabled`);
 
         if (fs.existsSync(enabledPath)) {
             fs.renameSync(enabledPath, disabledPath);
@@ -75,10 +78,11 @@ export function runStatus() {
 
     info('Claude Git Hooks status:\n');
 
+    const hooksDir = getGitHooksPath();
     const hooks = ['pre-commit', 'prepare-commit-msg'];
     hooks.forEach(hook => {
-        const enabledPath = `.git/hooks/${hook}`;
-        const disabledPath = `.git/hooks/${hook}.disabled`;
+        const enabledPath = path.join(hooksDir, hook);
+        const disabledPath = path.join(hooksDir, `${hook}.disabled`);
 
         if (fs.existsSync(enabledPath)) {
             success(`${hook}: enabled`);
@@ -135,7 +139,7 @@ export function runUninstall() {
 
     info('Uninstalling Claude Git Hooks...');
 
-    const hooksPath = '.git/hooks';
+    const hooksPath = getGitHooksPath();
     const hooks = ['pre-commit', 'prepare-commit-msg'];
 
     hooks.forEach(hook => {

package/lib/commands/install.js

@@ -23,12 +23,14 @@ import {
     warning,
     checkGitRepo,
     getTemplatesPath,
+    getGitHooksPath,
     isWindows,
     getClaudeCommand,
     getPackageJson,
     getLatestVersion,
     Entertainment
 } from './helpers.js';
+import { runSetupGitHub } from './setup-github.js';
 
 /**
  * Function to check version (used by hooks)
@@ -401,7 +403,7 @@ export async function runInstall(args) {
     await checkAndInstallDependencies(skipAuth);
 
     const templatesPath = getTemplatesPath();
-    const hooksPath = '.git/hooks';
+    const hooksPath = getGitHooksPath();
 
     // Create hooks directory if it doesn't exist
     if (!fs.existsSync(hooksPath)) {
@@ -654,34 +656,9 @@ export async function runInstall(args) {
     updateGitignore();
 
     success('Claude Git Hooks installed successfully! 🎉');
-    console.log('\nUsage:');
-    console.log('  git commit -m "auto"     # Generate message automatically');
-    console.log('  git commit -m "message"  # Analyze code before commit');
-    console.log('  git commit --no-verify   # Skip analysis completely');
-    console.log('\n💡 Configuration (v2.8.0):');
-    console.log('  📁 All templates installed in .claude/');
-    console.log('  📝 Edit .claude/config.json (minimal by default)');
-    console.log('  📂 Examples: .claude/config_example/');
-    console.log('  📦 Backups: .claude/config_old/');
-    console.log('  🎯 Presets: backend, frontend, fullstack, database, ai, default');
-    console.log('  🚀 Parallel analysis enabled by default (hardcoded)');
-    console.log('  🐛 Debug mode: claude-hooks --debug true');
-    console.log('\n🔗 GitHub PR Creation (v2.5.0+):');
-    console.log('  claude-hooks setup-github    # Configure GitHub token');
-    console.log('  claude-hooks create-pr main  # Create PR with auto-metadata');
-    console.log('\n📖 Minimal config.json (v2.8.0):');
-    console.log('  {');
-    console.log('    "version": "2.8.0",');
-    console.log('    "preset": "backend"');
-    console.log('  }');
-    console.log('\n📖 With GitHub customization:');
-    console.log('  {');
-    console.log('    "version": "2.8.0",');
-    console.log('    "preset": "backend",');
-    console.log('    "overrides": {');
-    console.log('      "github": { "pr": { "reviewers": ["your-username"] } }');
-    console.log('    }');
-    console.log('  }');
-    console.log('\n🔧 Advanced: see .claude/config_example/config.advanced.example.json');
-    console.log('\nFor more options: claude-hooks --help');
+    console.log('\nRun claude-hooks --help to see all available commands.');
+
+    // Run GitHub token setup
+    console.log('');
+    await runSetupGitHub();
 }

package/lib/utils/installation-diagnostics.js

@@ -22,6 +22,7 @@
 import fs from 'fs';
 import path from 'path';
 import { getRepoRoot } from './git-operations.js';
+import { getGitHooksPath } from '../commands/helpers.js';
 
 /**
  * Gets installation diagnostics
@@ -60,7 +61,7 @@ export const getInstallationDiagnostics = () => {
         diagnostics.presetsDirPath = path.join(diagnostics.claudeDirPath, 'presets');
         diagnostics.presetsDirExists = fs.existsSync(diagnostics.presetsDirPath);
 
-        const gitHooksPath = path.join(diagnostics.repoRoot, '.git', 'hooks');
+        const gitHooksPath = getGitHooksPath();
         diagnostics.gitHooksExists = fs.existsSync(gitHooksPath);
     } catch (error) {
         // Not in a git repository - diagnostics.repoRoot will be null

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.16.0",
+    "version": "2.17.1",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {