> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckbrain.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# hooks

> Trigger a sync at Claude Code session boundaries (SessionEnd, PreCompact)

```bash theme={null}
duckbrain hooks install                                  # SessionEnd + PreCompact, 15m debounce
duckbrain hooks install --events SessionEnd --debounce 30m
duckbrain hooks install --dry-run                        # print the resulting hooks JSON, write nothing
duckbrain hooks off                                      # remove duckbrain hooks
```

Adds a command hook to `~/.claude/settings.json` so every Claude Code session that ends (or compacts) kicks off a sync — your session history lands in the brain without a fixed timer. Applies to sessions started after install.

## The hook discipline

Hooks that do real work inside the agent loop are how memory tools make sessions feel slow. DuckBrain's hook is designed to be invisible:

* **Session boundaries only** — `SessionEnd` and `PreCompact` by default, never per-message events.
* **Fire-and-forget** — the hook command is backgrounded (`nohup … &`) and exits immediately, so Claude Code never waits on it.
* **Debounced** — the sync runs with `--debounce 15m`: if a sync completed in the last 15 minutes, it exits instantly. Ten sessions ending in an hour cost \~4 real syncs, not ten.
* **Single-flight** — `sync` holds a pid lock, so a hook firing while a scheduled sync is mid-run no-ops instead of racing.

The installed command looks like:

```
nohup ~/.bun/bin/duckbrain sync --debounce 15m </dev/null >/dev/null 2>&1 &
```

## With scheduling

Hooks and a [schedule](/commands/schedule) compose: the schedule guarantees a floor (data is never older than the interval), hooks make fresh session data land right away. The debounce + lock make it safe to run both.

## Uninstall

`duckbrain hooks off` removes every hook entry containing `duckbrain sync` from `~/.claude/settings.json` and leaves everything else untouched.