| name | Hooks Automation |
| description | Automated coordination, formatting, and learning from Claude Code operations using intelligent hooks with MCP integration. Includes pre/post task hooks, session management, Git integration, memory coordination, and neural pattern training for enhanced development workflows. |
Hooks Automation
Intelligent automation system that coordinates, validates, and learns from Claude Code operations through hooks integrated with MCP tools and neural pattern training.
What This Skill Does
This skill provides a comprehensive hook system that automatically manages development operations, coordinates swarm agents, maintains session state, and continuously learns from coding patterns. It enables automated agent assignment, code formatting, performance tracking, and cross-session memory persistence.
Key Capabilities:
- Pre-Operation Hooks: Validate, prepare, and auto-assign agents before operations
- Post-Operation Hooks: Format, analyze, and train patterns after operations
- Session Management: Persist state, restore context, generate summaries
- Memory Coordination: Synchronize knowledge across swarm agents
- Git Integration: Automated commit hooks with quality verification
- Neural Training: Continuous learning from successful patterns
- MCP Integration: Seamless coordination with swarm tools
Prerequisites
Required:
- Claude Flow CLI installed (
npm install -g claude-flow@alpha)
- Claude Code with hooks enabled
.claude/settings.json with hook configurations
Optional:
- MCP servers configured (claude-flow, ruv-swarm, flow-nexus)
- Git repository for version control
- Testing framework for quality verification
Quick Start
Initialize Hooks System
npx @claude-flow/cli@latest init --hooks
This creates:
.claude/settings.json with pre-configured hooks- Hook command documentation in
.claude/commands/hooks/
- Default hook handlers for common operations
Basic Hook Usage
npx @claude-flow/cli@latest hook pre-task --description "Implement authentication"
npx @claude-flow/cli@latest hook post-edit --file "src/auth.js" --memory-key "auth/login"
npx @claude-flow/cli@latest hook session-end --session-id "dev-session" --export-metrics
Complete Guide
Available Hooks
Pre-Operation Hooks
Hooks that execute BEFORE operations to prepare and validate:
pre-edit - Validate and assign agents before file modifications
npx @claude-flow/cli@latest hook pre-edit [options]
Options:
--file, -f <path> File path to be edited
--auto-assign-agent Automatically assign best agent (default: true)
--validate-syntax Pre-validate syntax before edit
--check-conflicts Check for merge conflicts
--backup-file Create backup before editing
Examples:
npx @claude-flow/cli@latest hook pre-edit --file "src/auth/login.js"
npx @claude-flow/cli@latest hook pre-edit -f "config/db.js" --validate-syntax
npx @claude-flow/cli@latest hook pre-edit -f "production.env" --backup-file --check-conflicts
Features:
- Auto agent assignment based on file type
- Syntax validation to prevent broken code
- Conflict detection for concurrent edits
- Automatic file backups for safety
pre-bash - Check command safety and resource requirements
npx @claude-flow/cli@latest hook pre-bash --command <cmd>
Options:
--command, -c <cmd> Command to validate
--check-safety Verify command safety (default: true)
--estimate-resources Estimate resource usage
--require-confirmation Request user confirmation for risky commands
Examples:
npx @claude-flow/cli@latest hook pre-bash -c "rm -rf /tmp/cache"
npx @claude-flow/cli@latest hook pre-bash --command "docker build ." --estimate-resources
Features:
- Command safety validation
- Resource requirement estimation
- Destructive command confirmation
- Permission checks
pre-task - Auto-spawn agents and prepare for complex tasks
npx @claude-flow/cli@latest hook pre-task [options]
Options:
--description, -d <text> Task description for context
--auto-spawn-agents Automatically spawn required agents (default: true)
--load-memory Load relevant memory from previous sessions
--optimize-topology Select optimal swarm topology
--estimate-complexity Analyze task complexity
Examples:
npx @claude-flow/cli@latest hook pre-task --description "Implement user authentication"
npx @claude-flow/cli@latest hook pre-task -d "Continue API dev" --load-memory
npx @claude-flow/cli@latest hook pre-task -d "Refactor codebase" --optimize-topology
Features:
- Automatic agent spawning based on task analysis
- Memory loading for context continuity
- Topology optimization for task structure
- Complexity estimation and time prediction
pre-search - Prepare and optimize search operations
npx @claude-flow/cli@latest hook pre-search --query <query>
Options:
--query, -q <text> Search query
--check-cache Check cache first (default: true)
--optimize-query Optimize search pattern
Examples:
npx @claude-flow/cli@latest hook pre-search -q "authentication middleware"
Features:
- Cache checking for faster results
- Query optimization
- Search pattern improvement
Post-Operation Hooks
Hooks that execute AFTER operations to process and learn:
post-edit - Auto-format, validate, and update memory
npx @claude-flow/cli@latest hook post-edit [options]
Options:
--file, -f <path> File path that was edited
--auto-format Automatically format code (default: true)
--memory-key, -m <key> Store edit context in memory
--train-patterns Train neural patterns from edit
--validate-output Validate edited file
Examples:
npx @claude-flow/cli@latest hook post-edit --file "src/components/Button.jsx"
npx @claude-flow/cli@latest hook post-edit -f "api/auth.js" --memory-key "auth/login"
npx @claude-flow/cli@latest hook post-edit -f "utils/helpers.ts" --train-patterns
Features:
- Language-specific auto-formatting (Prettier, Black, gofmt)
- Memory storage for edit context and decisions
- Neural pattern training for continuous improvement
- Output validation with linting
post-bash - Log execution and update metrics
npx @claude-flow/cli@latest hook post-bash --command <cmd>
Options:
--command, -c <cmd> Command that was executed
--log-output Log command output (default: true)
--update-metrics Update performance metrics
--store-result Store result in memory
Examples:
npx @claude-flow/cli@latest hook post-bash -c "npm test" --update-metrics
Features:
- Command execution logging
- Performance metric tracking
- Result storage for analysis
- Error pattern detection
post-task - Performance analysis and decision storage
npx @claude-flow/cli@latest hook post-task [options]
Options:
--task-id, -t <id> Task identifier for tracking
--analyze-performance Generate performance metrics (default: true)
--store-decisions Save task decisions to memory
--export-learnings Export neural pattern learnings
--generate-report Create task completion report
Examples:
npx @claude-flow/cli@latest hook post-task --task-id "auth-implementation"
npx @claude-flow/cli@latest hook post-task -t "api-refactor" --analyze-performance
npx @claude-flow/cli@latest hook post-task -t "bug-fix-123" --store-decisions
Features:
- Execution time and token usage measurement
- Decision and implementation choice recording
- Neural learning pattern export
- Completion report generation
post-search - Cache results and improve patterns
npx @claude-flow/cli@latest hook post-search --query <query> --results <path>
Options:
--query, -q <text> Original search query
--results, -r <path> Results file path
--cache-results Cache for future use (default: true)
--train-patterns Improve search patterns
Examples:
npx @claude-flow/cli@latest hook post-search -q "auth" -r "results.json" --train-patterns
Features:
- Result caching for faster subsequent searches
- Search pattern improvement
- Relevance scoring
MCP Integration Hooks
Hooks that coordinate with MCP swarm tools:
mcp-initialized - Persist swarm configuration
npx @claude-flow/cli@latest hook mcp-initialized --swarm-id <id>
Features:
- Save swarm topology and configuration
- Store agent roster in memory
- Initialize coordination namespace
agent-spawned - Update agent roster and memory
npx @claude-flow/cli@latest hook agent-spawned --agent-id <id> --type <type>
Features:
- Register agent in coordination memory
- Update agent roster
- Initialize agent-specific memory namespace
task-orchestrated - Monitor task progress
npx @claude-flow/cli@latest hook task-orchestrated --task-id <id>
Features:
- Track task progress through memory
- Monitor agent assignments
- Update coordination state
neural-trained - Save pattern improvements
npx @claude-flow/cli@latest hook neural-trained --pattern <name>
Features:
- Export trained neural patterns
- Update coordination models
- Share learning across agents
Memory Coordination Hooks
memory-write - Triggered when agents write to coordination memory
Features:
- Validate memory key format
- Update cross-agent indexes
- Trigger dependent hooks
- Notify subscribed agents
memory-read - Triggered when agents read from coordination memory
Features:
- Log access patterns
- Update popularity metrics
- Preload related data
- Track usage statistics
memory-sync - Synchronize memory across swarm agents
npx @claude-flow/cli@latest hook memory-sync --namespace <ns>
Features:
- Sync memory state across agents
- Resolve conflicts
- Propagate updates
- Maintain consistency
Session Hooks
session-start - Initialize new session
npx @claude-flow/cli@latest hook session-start --session-id <id>
Options:
--session-id, -s <id> Session identifier
--load-context Load context from previous session
--init-agents Initialize required agents
Features:
- Create session directory
- Initialize metrics tracking
- Load previous context
- Set up coordination namespace
session-restore - Load previous session state
npx @claude-flow/cli@latest hook session-restore --session-id <id>
Options:
--session-id, -s <id> Session to restore
--restore-memory Restore memory state (default: true)
--restore-agents Restore agent configurations
Examples:
npx @claude-flow/cli@latest hook session-restore --session-id "swarm-20241019"
npx @claude-flow/cli@latest hook session-restore -s "feature-auth" --restore-memory
Features:
- Load previous session context
- Restore memory state and decisions
- Reconfigure agents to previous state
- Resume in-progress tasks
session-end - Cleanup and persist session state
npx @claude-flow/cli@latest hook session-end [options]
Options:
--session-id, -s <id> Session identifier to end
--save-state Save current session state (default: true)
--export-metrics Export session metrics
--generate-summary Create session summary
--cleanup-temp Remove temporary files
Examples:
npx @claude-flow/cli@latest hook session-end --session-id "dev-session-2024"
npx @claude-flow/cli@latest hook session-end -s "feature-auth" --export-metrics --generate-summary
npx @claude-flow/cli@latest hook session-end -s "quick-fix" --cleanup-temp
Features:
- Save current context and progress
- Export session metrics (duration, commands, tokens, files)
- Generate work summary with decisions and next steps
- Cleanup temporary files and optimize storage
notify - Custom notifications with swarm status
npx @claude-flow/cli@latest hook notify --message <msg>
Options:
--message, -m <text> Notification message
--level <level> Notification level (info|warning|error)
--swarm-status Include swarm status (default: true)
--broadcast Send to all agents
Examples:
npx @claude-flow/cli@latest hook notify -m "Task completed" --level info
npx @claude-flow/cli@latest hook notify -m "Critical error" --level error --broadcast
Features:
- Send notifications to coordination system
- Include swarm status and metrics
- Broadcast to all agents
- Log important events
Configuration
Basic Configuration
Edit .claude/settings.json to configure hooks:
{
"hooks": {
"PreToolUse": [
{
"matcher": "^(Write|Edit|MultiEdit)$",
"hooks": [{
"type": "command",
"command": "npx @claude-flow/cli@latest hook pre-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/current'"
}]
},
{
"matcher": "^Bash$",
"hooks": [{
"type": "command",
"command": "npx @claude-flow/cli@latest hook pre-bash --command '${tool.params.command}'"
}]
}
],
"PostToolUse": [
{
"matcher"
Advanced Configuration
Complete hook configuration with all features:
{
"hooks": {
"enabled": true,
"debug": false,
"timeout": 5000,
"PreToolUse": [
{
"matcher": "^(Write|Edit|MultiEdit)$",
"hooks": [
{
"type": "command",
"command": "npx @claude-flow/cli@latest hook pre-edit --file '${tool.params.file_path}' --auto-assign-agent --validate-syntax",
"timeout": 3000,
"continueOnError": true
}
]
},
{
"matcher": "^Task$",
Protected File Patterns
Add protection for sensitive files:
{
"hooks": {
"PreToolUse": [
{
"matcher": "^(Write|Edit|MultiEdit)$",
"hooks": [
{
"type": "command",
"command": "npx @claude-flow/cli@latest hook check-protected --file '${tool.params.file_path}'"
}
]
}
]
}
}
Automatic Testing
Run tests after file modifications:
{
"hooks": {
"PostToolUse": [
{
"matcher": "^Write$",
"hooks": [
{
"type": "command",
"command": "test -f '${tool.params.file_path%.js}.test.js' && npm test '${tool.params.file_path%.js}.test.js'",
"continueOnError": true
}
]
}
]
}
}
MCP Tool Integration
Hooks automatically integrate with MCP tools for coordination:
Pre-Task Hook with Agent Spawning
npx @claude-flow/cli@latest hook pre-task --description "Build REST API"
mcp__claude-flow__agent_spawn {
type: "backend-dev",
capabilities: ["api", "database", "testing"]
}
mcp__claude-flow__memory_usage {
action: "store",
key: "swarm/task/api-build/context",
namespace: "coordination",
value: JSON.stringify({
description: "Build REST API",
agents: ["backend-dev"],
started: Date.now()
})
}
Post-Edit Hook with Memory Storage
npx @claude-flow/cli@latest hook post-edit --file "api/auth.js"
mcp__claude-flow__memory_usage {
action: "store",
key: "swarm/edits/api/auth.js",
namespace: "coordination",
value: JSON.stringify({
file: "api/auth.js",
timestamp: Date.now(),
changes: { added: 45, removed: 12 },
formatted: true,
linted: true
})
}
mcp__claude-flow__neural_train {
pattern_type: "coordination",
training_data: { }
}
Session End Hook with State Persistence
npx @claude-flow/cli@latest hook session-end --session-id "dev-2024"
mcp__claude-flow__memory_persist {
sessionId: "dev-2024"
}
mcp__claude-flow__swarm_status {
swarmId: "current"
}
Memory Coordination Protocol
All hooks follow a standardized memory coordination pattern:
Three-Phase Memory Protocol
Phase 1: STATUS - Hook starts
mcp__claude-flow__memory_usage {
action: "store",
key: "swarm/hooks/pre-edit/status",
namespace: "coordination",
value: JSON.stringify({
status: "running",
hook: "pre-edit",
file: "src/auth.js",
timestamp: Date.now()
})
}
Phase 2: PROGRESS - Hook processes
mcp__claude-flow__memory_usage {
action: "store",
key: "swarm/hooks/pre-edit/progress",
namespace: "coordination",
value: JSON.stringify({
progress: 50,
action: "validating syntax",
file: "src/auth.js"
})
}
Phase 3: COMPLETE - Hook finishes
mcp__claude-flow__memory_usage {
action: "store",
key: "swarm/hooks/pre-edit/complete",
namespace: "coordination",
value: JSON.stringify({
status: "complete",
result: "success",
agent_assigned: "backend-dev",
syntax_valid: true,
backup_created: true
})
}
Hook Response Format
Hooks return JSON responses to control operation flow:
Continue Response
{
"continue": true,
"reason": "All validations passed",
"metadata": {
"agent_assigned": "backend-dev",
"syntax_valid": true,
"file": "src/auth.js"
}
}
Block Response
{
"continue": false,
"reason": "Protected file - manual review required",
"metadata": {
"file": ".env.production",
"protection_level": "high",
"requires": "manual_approval"
}
}
Warning Response
{
"continue": true,
"reason": "Syntax valid but complexity high",
"warnings": [
"Cyclomatic complexity: 15 (threshold: 10)",
"Consider refactoring for better maintainability"
],
"metadata": {
"complexity": 15,
"threshold": 10
}
}
Git Integration
Hooks can integrate with Git operations for quality control:
Pre-Commit Hook
FILES=$(git diff --cached --name-only --diff-filter=ACM)
for FILE in $FILES; do
npx @claude-flow/cli@latest hook pre-edit --file "$FILE" --validate-syntax
if [ $? -ne 0 ]; then
echo "Validation failed for $FILE"
exit 1
fi
npx @claude-flow/cli@latest hook post-edit --file "$FILE" --auto-format
done
npm test
exit $?
Post-Commit Hook
COMMIT_HASH=$(git rev-parse HEAD)
COMMIT_MSG=$(git log -1 --pretty=%B)
npx @claude-flow/cli@latest hook notify \
--message "Commit completed: $COMMIT_MSG" \
--level info \
--swarm-status
Pre-Push Hook
npm run test:all
npx @claude-flow/cli@latest hook session-end \
--generate-report \
--export-metrics
TRUTH_SCORE=$(npx @claude-flow/cli@latest metrics score --format json | jq -r '.truth_score')
if (( $(echo "$TRUTH_SCORE < 0.95" | bc -l) )); then
echo "Truth score below threshold: $TRUTH_SCORE < 0.95"
exit 1
fi
exit 0
Agent Coordination Workflow
How agents use hooks for coordination:
Agent Workflow Example
npx @claude-flow/cli@latest hook pre-task \
--description "Implement user authentication API" \
--auto-spawn-agents \
--load-memory
npx @claude-flow/cli@latest hook pre-edit \
--file "api/auth.js" \
--auto-assign-agent \
--validate-syntax
npx @claude-flow/cli@latest hook post-edit \
--file "api/auth.js" \
--memory-key "swarm/backend/auth-api" \
--auto-format \
--train-patterns
npx @claude-flow/cli@latest hook notify \
--message "Auth API implementation complete" \
--swarm-status \
--broadcast
npx @claude-flow/cli@latest hook post-task \
--task-id "auth-api" \
--analyze-performance \
--store-decisions \
--export-learnings
npx @claude-flow/cli@latest hook session-restore \
--session-id "swarm-current" \
--restore-memory
npx @claude-flow/cli@latest hook pre-task \
--description "Write tests for auth API" \
--load-memory
npx @claude-flow/cli@latest hook post-edit \
--file "api/auth.test.js" \
--memory-key "swarm/testing/auth-api-tests" \
--train-patterns
npx @claude-flow/cli@latest hook notify \
--message "Auth API tests complete - 100% coverage" \
--broadcast
Custom Hook Creation
Create custom hooks for specific workflows:
Custom Hook Template
module.exports = {
name: 'custom-quality-check',
type: 'pre',
matcher: /\.(ts|js)$/,
async execute(context) {
const { file, content } = context;
const complexity = await analyzeComplexity(content);
const securityIssues = await scanSecurity(content);
await storeInMemory({
key: `quality/${file}`,
value: { complexity, securityIssues }
});
if (complexity > 15 || securityIssues.length > 0) {
return {
continue: false,
reason: 'Quality checks failed',
warnings: [
`Complexity: ${complexity} (max: 15)`,
`Security issues: ${securityIssues.length}`
]
};
}
return {
continue: true,
reason: 'Quality checks passed',
metadata: { complexity, : }
};
}
};
Register Custom Hook
{
"hooks": {
"PreToolUse": [
{
"matcher": "^(Write|Edit)$",
"hooks": [
{
"type": "script",
"script": ".claude/hooks/custom-quality-check.js"
}
]
}
]
}
}
Real-World Examples
Example 1: Full-Stack Development Workflow
npx @claude-flow/cli@latest hook session-start --session-id "fullstack-feature"
npx @claude-flow/cli@latest hook pre-task \
--description "Build user profile feature - frontend + backend + tests" \
--auto-spawn-agents \
--optimize-topology
npx @claude-flow/cli@latest hook pre-edit --file "api/profile.js"
npx @claude-flow/cli@latest hook post-edit \
--file "api/profile.js" \
--memory-key "profile/backend" \
--train-patterns
npx @claude-flow/cli@latest hook pre-edit --file "components/Profile.jsx"
npx @claude-flow/cli@latest hook post-edit \
--file "components/Profile.jsx" \
--memory-key "profile/frontend" \
--train-patterns
npx @claude-flow/cli@latest hook pre-task \
--description "Test profile feature" \
--load-memory
npx @claude-flow/cli@latest hook session-end \
--session-id "fullstack-feature" \
--export-metrics \
--generate-summary
Example 2: Debugging with Hooks
npx @claude-flow/cli@latest hook session-start --session-id "debug-memory-leak"
npx @claude-flow/cli@latest hook pre-task \
--description "Debug memory leak in event handlers" \
--load-memory \
--estimate-complexity
npx @claude-flow/cli@latest hook pre-search --query "EventEmitter"
npx @claude-flow/cli@latest hook post-search \
--query "EventEmitter" \
--cache-results
npx @claude-flow/cli@latest hook pre-edit \
--file "services/events.js" \
--backup-file
npx @claude-flow/cli@latest hook post-edit \
--file "services/events.js" \
--memory-key "debug/memory-leak-fix" \
--validate-output
npx @claude-flow/cli@latest hook post-task \
--task-id "memory-leak-fix" \
--analyze-performance \
--generate-report
npx @claude-flow/cli@latest hook session-end \
--session-id "debug-memory-leak" \
--export-metrics
Example 3: Multi-Agent Refactoring
npx @claude-flow/cli@latest hook pre-task \
--description "Refactor legacy codebase to modern patterns" \
--auto-spawn-agents \
--optimize-topology
npx @claude-flow/cli@latest hook pre-task --description "Analyze code complexity"
npx @claude-flow/cli@latest hook post-task \
--task-id "analysis" \
--store-decisions
npx @claude-flow/cli@latest hook session-restore \
--session-id "swarm-refactor" \
--restore-memory
for file in src/**/*.js; do
npx @claude-flow/cli@latest hook pre-edit --file "$file" --backup-file
npx @claude-flow/cli@latest hook post-edit \
--file "$file" \
--memory-key "refactor/$file" \
--auto-format \
--train-patterns
done
npx @claude-flow/cli@latest hook pre-task \
--description "Generate tests for refactored code" \
--load-memory
npx @claude-flow/cli@latest hook notify \
--message "Refactoring complete - all tests passing" \
--broadcast
Performance Tips
- Keep Hooks Lightweight - Target < 100ms execution time
- Use Async for Heavy Operations - Don't block the main flow
- Cache Aggressively - Store frequently accessed data
- Batch Related Operations - Combine multiple actions
- Use Memory Wisely - Set appropriate TTLs
- Monitor Hook Performance - Track execution times
- Parallelize When Possible - Run independent hooks concurrently
Debugging Hooks
Enable debug mode for troubleshooting:
export CLAUDE_FLOW_DEBUG=true
npx @claude-flow/cli@latest hook pre-edit --file "test.js" --debug
cat .claude-flow/logs/hooks-$(date +%Y-%m-%d).log
npx @claude-flow/cli@latest hook validate-config
Benefits
- Automatic Agent Assignment: Right agent for every file type
- Consistent Code Formatting: Language-specific formatters
- Continuous Learning: Neural patterns improve over time
- Cross-Session Memory: Context persists between sessions
- Performance Tracking: Comprehensive metrics and analytics
- Automatic Coordination: Agents sync via memory
- Smart Agent Spawning: Task-based agent selection
- Quality Gates: Pre-commit validation and verification
- Error Prevention: Syntax validation before edits
- Knowledge Sharing: Decisions stored and shared
- Reduced Manual Work: Automation of repetitive tasks
- Better Collaboration: Seamless multi-agent coordination
Best Practices
- Configure Hooks Early - Set up during project initialization
- Use Memory Keys Strategically - Organize with clear namespaces
- Enable Auto-Formatting - Maintain code consistency
- Train Patterns Continuously - Learn from successful operations
- Monitor Performance - Track hook execution times
- Validate Configuration - Test hooks before production use
- Document Custom Hooks - Maintain hook documentation
- Set Appropriate Timeouts - Prevent hanging operations
- Handle Errors Gracefully - Use continueOnError when appropriate
- Review Metrics Regularly - Optimize based on usage patterns
Troubleshooting
Hooks Not Executing
- Verify
.claude/settings.json syntax
- Check hook matcher patterns
- Enable debug mode
- Review permission settings
- Ensure claude-flow CLI is in PATH
Hook Timeouts
- Increase timeout values in configuration
- Make hooks asynchronous for heavy operations
- Optimize hook logic
- Check network connectivity for MCP tools
Memory Issues
- Set appropriate TTLs for memory keys
- Clean up old memory entries
- Use memory namespaces effectively
- Monitor memory usage
Performance Problems
- Profile hook execution times
- Use caching for repeated operations
- Batch operations when possible
- Reduce hook complexity
Related Commands
npx @claude-flow/cli@latest init --hooks - Initialize hooks systemnpx @claude-flow/cli@latest hook --list - List available hooksnpx @claude-flow/cli@latest hook --test <hook> - Test specific hooknpx @claude-flow/cli@latest memory usage - Manage memorynpx @claude-flow/cli@latest agent spawn - Spawn agentsnpx @claude-flow/cli@latest swarm init - Initialize swarm
Integration with Other Skills
This skill works seamlessly with:
- SPARC Methodology - Hooks enhance SPARC workflows
- Pair Programming - Automated quality in pairing sessions
- Verification Quality - Truth-score validation in hooks
- GitHub Workflows - Git integration for commits/PRs
- Performance Analysis - Metrics collection in hooks
- Swarm Advanced - Multi-agent coordination via hooks
