agentleFS
Sign inStart free
cyhhaocyhhao/vibe-remote/skills/background-watch-hook/SKILL.md

background-watch-hook

Skill638 starsChanged 7 days agoMITView on GitHub

Run durable `vibe watch` waits for PR reviews, CI, files or external signals, then resume the Agent in the right Session.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. avibe-bot/avibe★ 638100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository9 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 3 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use vibe watch for a durable wait that resumes an Agent when an external event arrives.

    line 10
  2. Very specific:

    Read vibe watch add --help before first use.

    line 28
  3. Distinctive:

    Remove the Watch at close-out.

    line 32
  4. Very specific:

    Use --session-id <id> only when resuming a different existing Agent Session.

    line 37
  5. Very specific:

    Use --create-session --same-scope for one visible sibling Session.

    line 38
  6. Very specific:

    Use --scope-id <scopes.id> instead of --same-scope for an explicit scope.

    line 40
  7. Very specific:

    If --cwd is omitted, Avibe uses the command's current working directory.

    line 41
  8. Very specific:

    Use --forever and one owner-specific state file for the whole loop.

    line 45
  9. Very specific:

    Keep this same Watch through queue validation.

    line 54
  10. Distinctive:

    Never reseed or replace its state between rounds.

    line 68
  11. Distinctive:

    Run scripts from the loaded Skill directory, not a guessed installation path:

    line 73
  12. Very specific:

    After confirming the seeded Watch is live, push or trigger review.

    line 95
  13. Very specific:

    Use wait_pr.py without CI arguments for PR-only activity.

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Background Watch Hook

Use vibe watch for a durable wait that resumes an Agent when an external event arrives. The waiter detects events; the follow-up Agent verifies live state and acts. A success candidate is not merge authorization.

Contract and lifecycle

Waiter exitMeaning
0One new reportable event; summary on stdout
75 (or configured retry code)Still waiting; no Agent turn
64 plus avibe-watch: no-event on stderrQuiet completed cycle: retire once, re-arm forever
124 or other terminal failureNotify the Agent and stop

A bare 64 is an error. Keep diagnostics on stderr. A once Watch waiting for its first event uses a retry code, not 64. Forever waiters need durable cursors or edge detection; a persistent true condition is not a new event. Avibe serializes follow-ups, re-arms after they settle, and pauses rapid repeated events for repair.

  • Read vibe watch add --help before first use; inspect/update with vibe watch <list|show|update|pause|resume|remove>.
  • --timeout bounds each cycle (default six hours); --lifetime-timeout bounds the whole Watch. Use 0 for an intentionally unbounded PR delivery loop.
  • Remove the Watch at close-out. Do not use detached shells for durable waits.

Session targeting

  • Inside an Avibe-injected Agent shell, omitting the target continues this conversation.
  • Use --session-id <id> only when resuming a different existing Agent Session.
  • Use --create-session --same-scope for one visible sibling Session; use --create-session-per-run --same-scope for a separate visible Session per event.
  • Use --scope-id <scopes.id> instead of --same-scope for an explicit scope.
  • If --cwd is omitted, Avibe uses the command's current working directory.

Preferred PR + CI watch

Use --forever and one owner-specific state file for the whole loop. Seed and arm before the watched push/review trigger; for a new PR, create it first, then immediately seed/arm. Keep the same Watch and cursor across all later rounds.

  • wait_pr.py --workflow <actual-name> combines PR activity with exact-head CI; repeat --workflow for every required workflow. Omit --sha to follow pushes.
  • Authenticated PR watches also report paginated merge-queue timeline events: enqueue, removal (with GitHub's reason), and MERGED (with merge commit/ref). These survive filters, success coalescing, and restart/delivery acknowledgement. Keep this same Watch through queue validation; PR-head CI is not merge-group CI. On removal, inspect the reason and associated queue run, then follow pr-delivery-loop recovery. Only MERGED readback permits close-out.
  • --coalesce-success: keep half-success quiet; report one same-head CI/review success candidate. Findings, errors and unfamiliar results remain reportable.
  • --actionable-only drops review triggers and empty envelopes; --settle 20 batches review bursts. New CI failures bypass settle. Final gates belong to pr-delivery-loop, including the stricter qualification of Codex reactions.
  • A Codex review of the current head that stays running for --review-stall-minutes (default 30, 0 disables) is reported as Codex review stalled, again each further window it lasts; the follow-up re-requests the review as pr-delivery-loop says.
  • Set --timeout 0 on both sides of the -- command separator; six quiet hours is not a PR failure. Verify workflow names: missing CI is never green.
  • Never reseed or replace its state between rounds. Filters/reporting modes are part of cursor ownership; enable them on the initial seed and armed command.
  • Cursor corruption, ownership conflicts or write failures require repair with evidence preserved, not a fresh baseline. Retryable GitHub failures keep waiting.

Run scripts from the loaded Skill directory, not a guessed installation path:

BACKGROUND_WATCH_HOOK_DIR="<directory containing the loaded SKILL.md>"
STATE_FILE="$HOME/.avibe/state/watch-cursors/pr-151-review.json"
BRANCH="$(gh pr view 151 --repo avibe-bot/avibe --json headRefName --jq .headRefName)"

uv run --no-project "$BACKGROUND_WATCH_HOOK_DIR/scripts/wait_pr.py" \
  --repo avibe-bot/avibe --pr 151 --branch "$BRANCH" \
  --workflow lint --coalesce-success --actionable-only \
  --state-file "$STATE_FILE" --seed-state

vibe watch add \
  --name "Watch PR 151 review and CI" --forever --timeout 0 \
  --message "PR #151 has an event. Follow pr-delivery-loop; verify live gates, handle findings/errors, and keep half-success silent." \
  -- \
  uv run --no-project "$BACKGROUND_WATCH_HOOK_DIR/scripts/wait_pr.py" \
    --repo avibe-bot/avibe --pr 151 --branch "$BRANCH" \
    --workflow lint --coalesce-success --actionable-only \
    --settle 20 --state-file "$STATE_FILE" --interval 60 --timeout 0

After confirming the seeded Watch is live, push or trigger review. Check exactly one live Watch per owner/PR/concern at each round's end. The state file stages reports until delivery acknowledgement, so an undelivered report may replay; never discard it merely to avoid a duplicate.

Other waits and troubleshooting

Use wait_pr.py without CI arguments for PR-only activity; use wait_action.py for standalone Actions and wait_issue.py for issues. Do not combine --new-prs with CI options. --catch-up and explicit cursors deliberately replay history, not routine re-arming. Keep Watch messages short and action-oriented; reference loaded policy rather than restating it on every fire.

Detailed waiter reference covers alternative commands, filters, replay, authentication, and cursor/settle internals. Read it only for those tasks or a concrete failure, not for routine PR monitoring.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free