/background-watch-hook

name: background-watch-hook
slug: background-watch-hook
description: Use `vibe watch` to run a managed Harness waiter that returns to the same conversation later. Best for reviews, CI, files, logs, and other wait-now-continue-later workflows.
version: 0.11.7

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 waiter example for one common case: GitHub PR review activity.

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

Management commands:

• `vibe watch list`
• `vibe watch show <watch-id>`
• `vibe watch update <watch-id> --name '...'`
• `vibe watch pause <watch-id>`
• `vibe watch resume <watch-id>`
• `vibe watch remove <watch-id>` hides the watch while keeping prior run history

Waiter Contract

Write waiters to follow this contract:

• `exit 0`: event detected; final summary printed to `stdout`
• `exit 64` **plus the line `avibe-watch: no-event` on `stderr`**: cycle completed with nothing worth reporting; **no follow-up Agent Run**, the watch ends (`once`) or re-arms (`--forever`)
• `exit 124`: timeout; still send a timeout follow-up
• other non-zero: failure; the watch stops and sends a failure follow-up

Exit 64 is the token-saving path. Every other terminal exit costs one Agent turn, so a waiter whose normal outcome is uninteresting — green CI, review chatter that was filtered out — should end on 64 rather than reporting "nothing to do". It is a clean ending, so a `once` watch that retires on 64 reads as completed rather than failed, and whatever the waiter wrote to `stderr` is logged beside the watch id.

The marker is not optional. 64 is also BSD `sysexits` EX_USAGE, so a watched command that rejects its own arguments exits with it — and it must keep failing loudly rather than being read as a quiet cycle and, in `--forever`, rerun indefinitely. A bare 64 is therefore treated as a failure; only 64 with the marker is a no-event cycle. In the bundled waiters, `_github_wait_common.no_event("<summary>")` prints the summary and the marker to `stderr` and returns the code, so `return no_event(...)` is the only place the contract has to be spelled out.

Keep the output split clean:

• `stdout`: final summary for the next turn
• `stderr`: polling logs and diagnostics

Generic Examples

Delay:

vibe watch add \
  --name "Delay follow-up" \
  --message "The delayed check completed. Continue from the result below." \
  -- \
  bash -lc 'sleep 120; echo "Timer finished after 120 seconds."'

File appears:

vibe watch add \
  --name "Wait for export file" \
  --message "The export file is ready. Inspect it and continue." \
  -- \
  bash -lc 'while [ ! -f /tmp/export.json ]; do sleep 10; done; echo "Detected /tmp/export.json"'

Log match:

vibe watch add \
  --name "Watch app log" \
  --message "The expected log pattern appeared. Inspect the event and continue." \
  --forever \
  -- \
  bash -lc 'tail -Fn0 /tmp/app.log | while read -r line; do case "$line" in *READY*) echo "$line"; break;; esac; done'

Session Targeting

Use the current Avibe context:

• Inside an Avibe-injected Agent shell, omitting the target continues this conversation.
• Use `--session-id <id>` only when the follow-up should continue a different existing Agent Session.
• Use `--create-session --same-scope` when follow-ups should run in one visible sibling Session under the same Workbench project or IM scope.
• For `--forever` watches that need a separate visible Session for each event, use `--create-session-per-run --same-scope`.
• Use `--create-session --scope-id <scopes.id>` when follow-ups should run in one Session under a specific existing scope.
• For separate visible Sessions in a specific existing scope, use `--create-session-per-run --scope-id <scopes.id>`.
• If `--cwd` is omitted while creating