Run commands with hooks

A hook runs your program after an agent publishes a signal or a workspace is created, closed, reopened, or deleted.

For example, send each review request to a notification service that accepts JSON webhooks.

Connect a review notification

First follow Publish agent updates to enable review.requested@1. For this example you also need curl and an HTTP endpoint that accepts CoCo’s event JSON.

Find the full executable path:

command -v curl
mkdir -p ~/.config/coco

Create ~/.config/coco/hooks.json. If it already exists, add the entry to its hooks array while preserving your other hooks and guards:

~/.config/coco/hooks.json

{
  "version": 1,
  "hooks": [
    {
      "id": "notify-review",
      "event": "signal.emitted",
      "signal": "review.requested@1",
      "command": [
        "/absolute/path/to/curl",
        "--fail", "--silent", "--show-error",
        "--header", "Content-Type: application/json",
        "--data-binary", "@-",
        "https://your-service.example/coco/review"
      ],
      "timeoutSeconds": 30,
      "maxAttempts": 3
    }
  ]
}

Replace the executable path and endpoint with your values. This sends the full event, including the workspace and signal payload, as the request body. Only use an endpoint you trust with those contents.

Load and check it

chmod 600 ~/.config/coco/hooks.json
coco hook validate
coco hook reload
coco hook list

After the agent emits a review request, your endpoint should receive it. Check the delivery result:

coco hook history

Changes to the file take effect after hook reload or a coordinator restart. An invalid reload leaves the previous configuration active.

Run your own program

Replace the command array with your executable and arguments. CoCo passes the event as JSON on standard input. Your program can use it to update another tool, record an artifact, or decide which follow-up action to take.

A command can receive the same event again after a failure or restart. Use the event’s id to avoid repeating external effects, such as creating the same ticket twice.

Hooks run as your user with only PATH inherited. Use absolute file paths, configure any required credentials explicitly, and keep commands in the foreground. Avoid actions that trigger the same hook repeatedly.

See Automation reference for event names, payloads, filters, retries, and configuration fields. To check an action before it happens, use a guard.

For prompt, tool, or permission events within Codex itself, configure Codex’s native hooks.