cline/docs/features/hooks/index.mdx

---
title: "Hooks Overview"
sidebarTitle: "Overview"
description: "Inject custom logic into Cline's workflow to validate operations, monitor tool usage, and shape AI decisions"
---

Hooks let you inject custom logic into Cline's workflow at key moments. Think of them as automated checkpoints where you can validate operations before they execute, monitor tool usage as it happens, and shape how Cline makes decisions.

Hooks run automatically when specific events happen during development. They receive detailed information about each operation, can block problematic actions before they cause issues, and can inject context that guides future AI decisions.

The real power comes from combining these capabilities. You can:

- Stop operations before they cause problems (like creating `.js` files in a TypeScript project)
- Learn from what's happening and build up project knowledge over time
- Monitor performance and catch issues as they emerge
- Track everything for analytics or compliance
- Trigger external tools or services at the right moments

## Getting Started

<Frame>
	<img src="https://storage.googleapis.com/cline_public_images/hooks.gif" alt="Hooks in action" />
</Frame>

<Note>
Hooks work across all platforms: Windows, macOS, and Linux. The bash examples in this documentation work with standard shells on all platforms (including Git Bash or WSL on Windows).
</Note>

Setting up hooks in Cline is user-friendly with the built-in hooks management interface. Here's how to get started:

<Steps>
<Step title="Access the Hooks Interface">
Navigate to the Hooks management interface:

<Frame>
  <img src="/assets/hooks/hooks-interface-with-dropdown.png" alt="Hooks management interface showing Global Hooks and project-specific hooks with dropdown menu" />
</Frame>

1. Open Cline (ensure hooks are enabled in settings)
2. Look for the **Hooks** tab at the top (alongside Rules and Workflows)
3. Click on **Hooks** to open the hooks management panel

The interface shows you all available hook types and existing hooks organized by workspace.
</Step>

<Step title="Understand Hook Locations">
Hooks are automatically organized by location in the interface:

**Global Hooks** - Apply to all workspaces:
- Stored in `~/Documents/Cline/Hooks/`
- Perfect for personal coding standards and universal rules

**Project-Specific Hooks** - Apply only to current project:
- Stored in `.clinerules/hooks/` within your repo
- Great for project-specific validation and team workflows
- Can be committed to version control for team sharing

Multi-root workspaces run hooks from all of the repos in your open workspace, making it easy to manage and run hooks across different repos within the same workspace.
</Step>

<Step title="Create Your First Hook">
Use the intuitive interface to create hooks:

<Frame>
  <img src="/assets/hooks/hooks-empty-state.png" alt="Empty hooks interface showing New hook... dropdowns for both Global Hooks and project-specific hooks before any hooks are created" />
</Frame>

1. **Choose your location**: Decide between Global Hooks or project-specific hooks
2. **Select hook type**: Click the **"New hook..."** dropdown in your chosen location
3. **Pick a hook type**: The dropdown shows all available hook types that haven't been created yet in this location. Only one of each hook type is allowed per hooks directory, so the dropdown automatically filters to show only the remaining available types.

<Frame>
  <img src="/assets/hooks/new-hook-dropdown.png" alt="Creating a new hook with the dropdown menu showing UserPromptSubmit selected with description" />
</Frame>

4. **Review and edit the hook**: Click the pencil icon to review the hook's code and add your custom logic
5. **Enable the hook**: Once you understand and approve of the hook's behavior, toggle the switch to activate it

<Frame>
  <img src="/assets/hooks/hook-controls.png" alt="Hook management controls showing toggle, edit, and delete buttons for each hook" />
</Frame>

<Warning>
Always review a hook's code before enabling it. Hooks execute automatically during your workflow, so it's important to understand what they do before activation.
</Warning>
</Step>

<Step title="Test Your Hook">
To develop and refine your hook, you'll need to trigger it multiple times during testing. Each hook type is triggered by different events in Cline's workflow. For example:

- **TaskStart** hooks trigger when you start a new task
- **PreToolUse** hooks trigger before Cline executes tools like file editing
- **PostToolUse** hooks trigger after tool execution completes
- **UserPromptSubmit** hooks trigger when you submit a message to Cline

For complete details on when each hook type is triggered and how to test them effectively, see the [Hook Reference](/features/hooks/hook-reference) documentation. This includes the specific conditions that trigger each hook and examples of how to invoke them during development.
</Step>
</Steps>

<Tip>
Start with a simple hook that just logs information before building complex validation logic. This helps you understand the data structure and timing.
</Tip>

## What You Can Build

Once you understand the basics, hooks open up creative possibilities:

<CardGroup cols={2}>
  <Card title="Intelligent Code Review" icon="code-branch">
    Run linters or custom validators before files get saved. Block commits that don't pass checks. Track code quality metrics over time.
  </Card>
  
  <Card title="Security Enforcement" icon="shield-halved">
    Prevent operations that violate security policies. Detect when sensitive data might be exposed. Audit all file access for compliance.
  </Card>
  
  <Card title="Development Analytics" icon="chart-line">
    Measure how long different operations take. Identify patterns in how the AI works. Generate productivity reports from hook data.
  </Card>
  
  <Card title="Integration Hub" icon="plug">
    Connect to issue trackers when certain keywords appear. Update project management tools. Sync with external APIs at the right moments.
  </Card>
</CardGroup>

The key is combining hooks with external tools. A hook can be the glue between Cline's workflow and the rest of your development ecosystem.

## Explore the Documentation

<CardGroup cols={2}>
  <Card title="Hook Reference" icon="book" href="/features/hooks/hook-reference">
    Complete API reference for all hook types, JSON schemas, and field documentation.
  </Card>
  
  <Card title="Samples" icon="code" href="/features/hooks/samples">
    Practical examples and complete working scripts for common use cases.
  </Card>
</CardGroup>

## CLI support

Hooks are also available in the [Cline CLI](/cline-cli/overview). You can enable or disable hooks when running tasks from the command line:

```bash
# Enable hooks for a task
cline "What does this repo do?" -s hooks_enabled=true

# Configure hooks globally via CLI
cline config set hooks-enabled=true
cline config get hooks-enabled
```

This allows you to integrate hooks into automated workflows, CI/CD pipelines, and headless task execution.

<Note>
Hooks in the CLI are only supported on macOS and Linux. Windows support is not yet available.
</Note>

## Related features

Hooks complement other Cline features:

- [Cline Rules](/features/cline-rules) define high-level guidance that hooks can enforce
- [Checkpoints](/features/checkpoints) let you roll back changes if a hook didn't catch an issue
- [Auto-Approve](/features/auto-approve) works well with hooks as safety nets for automated operations
- [Cline CLI](/cline-cli/overview) enables hooks in terminal-based and automated workflows