# ox hooks (https://sageox.ai/docs/cli/hooks)

# 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

```bash
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.

```bash
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

Register a new event hook.

```bash
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:**

```bash
# 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.

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

### ox hooks log

Show how to view daemon hook execution logs.

```bash
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:

```bash
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) |

## Related commands

- [ox integrate](/docs/cli/integrate): Install AI agent hooks
- [ox daemon](/docs/cli/daemon): Manage the background daemon