@codex-control/hooks

Routes Codex hook events to a running codex-connector instance.

Validate Package (npx only)

npx -y @codex-control/hooks

The command above only validates the package resolution, prints runtime/package metadata (including version), and exits.

This package is intended to be used with npx and not installed globally.

Behavior

• Reads hook event JSON from stdin.
• Normalizes and trims payload fields.
• Sends one event to POST /api/hooks/events.
• Always returns {"continue": true} to stdout (fail-open).
• Supports auto-update usage when invoked as @latest in hook commands.

Environment

• CODEX_CONNECTOR_URL (default http://127.0.0.1:4311)
• CODEX_HOOKS_ENDPOINT (default /api/hooks/events)
• CODEX_CONNECTOR_TOKEN (optional bearer token)
• CODEX_HOOK_TIMEOUT_MS (default 4000)

Codex hooks.json example

{
  "hooks": {
    "SessionStart": [{ "command": "npx -y @codex-control/hooks@latest" }],
    "UserPromptSubmit": [{ "command": "npx -y @codex-control/hooks@latest" }],
    "PreToolUse": [{ "command": "npx -y @codex-control/hooks@latest" }],
    "PostToolUse": [{ "command": "npx -y @codex-control/hooks@latest" }],
    "PermissionRequest": [{ "command": "npx -y @codex-control/hooks@latest" }],
    "Stop": [{ "command": "npx -y @codex-control/hooks@latest" }]
  }
}

With token and custom endpoint:

CODEX_CONNECTOR_URL=http://127.0.0.1:4311 \
CODEX_CONNECTOR_TOKEN=your-token \
npx -y @codex-control/hooks@latest --endpoint /api/hooks/events --timeout-ms 5000