Kiro Hooks Complete Documentation Guide

Introduction and Core Concepts

Kiro Hooks are powerful automation tools that streamline your development workflow by automatically executing predefined agent actions when specific events occur in your IDE. With hooks, you eliminate the need to manually request routine tasks and ensure consistency across your codebase.

What are Agent Hooks?

Agent Hooks are automated triggers that execute predefined agent actions when specific events occur in your IDE. Rather than manually asking for routine tasks to be performed, hooks set up automated responses to events such as:

• Saving files
• Creating new files
• Deleting files

Benefits of Agent Hooks

Agent Hooks transform your development workflow through intelligent automation. By setting up hooks for common tasks, you can:

• Maintain consistent code quality
• Prevent security vulnerabilities
• Reduce manual overhead
• Standardize team processes
• Create faster development cycles

How Agent Hooks Work

flowchart LR
    A[Event Detection] --> B[Prompt Execution]
    B --> C[Automated Action]
    
    A1[File Save/Create/Delete] --> A
    B1[Predefined Prompt] --> B
    C1[Agent Processing] --> C

The Agent Hook system follows a simple three-step process:

1. Event Detection: The system monitors for specific events in your IDE
2. Prompt Execution: When an event occurs, a predefined prompt is sent to the agent
3. Automated Action: The agent processes the prompt and performs the requested actions

Hook Types and Triggers

Agent Hooks support various trigger types, each designed for specific automation scenarios:

1. On File Create

Trigger: When new files matching specific patterns are created in your workspace.

Use Cases:

• Generate boilerplate code for new components
• Add license headers to new files
• Set up test files when creating implementation files

2. On File Save

Trigger: When files matching specific patterns are saved.

Use Cases:

• Run linting and formatting
• Update related files
• Generate documentation
• Run tests for changed files

3. On File Delete

Trigger: When files matching specific patterns are deleted.

Use Cases:

• Clean up related files
• Update import references in other files
• Maintain project integrity

4. Manual Trigger

Trigger: Manually execute a hook.

Use Cases:

• On-demand code reviews
• Documentation generation
• Security scanning
• Performance optimization

Hook Management and Configuration

Setting Up Agent Hooks

Creating and managing hooks is straightforward:

Using the Explorer View

1. Navigate to the Agent Hooks section in the Kiro panel
2. Click the + button to create a new hook
3. Define the hook workflow using natural language in the input field
4. Press Enter or click Submit to proceed
5. Configure the hook settings and save

Using the Command Palette

1. Open the command palette with Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows/Linux)
2. Type Kiro: Open Kiro Hook UI
3. Follow the on-screen instructions to create your hook

Managing Your Hooks

Access all your hooks through the Agent Hooks section in the Kiro panel.

Enable/Disable Hooks

Toggle hooks on/off without deleting them:

• Quick toggle: Click the eye icon next to any hook in the Agent Hooks panel
• From hook view: Select a hook and use the Hook Enabled switch in the top-right corner

Edit Existing Hooks

Hooks evolve with your workflow. Update them anytime by selecting your hook in the Agent Hooks panel and modifying settings like triggers, file patterns, instructions, or descriptions. Updates apply immediately.

Delete Hooks

Select the hook in the Agent Hooks panel, click Delete Hook located at the bottom view, then click delete. This action cannot be undone.

Run Manual Trigger Hooks

You can execute a manual trigger hook using:

• Quick run: Click the play button (▷) next to the hook name in the Agent Hooks panel
• From hook view: Select the hook and click Start Hook in the top-right corner

Best Practices and Guidelines

Following these best practices will help you create reliable, efficient, and maintainable hooks that enhance your development workflow.

Hook Design

Be Specific and Clear

• Write detailed, unambiguous instructions
• Focus on one specific task per hook
• Use numbered steps for complex operations

Test Thoroughly

• Test hooks on sample files before deploying
• Verify hooks work with edge cases
• Start with limited file patterns before expanding

Monitor Performance

• Ensure hooks don't slow down your workflow
• Consider the frequency of trigger events
• Optimize prompts for efficiency

Security Considerations

Validate Inputs

• Ensure hooks handle unexpected file content gracefully
• Consider potential edge cases in file formats
• Test with malformed or unexpected input

Limit Scope

• Target specific file types or directories when possible
• Use precise file patterns to avoid unnecessary executions
• Consider the impact of hooks on your entire codebase

Review Regularly

• Update hook logic as your project evolves
• Remove hooks that are no longer needed
• Refine prompts based on actual results

Team Collaboration

Document Hooks

• Maintain clear documentation of hook purposes
• Include examples of expected behavior
• Document any limitations or edge cases

Standardize Workflows

• Use consistent hooks across team members
• Store hook configurations in version control
• Create standard hooks for common team workflows

Version Control Integration

• Consider hooks that integrate with your version control system
• Create hooks for code review workflows
• Use hooks to enforce team standards

Practical Use Cases and Examples

These examples demonstrate real-world hook implementations that you can adapt for your own projects.

1. Security Pre-Commit Scanner

Trigger Type: File Save
Target: **/*

This hook helps prevent security leaks by scanning files before they're committed.

Hook Instructions:

Scan this file for potential security issues including:
- API keys, passwords, or secrets
- Hardcoded credentials
- Potential SQL injection vulnerabilities
- XSS vulnerabilities
- Insecure configurations

If any issues are found, provide specific recommendations for fixes.

2. Internationalization Helper

Trigger Type: File Save
Target: src/locales/en/*.json

This hook ensures that when you update text in your primary language file, translations are kept in sync.

Hook Instructions:

Check if this English locale file has new keys that don't exist in other language files.
For any missing keys, add them to the corresponding files with placeholder text
that indicates translation is needed.

3. Documentation Generator

Trigger Type: Manual Trigger

This hook automatically updates documentation when code changes.

Hook Instructions:

Generate comprehensive documentation for the current project including:
- API documentation for all public functions
- Usage examples
- Installation instructions
- Configuration options

Update the README.md file with the latest information.

4. Test Coverage Maintainer

Trigger Type: File Save
Target: src/**/*.{js,ts,jsx,tsx}

This hook ensures test coverage remains high as code evolves.

Hook Instructions:

Analyze this file and check if corresponding test files exist.
If tests are missing or incomplete:
- Create or update test files
- Ensure all public functions are tested
- Add edge case tests where appropriate

Integration with MCP

Agent Hooks can be enhanced with Model Context Protocol (MCP) capabilities to extend their functionality:

1. Access to External Tools: Hooks can leverage MCP servers to access specialized tools and APIs
2. Enhanced Context: MCP provides additional context for more intelligent hook actions
3. Domain-Specific Knowledge: Specialized MCP servers can provide domain expertise

Example: Validate Figma Design

Trigger Type: File Save Hook
Target: *.css *.html

Hook Instructions:

Using the Figma MCP, validate that the HTML and CSS changes in this file
follow the design system specifications. Check for:
- Color consistency with design tokens
- Typography alignment with style guide
- Spacing and layout adherence to grid system

Provide specific feedback on any deviations.

Troubleshooting and Common Issues

While the troubleshooting page content was not fully available in the provided information, here are common troubleshooting approaches for Kiro Hooks:

Common Issues

Hook Not Triggering

• Verify the file pattern matches your target files
• Check if the hook is enabled in the Agent Hooks panel
• Ensure the trigger event is occurring as expected

Performance Issues

• Review hook frequency and scope
• Optimize prompt complexity
• Consider limiting file patterns to reduce unnecessary executions

Unexpected Results

• Review and refine hook instructions for clarity
• Test with sample files before deploying to production
• Check for edge cases in your file patterns

Debugging Steps

1. Check Hook Status: Verify the hook is enabled and properly configured
2. Test File Patterns: Ensure your target patterns match the intended files
3. Review Logs: Check for any error messages or warnings
4. Simplify Instructions: Start with basic instructions and gradually add complexity
5. Test Incrementally: Test hooks on small file sets before applying broadly

Best Practices for Troubleshooting

• Keep detailed documentation of hook configurations
• Use version control for hook settings when possible
• Test hooks in development environments before production
• Monitor hook performance and adjust as needed
• Regularly review and update hook logic as projects evolve