> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

> Event-driven actions triggered during agent execution

The `hooks` command manages event-driven hooks configured in `.praison/hooks.json`.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List configured hooks
praisonai hooks list
```

<Frame>
  <img src="https://mintcdn.com/praisonai/SX0Y8_-DRBjzOTnt/docs/cli/hooks-list-event-hooks.gif?s=bdee2e73cb092f15ebe983f5aada3849" alt="List event hooks example" width="1497" height="1104" data-path="docs/cli/hooks-list-event-hooks.gif" />
</Frame>

## Usage

### List Hooks

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai hooks list
```

**Expected Output:**

```
╭─ Configured Hooks ───────────────────────────────────────────────────────────╮
│  🪝 pre_write_code - Validate before writing code                           │
│  🪝 post_write_code - Format after writing code                             │
│  🪝 on_error - Log errors to monitoring                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### Show Statistics

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai hooks stats
```

### Initialize Hooks

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai hooks init
```

Creates a template `.praison/hooks.json` file.

## Hooks Configuration

<img src="https://mintcdn.com/praisonai/fT4nF3hY6KPMOPvS/docs/cli/hooks-manage-event-driven-hooks.gif?s=bdeb4b65124d712deec5614e6c5e557a" alt="Manage Event-Driven Hooks" width="1497" height="1104" data-path="docs/cli/hooks-manage-event-driven-hooks.gif" />

Configure hooks in `.praison/hooks.json`:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "pre_write_code": {
    "type": "shell",
    "command": "echo 'About to write code'"
  },
  "post_write_code": {
    "type": "shell",
    "command": "black {file}"
  },
  "on_error": {
    "type": "python",
    "module": "my_hooks",
    "function": "log_error"
  }
}
```

## Available Hook Events

| Event             | Trigger                       |
| ----------------- | ----------------------------- |
| `pre_write_code`  | Before writing code to a file |
| `post_write_code` | After writing code to a file  |
| `pre_execute`     | Before executing a command    |
| `post_execute`    | After executing a command     |
| `on_error`        | When an error occurs          |
| `on_complete`     | When a task completes         |

## Hook Types

### Shell Hooks

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "post_write_code": {
    "type": "shell",
    "command": "black {file} && isort {file}"
  }
}
```

### Python Hooks

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "on_error": {
    "type": "python",
    "module": "my_hooks",
    "function": "handle_error"
  }
}
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# my_hooks.py
def handle_error(context):
    print(f"Error in {context['file']}: {context['error']}")
```

## How It Works

1. **Load**: Hooks are loaded from `.praison/hooks.json`
2. **Register**: Hooks are registered for specific events
3. **Trigger**: Events trigger corresponding hooks
4. **Execute**: Hook commands/functions are executed with context

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    A[Event Occurs] --> B{Hook Registered?}
    B -->|Yes| C[Execute Hook]
    B -->|No| D[Continue]
    C --> E{Shell or Python?}
    E -->|Shell| F[Run Command]
    E -->|Python| G[Call Function]
    F --> D
    G --> D
```

## Context Variables

Hooks receive context variables that can be used in commands:

| Variable    | Description                   |
| ----------- | ----------------------------- |
| `{file}`    | File path being processed     |
| `{content}` | Content being written         |
| `{error}`   | Error message (for on\_error) |
| `{result}`  | Result of operation           |

## Examples

### Code Formatting Hook

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "post_write_code": {
    "type": "shell",
    "command": "black {file} && isort {file}"
  }
}
```

### Linting Hook

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "pre_write_code": {
    "type": "shell",
    "command": "pylint {file} --errors-only"
  }
}
```

### Error Logging Hook

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "on_error": {
    "type": "python",
    "module": "monitoring",
    "function": "send_alert"
  }
}
```

## Programmatic Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import HooksManager

hooks = HooksManager()

# Register Python hooks
hooks.register("pre_write_code", lambda ctx: print(f"Writing {ctx['file']}"))

# Execute hooks
result = hooks.execute("pre_write_code", {"file": "main.py"})
```

## Best Practices

<Tip>
  Use hooks for consistent code formatting and validation across your project.
</Tip>

<Warning>
  Hooks add execution time. Keep hook commands fast to avoid slowing down agent operations.
</Warning>

| Do                             | Don't                          |
| ------------------------------ | ------------------------------ |
| Keep hooks fast and focused    | Run long-running processes     |
| Use for formatting and linting | Use for complex business logic |
| Log errors for debugging       | Silently ignore failures       |
| Test hooks independently       | Deploy untested hooks          |

## Related

* [Hooks Feature](/features/hooks)
* [Rules CLI](/cli/rules)
* [Workflow CLI](/cli/workflow)