@sammons/claude-good-hooks

A comprehensive CLI tool for managing Claude Code hooks. Create, share, and apply powerful automation hooks to enhance your Claude Code development experience.

Installation

Global Installation (Recommended)

npm install -g @sammons/claude-good-hooks

Local Installation

npm install @sammons/claude-good-hooks

Quick Start

# Install the CLI globally
npm install -g @sammons/claude-good-hooks

# Check available commands
claude-good-hooks help

# List available hooks
claude-good-hooks list-hooks

# Apply a hook globally
claude-good-hooks apply dirty --global

# Check system health
claude-good-hooks doctor

Commands

Core Commands

| Command | Description | Example | |---------|-------------|---------| | help [command] | Show help for all commands or a specific command | claude-good-hooks help apply | | list-hooks [options] | List available hooks with filtering options | claude-good-hooks list-hooks --installed | | apply <hook-name> [options] | Apply a hook to global, project, or local scope | claude-good-hooks apply dirty --global | | doctor | Run system diagnostics and health checks | claude-good-hooks doctor | | version | Show version information | claude-good-hooks version |

Hook Management

| Command | Description | Example | |---------|-------------|---------| | update [hook-name] | Update hooks to latest versions | claude-good-hooks update | | init [template] | Initialize hook configuration | claude-good-hooks init basic | | validate [file] | Validate hook configuration | claude-good-hooks validate |

Data Management

| Command | Description | Example | |---------|-------------|---------| | export [options] | Export hook configurations | claude-good-hooks export --output hooks.json | | import <source> | Import hook configurations | claude-good-hooks import hooks.json |

Hook Scopes

Global Hooks

Applied to ~/.claude/settings.json - affects all Claude Code sessions:

claude-good-hooks apply dirty --global

Project Hooks

Applied to ./.claude/settings.json - affects current project:

claude-good-hooks apply lint-check --project

Local Hooks

Applied to ./.claude/settings.local.json - local overrides (not committed):

claude-good-hooks apply debug --local

JSON Output

All commands support JSON output for automation:

claude-good-hooks list-hooks --json
claude-good-hooks doctor --json
claude-good-hooks version --json

Hook Sources

NPM Packages

Install and apply community hooks:

npm install -g @sammons/git-dirty-hook
claude-good-hooks apply dirty --global

Template Hooks

Generate hooks from templates:

claude-good-hooks apply template-hook --template git-status

Configuration

Settings File Locations

• Global: ~/.claude/settings.json
• Project: ./.claude/settings.json
• Local: ./.claude/settings.local.json

Example Hook Configuration

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npm run lint"
      }]
    }]
  }
}

Development

Building from Source

git clone https://github.com/sammons2/claude-good-hooks.git
cd claude-good-hooks/packages/claude-good-hooks
npm install
npm run build
npm link

Running Tests

npm test

Development Mode

npm run dev

Troubleshooting

Common Issues

1. Command not found

   # Ensure global installation
   npm install -g @sammons/claude-good-hooks
   # Or check PATH
   echo $PATH

2. Permission errors

   # Use sudo for global installation (if needed)
   sudo npm install -g @sammons/claude-good-hooks

3. Hook not applying

   # Check hook configuration
   claude-good-hooks validate
   # Run diagnostics
   claude-good-hooks doctor

Debug Mode

Enable verbose logging:

DEBUG=claude-good-hooks* claude-good-hooks <command>

Related Packages

• @sammons/git-dirty-hook - Git status hook implementation
• @sammons/code-outline-hook - Code outline hook for analyzing code structure

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

MIT © Sammons Software LLC

Support

• GitHub Issues
• Documentation