Hooks Configuration

You are a Claude Code automation engineer. The user wants to configure Claude Code hooks for automated pre/post actions on file operations, code generation, and skill execution.

What to check first

• Run claude-code config list to see current hook configuration
• Check if .claude-code/hooks.json exists in your project root
• Verify Node.js runtime is available (node --version)

Steps

1. Create .claude-code/hooks.json in your project root with the hook registry structure
2. Define pre-hooks that run before file writes using the beforeWrite event type
3. Define post-hooks that run after code generation using the afterGenerate event type
4. Specify the hook handler path (relative to project root) for each hook entry
5. Add hook metadata including name, description, priority (0-100, higher runs first), and async flag
6. Create handler modules that export a default function accepting context object with file path, content, and operation type
7. Register hooks using claude-code hook register <hook-name> <handler-path> command
8. Test hooks with a trial file write to verify execution order and error handling

Code

{
  "version": "1.0",
  "hooks": [
    {
      "id": "lint-before-write",
      "event": "beforeWrite",
      "name": "Lint Before Write",
      "description": "Run ESLint on generated code before writing to disk",
      "handler": ".claude-code/hooks/lint-handler.js",
      "priority": 90,
      "async": true,
      "config": {
        "ruleset": ".eslintrc.json",
        "fix": true
      },
      "enabled": true
    },
    {
      "id": "format-after-generate",
      "event": "afterGenerate",
      "name": "Format After Generate",
      "description": "Auto-format generated code with Prettier",
      "handler": ".claude-code/hooks/format-handler.js",
      "priority": 85,
      "async": true,
      "config": {
        "parser": "babel",
        "semi": true,
        "singleQuote": false
      },
      "enabled": true
    },
    {
      "id": "git-track-changes",
      "event": "afterWrite",
      "name": "Git Track Changes",
      "description": "Stage modified files to git automatically",
      "handler": ".claude-code/hooks/git-handler.js",
      "priority": 50,
      "async": false,
      "enabled": true
    }
  ]
}

// .claude-code/hooks/lint-handler.js
const { execSync } = require('child_process');
const path = require('path');

module.exports = async function lintHandler(context) {
  const { filePath, content, config } =

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change