🔗 HookFlow - AI Agent Hooks
Automated event-driven AI agent hooks for Visual Studio Code
Transform your development workflow with intelligent automation! AI Agent Hooks allows you to create smart hooks that automatically trigger AI-powered code modifications based on file events using natural language descriptions.
✨ Features
🤖 Natural Language Hook Creation
- Describe what you want in plain language
- Example: "Whenever I modify a Kotlin file, add KDoc comments to all functions"
- AI automatically generates the appropriate code modifications
🎯 Event-Driven Automation
- File Save: Trigger when files are saved
- File Change: React to file modifications
- File Open: Execute when files are opened
- File Create: Respond to new file creation
- File Delete: Handle file deletion events
🔧 Advanced Hook Management
- Visual Hook Manager: Easy-to-use WebView interface with MCP configuration
- Real-time Status: See when hooks are running with MCP execution details
- Live Editing: Modify hooks and MCP settings on-the-fly
- Pattern Matching: Target specific file types with glob patterns
- Stop Control: Cancel running hooks anytime
- MCP Tool Selection: Visual interface for enabling project-specific tools
🛡️ Smart Safety Features
- Anti-Recursion: Prevents hooks from triggering themselves
- Cooldown System: Configurable delays between executions
- Cross-Hook Protection: Prevents hooks from triggering each other
- File Pattern Filtering: Precise control over which files trigger hooks
🌐 Multiple AI Provider Support
- OpenAI (GPT-4, GPT-3.5)
- Anthropic (Claude 3 Sonnet, Haiku)
- Ollama (Local LLMs)
- Azure OpenAI
🚀 Quick Start
Install the Extension
# Install from VSCode Marketplace or load as development extension
Configure AI Provider
- Open Command Palette (
Ctrl+Shift+P)
- Run
HookFlow - AI Agent Hooks: Choose AI Provider
- Choose your preferred AI provider and enter credentials
Configure MCP Tools (Optional)
- Open Command Palette (
Ctrl+Shift+P)
- Run
HookFlow - AI Agent Hooks: Configure MCP Tools
- Select tools based on your project (Git tools, file operations, etc.)
- This enables advanced multi-step reasoning for hooks
Create Your First Hook
- Open Command Palette (
Ctrl+Shift+P)
- Run
HookFlow - AI Agent Hooks: Open Hook Manager
- Click "🚀 Create Hook"
- Fill in natural language description
- Select trigger event and file pattern
- Enable MCP for advanced reasoning:
- Check "Enable MCP" for multi-step execution
- Select project-specific tools (recommended tools pre-selected)
- Enable multi-step execution for complex workflows
Watch the Magic Happen
- Your hooks will automatically execute when conditions are met
- Monitor status in real-time through the Hook Manager
📋 Example Use Cases
📝 Documentation Automation
Name: Kotlin KDoc Generator
Description: "Whenever I change a Kotlin file, add KDoc comments to all functions"
Trigger: File saved
Pattern: **/*.kt
MCP: ✅ Enabled with mcp_filesystem_read, mcp_search_find
Multi-Step: ✅ Analyzes existing code patterns before adding docs
🧪 Test Generation
Name: JavaScript Test Creator
Description: "When I create a new JS file, generate corresponding Jest test file"
Trigger: File created
Pattern: **/*.js
MCP: ✅ Enabled with mcp_filesystem_list, mcp_search_grep
Multi-Step: ✅ Finds existing test patterns and follows project conventions
Name: Python Style Checker
Description: "On every Python save, check code quality and add docstrings"
Trigger: File saved
Pattern: **/*.py
MCP: ✅ Enabled with mcp_search_grep, mcp_git_status
Multi-Step: ✅ Checks git status and analyzes project style before modifications
📖 README Maintenance
Name: Project Documentation
Description: "When I create any file, update the README.md with project structure"
Trigger: File created
Pattern: **/*
MCP: ✅ Enabled with mcp_filesystem_list, mcp_filesystem_read_multiple
Multi-Step: ✅ Analyzes entire project structure and existing README before updates
📚 Extension Settings
Configure AI Agent Hooks through VSCode settings:
AI Provider Configuration
{
"aiAgentHooks.provider": "openai",
"aiAgentHooks.openai.apiKey": "your-api-key",
"aiAgentHooks.openai.model": "gpt-4",
"aiAgentHooks.anthropic.apiKey": "your-claude-key",
"aiAgentHooks.anthropic.model": "claude-3-sonnet-20240229",
"aiAgentHooks.ollama.baseUrl": "http://localhost:11434",
"aiAgentHooks.ollama.model": "llama2",
"aiAgentHooks.azureOpenai.apiKey": "your-azure-key",
"aiAgentHooks.azureOpenai.baseUrl": "https://your-resource.openai.azure.com",
"aiAgentHooks.azureOpenai.model": "your-deployment-name"
}
MCP (Model Context Protocol) Configuration
{
"aiAgentHooks.mcp.enabled": true,
"aiAgentHooks.mcp.defaultTools": [
"mcp_filesystem_list",
"mcp_filesystem_read",
"mcp_search_find",
"mcp_git_status"
],
"aiAgentHooks.mcp.allowedTools": [
"mcp_filesystem_list",
"mcp_filesystem_read",
"mcp_filesystem_read_multiple",
"mcp_search_find",
"mcp_search_grep",
"mcp_git_status",
"mcp_git_log"
]
}
🎮 Commands
| Command |
Description |
AI Agent Hooks: Choose AI Provider |
Select and configure AI provider |
AI Agent Hooks: Test AI Provider |
Test current AI provider connection |
AI Agent Hooks: Open Hook Manager |
Open visual Hook Manager interface |
AI Agent Hooks: Configure MCP Tools |
Configure MCP tools for this project |
🏗️ Architecture
Core Components
- HookManager: Central hook lifecycle management
- HookExecutor: Event listening and hook execution
- ProviderManager: AI provider abstraction layer
- WebView Provider: Visual interface for hook management
- FileUtils: Cross-platform file operations
Hook Lifecycle
- Registration: Active hooks register event listeners
- Triggering: File events trigger pattern matching
- Execution: AI provider processes natural language
- Application: Code changes applied to target files
- Completion: Status updates sent to WebView
🧪 Testing
Comprehensive test suite with 63 passing tests:
npm test # Run all tests
npm run compile # Compile TypeScript
npm run lint # Check code style
Test Coverage
- ✅ Hook Management (CRUD operations, persistence)
- ✅ Hook Execution (triggers, patterns, cooldowns)
- ✅ AI Provider Integration (all provider types)
- ✅ WebView Communication (real-time updates)
- ✅ File Operations (cross-platform compatibility)
🔒 Security & Safety
Built-in Protection
- No Secret Logging: API keys never appear in logs
- Local Storage: Hooks stored locally in VSCode settings
- Permission Control: Only modifies files based on explicit patterns
- Execution Limits: Cooldown prevents runaway executions
Best Practices
- Start with simple, specific hooks
- Use narrow file patterns (
**/*.js vs **/*)
- Test hooks on small projects first
- Regular backup of important code
🐛 Known Issues
Standard Hooks (Non-MCP) Limitations
Standard hooks without MCP enabled implement simple prompt-response patterns. This results in several limitations:
Context Awareness
- Limited Scope: Hooks only analyze the single triggered file, missing broader project context
- No Project Understanding: Cannot analyze folder structures, related files, or project dependencies
- Static Processing: No dynamic exploration of codebase or adaptive reasoning based on discoveries
Missing Agent Capabilities
- No Multi-Step Planning: Cannot break down complex tasks into logical sub-steps
- No File System Exploration: Cannot list directory contents or explore project structure
- No Multi-File Reading: Cannot read multiple related files to understand context
- No Command Execution: Cannot run read-only commands (ls, find, grep, git status) to gather information
- No Configurable Tool Access: Missing whitelist system for allowing specific safe commands
- No Cross-File Analysis: Cannot read related files (tests, configs, documentation) to inform decisions
- No Iterative Refinement: Cannot analyze results and adjust approach based on intermediate outcomes
Examples of Current Limitations
Current: Simple transformation
"Add JSDoc to this function" → Modifies single file
Missing: Complex agent workflow
"Refactor this component following project patterns" →
- List project files to understand structure (ls, find)
- Read similar components for pattern analysis
- Execute git status to check for uncommitted changes
- Extract common patterns from multiple files
- Apply consistent architecture with context awareness
- Update related tests and documentation files
Impact on Use Cases
- Architecture Decisions: Cannot analyze project patterns for consistent refactoring
- Smart Test Generation: Cannot understand existing test patterns and file relationships
- Documentation Sync: Cannot cross-reference multiple files for comprehensive docs
- Code Migration: Cannot analyze dependencies and impact across multiple files
🔧 Potential Solution: MCP Integration
The limitations above could be addressed through Model Context Protocol (MCP) integration, which would enable sophisticated AI agent workflows:
Proposed MCP Architecture
Hook Trigger → MCP Client → AI Model with Tools → Multi-Step Execution → File Modifications
MCP-Enabled Capabilities
File System Tools
mcp_filesystem: List directories, explore project structuremcp_search: Advanced file searching with grep, ripgrepmcp_git: Git operations (status, log, diff) for context
Multi-File Operations
- Read multiple related files simultaneously
- Cross-reference imports, exports, and dependencies
- Analyze test patterns across the codebase
Configurable Tool Access
- Whitelist system for allowed MCP tools
- Security boundaries for safe command execution
- User-controlled permission levels per hook
Agent Workflow Example
"Refactor component following project patterns" →
1. mcp_filesystem.list() - Explore project structure
2. mcp_search.find() - Locate similar components
3. mcp_filesystem.read_multiple() - Analyze patterns
4. mcp_git.status() - Check for conflicts
5. Multi-step reasoning and planning
6. Coordinated file modifications
Implementation Benefits
- Context-Aware: Full project understanding before modifications
- Safe Execution: MCP security model prevents dangerous operations
- Extensible: Plugin architecture for custom tools
- Configurable: User controls which tools each hook can access
✅ IMPLEMENTED: The above MCP integration is now available! Enable MCP in the Hook Manager UI to unlock advanced reasoning capabilities.
Current Status: MCP Available
The Hook Manager now includes:
- ✅ Visual MCP Configuration in the UI
- ✅ Project-Specific Tool Detection (Git tools for Git repos, etc.)
- ✅ Multi-Step Execution with context awareness
- ✅ Tool Whitelisting per hook
- ✅ Real-Time Status showing MCP vs Standard execution
Simply check "Enable MCP" when creating hooks to access sophisticated AI agent workflows!
📈 Roadmap
- 🔮 v0.1.0: MCP Integration ✅ IMPLEMENTED
- ✅ MCP Client with filesystem, search, and git tools
- ✅ Multi-step execution with AI planning
- ✅ Configurable tool whitelisting per hook
- ✅ Advanced reasoning capabilities with context awareness
- ✅ Visual MCP configuration in Hook Manager WebView
- ✅ Project-specific tool recommendations
- ✅ Real-time MCP status indicators
- 🚀 v0.2.0: Enhanced Analytics & Debugging
- 🎨 Real-time execution step visualization
- 📊 Hook performance analytics
- 🔍 MCP execution debugging tools
- 🌟 v0.3.0: Advanced Features
- 🔌 Custom MCP tool plugins
- 🤝 Team hook sharing and templates
- 🔄 Hook execution pipelines
🤝 Contributing
We welcome contributions! Please see our contributing guidelines:
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature)
- Run tests (
npm test)
- Commit changes (
git commit -m 'Add amazing feature')
- Push to branch (
git push origin feature/amazing-feature)
- Open Pull Request
📄 License
This project is licensed under the GNU General Public License v3.0 (GPLv3).
See the LICENSE file for full license details.
© 2025 sockethunter. All rights reserved.
Note: If you modify or redistribute this project, the source code must remain under GPLv3, and my name as the original author must be retained.
💖 Support
