Hooks Automation

Hooks Automation

Intelligent automation system that coordinates, validates, and learns from Claude Code operations through hooks integrated with MCP tools and neural/routing pattern training.

See references/examples.md for complete configuration templates and Git hook scripts.

What This Skill Does

Key capabilities:

• Pre-operation hooks: risk-assess a command, get agent-routing suggestions before a file edit or task
• Post-operation hooks: record edit/task/command outcomes for learning
• Session management: persist and restore session state
• Memory coordination: read/write shared context via mcp__claude-flow__memory_usage
• Agent routing: route/explain — route a task to the best-fit agent and see why
• Pattern learning: outcomes recorded by hooks feed claude-flow hooks pretrain/metrics

When Not To Use

• One-off swarm orchestration without persistent hooks -- use swarm-advanced instead
• Full development pipelines with quality gates -- use build-with-quality instead
• Single-agent plan/memory/security-scan hooks -- use lazy-fetch instead (see Related Skills for the ownership split)
• GitHub-specific CI/CD workflow authoring -- use a GitHub workflow-automation skill instead
• Standalone performance profiling -- use a performance-analysis skill instead

Prerequisites

Required:

• claude-flow already on PATH as the baked ruflo CLI (Nix store derivation) -- no install needed; do not run npm install -g claude-flow@alpha, it is redundant and may fail in this read-only-Nix-store container
• Claude Code with hooks enabled
• .claude/settings.json with hook configurations

Optional:

• Git repository for version control (for the Git hook scripts in references/examples.md)

Quick Start

# Verify the CLI and see every real subcommand
claude-flow hooks --help

Add hook entries under .claude/settings.json's hooks key (Claude Code's own config, not a claude-flow subcommand):

Basic Hook Usage

claude-flow hooks pre-task -d "Implement authentication"
claude-flow hooks post-edit -f "src/auth.js" --success true
claude-flow hooks session-end

Minimal settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^(Write|Edit|MultiEdit)$",
        "hooks": [{ "type": "command", "command": "claude-flow hooks pre-edit -f '${tool.params.file_path}'" }]
      },
      {
        "matcher": "^Bash$",
        "hooks": [{ "type": "command", "command": "claude-flow hooks pre-command -c '${tool.params.command}'" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "^(Write|Edit|MultiEdit)$",
        "hooks": [{ "type": "command", "command": "claude-flow hooks post-edit -f '${tool.params.file_path}' --success true" }]
      },
      {
        "matcher": "^Bash$",
        "hooks": [{ "type": "command", "command": "claude-flow hooks post-command -c '${tool.params.command}' --success true" }]
      }
    ]
  }
}

Available Hooks (verified against claude-flow hooks --help, 2026-09-09)

Pre-operation hooks (run BEFORE the tool)

claude-flow hooks pre-edit -f src/auth.js -o refactor
claude-flow hooks pre-command -c "rm -rf dist"
claude-flow hooks pre-task -d "Implement user authentication" --auto-spawn

Post-operation hooks (run AFTER the tool)

claude-flow hooks post-edit -f src/auth.js --success true
claude-flow hooks post-command -c "npm test" --success true
claude-flow hooks post-task -i task-123 --success true -q 0.9

Routing hooks

claude-flow hooks route -t "Fix authentication bug"
claude-flow hooks explain -t "Fix authentication bug" -a coder --verbose

Session hooks

claude-flow hooks session-end
claude-flow hooks session-restore -i latest
claude-flow hooks notify -m "Task complete" -l info

Learning and diagnostics

claude-flow hooks metrics --period 7d --v3-dashboard
claude-flow hooks list --enabled

claude-flow hooks --help lists every subcommand, including worker/progress/statusline/coverage-*/token-optimize/model-* -- check there before relying on a flag not shown above, the CLI is the source of truth, not this table.

Which Hook to Use When

Memory Coordination

Hooks that need to share state across agents do it through mcp__claude-flow__memory_usage directly (namespace coordination), not through a dedicated hook subcommand. A three-phase status -> progress -> complete pattern is a convention you can apply in a custom hook script, not an automatic behaviour of the built-in hooks above. Worked example: references/examples.md#memory-coordination-pattern.

Performance Tips

1. Prefer the deprecation-free, current subcommand names (pre-command, not the deprecated route-task/session-start aliases)
2. Keep custom hook scripts fast; heavy work belongs in a background job, not the hook's PreToolUse/PostToolUse path
3. Batch related memory_usage writes rather than one call per field
4. Set an explicit "timeout" in settings.json hook entries for anything that shells out

Troubleshooting

Integration with Other Skills

• SPARC Methodology -- hooks enhance SPARC workflows
• build-with-quality -- automated quality gates in a full dev+QE pipeline (supersedes the old "Pair Programming" skill, deprecated and merged in)
• lazy-fetch -- owns the single-agent plan/memory/security-scan hook lifecycle (SessionStart/PostToolUse/PreCompact/Stop); this skill owns swarm-coordination and neural/routing-pattern hooks. Install both together if you need both lifecycles; they do not register the same hook events.
• GitHub workflows -- Git integration for commits/PRs (see references/examples.md)
• Performance analysis -- metrics collection in hooks

Related Commands

claude-flow hooks --help              # every real subcommand
claude-flow hooks list                # list registered hooks
claude-flow hooks metrics             # learning metrics dashboard
claude-flow hooks pretrain            # bootstrap intelligence from repo