# Claude Code Hooks

This directory contains hooks that integrate with Claude Code to provide real-time code quality validation.

## Available Hooks

### typescript-check.sh

Validates TypeScript files when they are created or modified through Claude Code's Write or Edit tools.

**What it checks:**

- ✅ TypeScript type errors (`tsc --noEmit`)
- ✅ Biome lint/format errors (`biome check`)

**When it runs:**

- After Write tool creates a `.ts` or `.tsx` file
- After Edit tool modifies a `.ts` or `.tsx` file

**Behavior:**

- ✅ **Passes**: Allows the operation to complete
- ❌ **Fails**: Blocks the operation and shows detailed errors with suggestions

## Hook Configuration

The `hooks.json` file registers hooks with Claude Code:

```json
{
  "description": "TypeScript and code quality validation hook for Write/Edit operations on .ts/.tsx files",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/typescript-check.sh"
          }
        ]
      }
    ]
  }
}
```

## How It Works

1. **User requests file creation/edit**: Claude Code invokes Write or Edit tool
2. **Tool completes**: File is written/edited to disk
3. **Hook triggers**: `typescript-check.sh` executes
4. **Validation runs**:
   - Checks if file is `.ts` or `.tsx`
   - Runs `tsc --noEmit` for type checking
   - Runs `biome check` for linting
5. **Result**:
   - **All pass**: Operation succeeds, user sees success message
   - **Errors found**: Operation is blocked, user sees detailed error report

## Example Output

### ✅ Success

```
TypeScript Check:
✅ No type errors found

Biome Check:
✅ No lint errors found

✅ Code quality checks passed!
```

### ❌ Failure

```
❌ Code quality checks failed for src/utils/helper.ts:

❌ TypeScript errors found:
src/utils/helper.ts:15:3 - Type 'string' is not assignable to type 'number'
src/utils/helper.ts:23:7 - Property 'email' does not exist on type 'User'

❌ Biome lint/format errors found:
src/utils/helper.ts:15:3 - Unused variable 'response'
src/utils/helper.ts:42:1 - Missing return type

💡 Run these commands to fix:
  bun run format
  bun run lint:fix
  bun run type-check
```

## Installation

The hooks are **automatically registered** when the plugin is loaded by Claude Code. No manual installation needed.

## Configuration

### Disable Hook Temporarily

If you need to bypass the hook temporarily:

```bash
# Set environment variable
export SKIP_TYPESCRIPT_CHECK=1

# Or disable in Claude Code settings
```

### Customize Hook Behavior

Edit `typescript-check.sh` to adjust:

- Which tools to run (tsc, biome)
- Error message formatting
- Suggested fix commands

## Troubleshooting

### Hook Not Running

**Check:**

1. Plugin is properly loaded
2. `typescript-check.sh` is executable: `chmod +x hooks/typescript-check.sh`
3. `hooks.json` is valid JSON
4. Hook log file: `~/.claude/hooks/typescript-check.log`

### False Positives

If the hook is too strict:

1. **Adjust Biome rules** in project's `biome.json`
2. **Exclude files** in `.gitignore` or Biome config
3. **Disable specific rules** for certain files

### Performance Issues

If hook is too slow:

1. **Run only on changed files** (modify script to check specific file)
2. **Disable type checking for large projects** (comment out `tsc` in script)
3. **Use incremental TypeScript** (add `--incremental` flag)

## Log File

Hook execution is logged to:

```
~/.claude/hooks/typescript-check.log
```

View logs:

```bash
tail -f ~/.claude/hooks/typescript-check.log
```

## Best Practices

1. **Keep hook fast**: Only run essential checks
2. **Provide clear errors**: Show exact line numbers and fixes
3. **Log everything**: Use the log file for debugging
4. **Test thoroughly**: Ensure hook doesn't block valid operations
5. **Document behavior**: Explain what the hook does and why

## Comparison with Pre-commit Hooks

| Feature      | Claude Code Hook     | Git Pre-commit Hook       |
| ------------ | -------------------- | ------------------------- |
| **Trigger**  | On file Write/Edit   | On git commit             |
| **Scope**    | Single file          | Staged files              |
| **Speed**    | Per-file validation  | Batch validation          |
| **Blocking** | Blocks file creation | Blocks commit             |
| **Best for** | Real-time feedback   | Final check before commit |

**Recommendation**: Use **both**:

- Claude Code hooks for immediate feedback during development
- Pre-commit hooks for final validation before committing

## Related

- **Pre-commit hooks**: See `templates/.husky/` for Git pre-commit hooks
- **Quality gates**: See `commands/quality-gates.md` for full workflow
- **TypeScript config**: Adjust `tsconfig.json` for type checking behavior
- **Biome config**: Adjust `biome.json` for linting behavior