Hooks

Event-driven actions triggered during agent execution

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

This CLI and its HooksManager API are a standalone, opt-in utility. Configured hooks do NOT fire automatically inside an Agent — an event only occurs when your own code calls HooksManager.execute(). Agent and Task never call it. For hooks that fire automatically around an Agent’s tool/LLM calls, use the live praisonaiagents.hooks package instead. See Memory HooksManager for the standalone utility in depth.

Install requirement: praisonai hooks requires pip install praisonai (the full wrapper). On a standalone pip install praisonai-code install every hooks subcommand exits 1 with hooks requires the full wrapper. Install the full wrapper: pip install praisonai — a single-line hint, no Rich traceback (PR #2854).

Quick Start

# List configured hooks
praisonai hooks list

Usage

List Hooks

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

praisonai hooks stats

Initialize Hooks

praisonai hooks init

Creates a template .praisonai/hooks.json file.

The only Typer-registered actions are list, stats, and init. The underlying handler also accepts help. There is no add or remove subcommand — configure hooks by editing the file hooks init creates.

An unknown hooks action prints an error and exits non-zero (1). Earlier versions printed the error but returned 0, so shell scripts checking $? saw success. Update any script that relied on the old exit code.

Hooks Configuration

hooks init writes this template to .praisonai/hooks.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

Event	Trigger
pre_write_code / post_write_code	Around code writes
pre_run_command / post_run_command	Around command execution
pre_user_prompt / post_user_prompt	Around user prompt handling
pre_mcp_tool_use / post_mcp_tool_use	Around MCP tool calls

Hook Types

Shell Hooks

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

Python Hooks

{
  "pre_run_command": {
    "type": "python",
    "module": "my_hooks",
    "function": "validate_command"
  }
}

# my_hooks.py
def validate_command(context):
    print(f"Validating command: {context['command']}")

How It Works

The “event” below is triggered by whoever calls HooksManager.execute() — this page documents the CLI-facing utility and its programmatic API. Inside an Agent/Task run, nothing calls it. For hooks that fire automatically around an Agent’s tool/LLM calls, use /features/hooks.

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

Context Variables

Hooks receive context variables that can be used in commands:

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

Examples

Code Formatting Hook

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

Linting Hook

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

Command Validation Hook

{
  "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.

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"})

This is a standalone utility: its events fire only when you call .execute(). To gate an operation, put the .execute() call inside your own tool or wrapper. See Memory HooksManager for the full API, and Live Agent Hooks for hooks that fire automatically.

Best Practices

Use hooks for consistent code formatting and validation across your project.

Hooks add execution time. Keep hook commands fast to avoid slowing down agent operations.

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

• Memory HooksManager — the standalone utility this CLI wraps
• Live Agent Hooks — hooks that fire automatically around Agent tool/LLM calls
• Rules CLI
• Workflow CLI