# ox hooks (/docs/cli/commands/hooks)



ox 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 [#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 [#subcommands]

ox hooks list [#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 [#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 [#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 [#ox-hooks-log]

Show how to view daemon hook execution logs.

```bash
ox hooks log
```

Git hooks [#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 [#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 [#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 [#related-commands]

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