Hooks - EnConvo Documentation

Overview

Hooks let you run a shell command or send an HTTP request when something happens inside EnConvo, such as an agent starting, completing, failing, or using a tool. They are configured with a JSON file, so you can add notifications, logs, local automation, or integrations without building an extension.

Hooks are fire-and-forget. They run in the background and do not block EnConvo.

Config File

Create your hooks config at:

~/.enconvo/hooks.json

EnConvo also reads the legacy file at ~/.config/enconvo/hooks.json when the new file does not exist. If both files exist, ~/.enconvo/hooks.json wins. The file is checked again whenever an event fires, so you can edit hooks while EnConvo is running. No restart is required.

Manage Hooks in Settings

Open Settings → Hooks to inspect hooks from ~/.enconvo/hooks.json. The settings panel groups entries by event, lets you toggle an entry on or off, and can open the JSON file for editing. Toggling writes enabled: false or enabled: true on that hook entry without changing the command or webhook definition.

Quick Start

Create the hooks folder

mkdir -p ~/.enconvo

Create ~/.enconvo/hooks.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Agent status changed' >> /tmp/enconvo-hooks.log"
          }
        ]
      }
    ]
  }
}

Trigger an agent

Start any agent or chat command. When its status changes, EnConvo runs the configured command and appends a line to /tmp/enconvo-hooks.log.

How Hooks Work

When an event fires, EnConvo:

Loads ~/.enconvo/hooks.json.
Falls back to ~/.config/enconvo/hooks.json only if the new file is absent.
Finds entries inside the top-level hooks object whose key matches the event name.
Applies the optional matcher regex.
Skips entries where enabled is false.
Runs every configured hook concurrently.

Hook event names follow the Codex lifecycle set: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, and Stop. The old EnConvo event names and old flat JSON shape are still readable for existing installs, but new writes use the wrapped Codex-style format.

Configuration Reference

{
  "hooks": {
    "event_name": [
      {
        "matcher": "optional_regex_filter",
        "enabled": true,
        "hooks": [
          { "type": "command", "command": "..." },
          { "type": "http", "url": "..." }
        ]
      }
    ]
  }
}

Field	Type	Required	Description
`hooks`	object	Yes	Event map keyed by event name.
`event_name`	string	Yes	Event to listen for. Use this as a key inside `hooks`.
`matcher`	string	No	Regex filter. For tool events, it matches `toolName`, `toolTitle`, or `path`; for other events, it matches the hook event name.
`enabled`	boolean	No	Set to `false` to keep the entry in config but skip execution. Defaults to `true`.
`hooks`	array	Yes	Command and HTTP hooks to execute.

Command Hook

A command hook runs a shell command. EnConvo writes the event payload to the command’s stdin as JSON.

{
  "type": "command",
  "command": "bash ~/.enconvo/hooks/on-status-change.sh",
  "timeout": 30000
}

Field	Type	Default	Description
`type`	`"command"`	-	Required hook type.
`command`	string	-	Shell command to execute.
`timeout`	number	`30000`	Timeout in milliseconds.

HTTP Hook

An HTTP hook sends the event payload as the JSON request body.

{
  "type": "http",
  "url": "https://example.com/webhook",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-token"
  },
  "timeout": 30000
}

Field	Type	Default	Description
`type`	`"http"`	-	Required hook type.
`url`	string	-	HTTP endpoint URL.
`method`	string	`"POST"`	HTTP method.
`headers`	object	`{}`	Additional request headers.
`timeout`	number	`30000`	Timeout in milliseconds.

Event Payload

Command hooks receive this JSON on stdin. HTTP hooks receive the same JSON as the request body.

{
  "event": "UserPromptSubmit",
  "fullEvent": "event-UserPromptSubmit",
  "sourceEvent": "run_status_changed",
  "sourceFullEvent": "event-run_status_changed",
  "params": {
    "commandKey": "agent|main",
    "runStatus": "running"
  },
  "timestamp": 1742313600000
}

Field	Description
`event`	Short event name.
`fullEvent`	Internal event name with the `event-` prefix.
`sourceEvent`	Original EnConvo event that produced this hook event, when the event is mapped for Codex compatibility.
`sourceFullEvent`	Original internal event name with the `event-` prefix.
`params`	Event-specific payload.
`timestamp`	Unix timestamp in milliseconds.

Available Events

Event	Params	When
`SessionStart`	`{ command, commandKey }`	A new chat session is created.
`UserPromptSubmit`	`{ commandKey, runStatus, status?, sessionId? }`	An agent, chat, or bot run starts from user input.
`PreToolUse`	`{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }`	A tool call starts.
`PermissionRequest`	`{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }`	A tool call reaches a permission or denied state.
`PostToolUse`	`{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }`	A tool call succeeds, fails, completes, or is denied.
`Stop`	`{ commandKey, runStatus, status?, sessionId? }`	An agent, chat, or bot run reaches a terminal status.

Legacy EnConvo names such as run_status_changed and agent_tool_step_changed still work, so existing hook files do not need to be migrated immediately.

Recipes

macOS Notification on Agent Failure

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "STATUS=$(cat | jq -r '.params.runStatus // .params.status') && [ \"$STATUS\" = \"failed\" ] && osascript -e 'display notification \"An agent failed\" with title \"EnConvo\"'"
          }
        ]
      }
    ]
  }
}

Log Agent Status Changes

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: (.timestamp / 1000 | strftime(\"%Y-%m-%d %H:%M:%S\")), agent: .params.commandKey, status: (.params.runStatus // .params.status)}' >> ~/.enconvo/agent-status.log"
          }
        ]
      }
    ]
  }
}

Log Agent Tool Calls

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.params | \"\\(.status) \\(.toolName) \\(.toolCallId)\"' >> ~/.enconvo/agent-tools.log"
          }
        ]
      }
    ]
  }
}

Send to Slack

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
          }
        ]
      }
    ]
  }
}

Custom Script

Create a script that reads the event payload from stdin:

#!/bin/bash
# ~/.enconvo/hooks/on-status-change.sh
INPUT=$(cat)
STATUS=$(echo "$INPUT" | jq -r '.params.runStatus // .params.status')
AGENT=$(echo "$INPUT" | jq -r '.params.commandKey')

echo "[$(date)] $AGENT -> $STATUS" >> /tmp/enconvo-hooks.log

if [ "$STATUS" = "failed" ]; then
  osascript -e "display notification \"$AGENT failed\" with title \"EnConvo\""
fi

Reference it from ~/.enconvo/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.enconvo/hooks/on-status-change.sh"
          }
        ]
      }
    ]
  }
}

Make the script executable:

chmod +x ~/.enconvo/hooks/on-status-change.sh

Troubleshooting

My hook did not run

Confirm that ~/.enconvo/hooks.json is valid JSON, the top-level key matches the event name, and the command works when run manually. If you still have ~/.config/enconvo/hooks.json, remember that it is ignored when the new file exists.

How do I test a script manually?

Pipe a sample payload into the script:

echo '{"event":"Stop","params":{"commandKey":"agent|main","runStatus":"failed"},"timestamp":1742313600000}' | bash ~/.enconvo/hooks/on-status-change.sh

Do hooks block EnConvo?

No. Hooks are fire-and-forget. If a hook fails or times out, EnConvo logs the failure and continues processing the original event.

Should commands use absolute paths?

Prefer absolute paths for scripts and binaries. Shell ~ expansion works when the command is executed through a shell, but absolute paths are easier to debug.

Agents

Learn about EnConvo agents and custom bots

Extension API Reference

Build extensions that emit or listen to events

​Overview

​Config File

​Manage Hooks in Settings

​Quick Start

​How Hooks Work

​Configuration Reference

​Command Hook

​HTTP Hook

​Event Payload

​Available Events

​Recipes

​macOS Notification on Agent Failure

​Log Agent Status Changes

​Log Agent Tool Calls

​Send to Slack

​Custom Script

​Troubleshooting

Agents

Extension API Reference

Overview

Config File

Manage Hooks in Settings

Quick Start

How Hooks Work

Configuration Reference

Command Hook

HTTP Hook

Event Payload

Available Events

Recipes

macOS Notification on Agent Failure

Log Agent Status Changes

Log Agent Tool Calls

Send to Slack

Custom Script

Troubleshooting