Skip to content

HOOKS.md

Latest commit

 

History

History
118 lines (88 loc) · 3.5 KB

HOOKS.md

File metadata and controls

118 lines (88 loc) · 3.5 KB

Hooks

Quality checks that run automatically as Claude Code works.

How It Works

chunk init generates .claude/settings.json with two hooks:

PreToolUse — matches Bash(git commit*). Runs every configured command before a commit. If any command fails, the commit is blocked.

Stop — runs chunk validate after every session ends. Skips everything when the working tree is clean. When there are changes, it runs all configured commands so problems are surfaced before the agent stops working.

Worktree Support

The Stop hook uses CLAUDE_WORKING_DIR (the actual session working directory) when available, falling back to CLAUDE_PROJECT_DIR. This means it correctly targets the active worktree rather than the main repo root. No special configuration is needed.

Quick Start

# 1. Install chunk (see README)
chunk --version

# 2. Initialize project (detects commands, writes settings.json)
chunk init

# 3. Edit .chunk/config.json to adjust commands if needed

Configuration

.chunk/config.json

Commands are defined in the project config:

{
  "commands": [
    {"name": "format", "run": "task fmt", "timeout": 30},
    {"name": "lint", "run": "task lint", "timeout": 60},
    {"name": "test", "run": "task test", "timeout": 300}
  ],
  "stopHookMaxAttempts": 3
}

stopHookMaxAttempts controls how many times the Stop hook will re-signal the agent when validation keeps failing for the same uncommitted changes. After that many consecutive failures the hook exits 0 (ending the session) instead of non-zero (which would ask Claude to try again). Defaults to 3 if unset.

.claude/settings.json

Generated by chunk init:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {"type": "command", "command": "cd ${CLAUDE_PROJECT_DIR:-.} && task fmt", "timeout": 30},
          {"type": "command", "command": "cd ${CLAUDE_PROJECT_DIR:-.} && chunk validate lint", "timeout": 60},
          {"type": "command", "command": "cd ${CLAUDE_PROJECT_DIR:-.} && chunk validate test", "timeout": 300}
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {"type": "command", "command": "chunk validate", "timeout": 420}
        ]
      }
    ]
  }
}

The Bash(chunk:*) permission is also granted so chunk CLI commands run without prompting.

Supported Environments

IDE Status Notes
Claude Code (CLI / terminal) Fully supported Canonical provider
Cursor Supported Reads .claude/settings.json directly

Disabling Stop-Hook Validation

Temporarily disable the chunk validate Stop hook without modifying .claude/settings.json:

chunk hook disable   # Creates .chunk/hooks-disabled sentinel file
chunk hook enable    # Removes the sentinel file
chunk hook status    # Shows "enabled" or "disabled"

Stop-hook validation is also skipped when the CHUNK_HOOKS_DISABLED environment variable is set to any non-empty value. This does not suppress PreToolUse commit hooks generated by chunk init, because those commands run directly from .claude/settings.json.

The --project flag overrides the project root used to locate the sentinel file.

Manual Validation

Use chunk validate to run checks manually (outside of hooks):

chunk validate           # Run all configured commands
chunk validate test      # Run a specific command
chunk validate --list    # List configured commands
chunk validate --dry-run # Show commands without executing