background-watch-hook

Background Watch Hook

Use this skill when the job is "wait now, continue later in the same conversation".

What it gives the agent:

• a managed background task instead of manual polling
• a clean way to come back to the same channel or thread later
• a reusable pattern that works for reviews, CI, files, logs, and process completion

Good trigger scenarios:

• PR reviews or comments may arrive later
• CI, deployments, or exports need time to finish
• a file, log line, or process exit should wake the agent up later

Prefer vibe watch when the wait should be inspectable, pausable, resumable, or removable later.

Main Tools

• vibe watch add Main entrypoint. Starts a managed background watch and creates a follow-up Agent Run after the waiter succeeds or reaches a terminal failure.
• vibe watch list, vibe watch show, vibe watch update, vibe watch pause, vibe watch resume, vibe watch remove Use these to inspect and manage the watch after creation.
• scripts/wait_pr.py Bundled GitHub waiter for PR activity, with optional exact-head Actions monitoring.

Use vibe watch First

Use vibe watch add first. Most tasks only need:

1. a short action-oriented message
2. a blocking waiter command

Generic shape:

vibe watch add \
  --message "<what the next Agent Run should do>" \
  --name "<optional label>" \
  -- \
  <waiter command ...>

Default behavior:

• returns immediately
• keeps the waiter managed by Avibe
• lets the agent inspect or stop the watch later
• creates a follow-up Agent Run after the waiter succeeds or reaches a terminal failure

Use --forever when the same waiter should re-arm after each detected event instead of exiting after one follow-up.

vibe watch Parameters To Remember

• --message: the instruction template for the follow-up Agent Run created from waiter output
• --name: optional label for later management
• --session-id: only when the follow-up should continue a different explicit Agent Session
• --create-session --same-scope: create a visible sibling Session for the follow-up instead of continuing this conversation
• --create-session --scope-id <scopes.id>: create the follow-up Session in a specific existing scope
• --forever: re-arm after each detected event
• --timeout: per-cycle timeout
• --lifetime-timeout: whole-watch lifetime cap, mainly for forever watches