Praison AI

Hooks

Event-driven actions triggered during agent execution

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

Quick Start

bash
# List configured hooks
praisonai hooks list
List event hooks example

Usage

List Hooks

bash
praisonai hooks list

Expected Output:

╭─ Configured Hooks ───────────────────────────────────────────────────────────╮
│  🪝 pre_write_code - Validate before writing code                           │
│  🪝 post_write_code - Format after writing code                             │
│  🪝 pre_run_command - Validate before running a command                     │
╰──────────────────────────────────────────────────────────────────────────────╯

When no hooks are configured, list prints an empty-state hint pointing at .praisonai/hooks.json.

Show Statistics

bash
praisonai hooks stats

Initialize Hooks

bash
praisonai hooks init

Creates a template .praisonai/hooks.json file.

Hooks Configuration

!Manage Event-Driven Hooks

hooks init writes this template to .praisonai/hooks.json:

json
{
  "enabled": true,
  "hooks": {
    "pre_write_code": [],
    "pre_run_command": [],
    "post_write_code": []
  },
  "settings": {
    "timeout_seconds": 30,
    "fail_on_error": false,
    "log_hook_output": true
  }
}

Available Hook Events

EventTrigger
pre_write_code / post_write_codeAround code writes
pre_run_command / post_run_commandAround command execution
pre_user_prompt / post_user_promptAround user prompt handling
pre_mcp_tool_use / post_mcp_tool_useAround MCP tool calls

Hook Types

Shell Hooks

json
{
  "post_write_code": {
    "type": "shell",
    "command": "black {file} && isort {file}"
  }
}

Python Hooks

json
{
  "pre_run_command": {
    "type": "python",
    "module": "my_hooks",
    "function": "validate_command"
  }
}
python
# my_hooks.py
def validate_command(context):
    print(f"Validating command: {context['command']}")

How It Works

  1. Load: Hooks are loaded from .praisonai/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
Diagram

Yes

No

Shell

Python

Event Occurs

Hook Registered?

Execute Hook

Continue

Shell or Python?

Run Command

Call Function

Context Variables

Hooks receive context variables that can be used in commands:

VariableDescription
{file}File path being processed
{content}Content being written
{command}Command being run
{result}Result of operation

Examples

Code Formatting Hook

json
{
  "post_write_code": {
    "type": "shell",
    "command": "black {file} && isort {file}"
  }
}

Linting Hook

json
{
  "pre_write_code": {
    "type": "shell",
    "command": "pylint {file} --errors-only"
  }
}

Command Validation Hook

json
{
  "pre_run_command": {
    "type": "python",
    "module": "monitoring",
    "function": "send_alert"
  }
}

Programmatic Usage

HooksManager is exported from praisonaiagents.memory, not the top-level package. The event fires only because your code calls .execute() — an Agent never does.

python
from praisonaiagents.memory import HooksManager

hooks = HooksManager(workspace_path=".")

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

# You trigger the event yourself
result = hooks.execute("pre_write_code", context={"file_path": "main.py"})

Best Practices

DoDon’t
Keep hooks fast and focusedRun long-running processes
Use for formatting and lintingUse for complex business logic
Log errors for debuggingSilently ignore failures
Test hooks independentlyDeploy untested hooks

Related