A hook is an automatic response that fires when something happens on a worktree or pull request — a failed check, a merge conflict, a new review comment — and hands it to an agent to deal with, without you. Hooks run in the background and are one of the main ways to keep work moving on its own. This article covers what hooks respond to, how they work, and where to set them up.
What hooks respond to
Hooks fire on worktree and pull-request events. The common ones include:
- Pre-commit failure — a commit is blocked by a failing check.
- PR checks failed (or finished with failures) — CI didn't pass.
- PR merge conflicts detected — the branch no longer merges cleanly.
- New PR review, or review with inline comments — someone left feedback to address.
- PR comments updated — a new comment needs a response.
- PR created, merged, or closed, and checks passed / finished — lifecycle events you can key off of.
How a hook works
When its event fires, a hook funnels the event to a chat and asks an agent to handle it — for example, "a pre-commit check failed, go fix it." Details about the event, such as the pull-request ID, are passed in as variables the agent can use, and the agent typically works through the GitHub CLI to investigate and make the fix.
Because hooks are always running in the background, common interruptions — a failed check, a merge conflict, a new comment — get picked up and worked automatically instead of waiting for you.
Where hooks are configured
Hooks are set up in workspace settings. In a multi-repo workspace you can scope them per repository, so different repos can respond differently. You can also pause hooks on a worktree when you want to work without them firing, and resume them later.
Hooks vs. watchers
It's easy to confuse the two, so keep the distinction clear:
- A hook is a durable rule that acts — it responds to an event by putting an agent to work.
- A watcher only notifies — it pings you when something you're watching finishes.
Next steps
- Watchers — get pinged when a job finishes, instead of acting automatically.
- Working in parallel — hooks are part of how you keep everything moving.
- App Advisor — set up automation in plain language.