ox hooks

Manage event hooks triggered by daemon events such as session uploads, murmurs, and sync completions. Event hooks let you run custom commands when things happen in SageOx.

Usage

ox hooks list                    # List registered event hooks
ox hooks add <event> <command>   # Register a new event hook
ox hooks test <event>            # Fire a synthetic event to test hooks
ox hooks log                     # Show how to view hook execution logs

Subcommands

ox hooks list

List all registered event hooks.

ox hooks list

EVENT              COMMAND                           STATUS
session-upload     notify-send "Session uploaded"    enabled
murmur             ./scripts/on-murmur.sh            enabled
sync               echo "Sync complete"              enabled

ox hooks add

ox hooks add <event> <command>

Events:

session-upload — Triggered when a coding session is uploaded
murmur — Triggered when a murmur is received from a coworker
sync — Triggered when ledger or team context sync completes

Example:

# Desktop notification on session upload
ox hooks add session-upload 'notify-send "Session uploaded"'

# Run a script when a murmur arrives
ox hooks add murmur './scripts/handle-murmur.sh'

# Log sync completions
ox hooks add sync 'echo "$(date): sync complete" >> ~/.sageox/sync.log'

ox hooks test

Fire a synthetic event to test your hooks.

ox hooks test session-upload
ox hooks test murmur
ox hooks test sync

ox hooks log

Show how to view daemon hook execution logs.

ox hooks log

Git hooks

SageOx also installs git hooks for commit attribution. These are managed separately from event hooks:

Hook	Purpose
`prepare-commit-msg`	Adds Co-Authored-By and SageOx-Session trailers

Git hooks are installed automatically by ox integrate install and ox init.

To check git hook status:

ox integrate list

Hook execution

Hooks run asynchronously — they don't block the daemon
Hook output is logged to the daemon log
Failed hooks don't affect other hooks or daemon operation
Hooks receive event data via environment variables

Environment variables

Hooks receive context via environment variables:

Variable	Description
`SAGEOX_EVENT`	Event type (session-upload, murmur, sync)
`SAGEOX_TEAM_ID`	Team ID
`SAGEOX_REPO_ID`	Repository ID (if applicable)
`SAGEOX_AGENT_ID`	Agent ID (for murmur events)

ox integrate — Install AI agent hooks
ox daemon — Manage the background daemon

On this page