Skip to main content
Hooks let a config wrap sync with local commands. Common uses are snapshotting dotfiles before a sync, refreshing a checked-out docs repo afterwards, or rebuilding files generated from synced content.

​
Basic shape

Hooks use exec form: command plus args. There is no shell, so pipes, redirects, and globs are not interpreted. Put shell logic in a script and call that script.

​
Order

  1. gaal builds the sync plan.
  2. pre-sync hooks run in order.
  3. Sync applies repositories, skills, content, and MCPs.
  4. --prune runs, when requested.
  5. gaal prints the sync summary.
  6. post-sync hooks run in order.
post-sync only runs after a successful sync. It is skipped when planning, sync, or prune fails.

​
Platform filters

Use os: to restrict a hook to linux, darwin, or windows.

​
Environment

Every hook sees GAAL_HOOK_PHASE, GAAL_HAS_CHANGES, GAAL_HAS_ERRORS, and newline-separated lists of planned or changed resources. See Schema: hooks for the full list.

​
Dry-run

gaal sync --dry-run shows hooks in the plan but never executes them.

​
Service mode

In service mode, hooks run on every iteration. A failing pre-sync hook skips that iteration. A failing post-sync hook is logged and the loop continues.

Schema: hooks

gaal sync