Thank you for your interest in contributing to claude-hooks! This guide will help you get started.
- Code of Conduct
- Getting Started
- Development Setup
- Making Changes
- Testing
- Submitting Changes
- Coding Standards
- Documentation
This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.
- Fork the repository
- Clone your fork:
git clone https://github.com/YOUR_USERNAME/claude-hooks.git - Add upstream remote:
git remote add upstream https://github.com/anthropics/claude-hooks.git - Create a feature branch:
git checkout -b feature/your-feature-name
- Node.js >= 18.0.0
- npm >= 8.0.0
- Bun runtime (for testing generated hooks)
# Clone the repository
git clone https://github.com/anthropics/claude-hooks.git
cd claude-hooks
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test# Start development (watch mode)
npm run dev
# Run tests during development
npm test -- --watch
# Check code style
npm run lint
# Run type checking
npm run build- Features:
feature/description - Bug fixes:
fix/description - Documentation:
docs/description - Refactoring:
refactor/description
Follow the Conventional Commits specification:
type(scope): subject
body
footer
Types:
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changes (formatting, etc.)refactor: Code refactoringtest: Adding or updating testschore: Maintenance tasks
Examples:
feat(init): add support for Ruby projects
fix(security): prevent false positives in secret detection
docs(readme): update installation instructions
test(init): add tests for force flag behavior# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:smoke
# Run specific test file
npm test test/commands/init.test.ts
# Run tests matching pattern
npm test -- --grep "security patterns"-
Unit Tests: Test individual functions and components
- Location:
test/unit/,test/commands/ - Use mocks for external dependencies
- Focus on edge cases
- Location:
-
Integration Tests: Test complete workflows
- Location:
test/integration/ - Test actual CLI execution
- Verify file system operations
- Location:
-
Smoke Tests: Verify generated output
- Location:
test/smoke/ - Check generated file syntax
- Validate security patterns
- Location:
Example test:
describe('init command', () => {
it('should generate hooks with security patterns', async () => {
const result = await runCommand(['init', '--yes'])
expect(result.stdout).to.include('setup complete')
const indexContent = await fs.readFile('.claude/hooks/index.ts', 'utf8')
expect(indexContent).to.include('DANGEROUS_FILE_OPS')
})
})Maintain test coverage above:
- Branches: 80%
- Lines: 85%
- Functions: 80%
- Statements: 85%
-
Update your branch with latest upstream changes:
git fetch upstream git rebase upstream/main
-
Ensure all tests pass:
npm test npm run lint -
Update documentation if needed
-
Submit pull request with:
- Clear title and description
- Reference to related issues
- Screenshots for UI changes
- Test results
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
- [ ] All tests pass
- [ ] Added new tests
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No console.log statements- Use TypeScript strict mode
- Prefer interfaces over types for objects
- Use explicit return types
- Avoid
anytype
- 2 spaces for indentation
- Single quotes for strings
- No semicolons (prettier handles this)
- Max line length: 100 characters
src/
├── commands/ # CLI command implementations
├── hooks/ # Hook-related utilities
├── templates/ # Template generators
└── utils/ # Shared utilities
- Add JSDoc comments for public APIs
- Include examples in comments
- Document complex algorithms
Example:
/**
* Generates a customized hook file based on user selections
* @param hooks - Selected hook types
* @param security - Security feature configuration
* @returns Generated TypeScript code
* @example
* const code = generateHookFile(
* { preToolUse: true },
* { blockDangerousFileOps: true }
* )
*/
export function generateHookFile(
hooks: HookSelection,
security: SecurityFeatures
): string {
// Implementation
}Update README.md when:
- Adding new features
- Changing CLI options
- Updating requirements
- Open an issue for bugs or feature requests
- Start a discussion for questions
- Contact maintainers for security issues
Thank you for contributing to claude-hooks! 🚀