gh-delta

gh-delta is a deterministic, one-shot GitHub pull-request and issue detector for schedulers, scripts, and agent loops. It compares a current observation to a local snapshot, emits deltas, and leaves the next action to its caller. It is not a dashboard, inbox, bot, or scheduler.

A common one-minute PR loop lets the terminal history scroll naturally through the baseline, PR creation, CI starting, a failed job, a corrective push, green CI, and a final quiet tick that does not replay the change.

Contents

• Try it live
• Install
• Quick start
• Output formats
• What an agent usually does
• One agent pattern
• Strict watch lists
• Docs
• License

Try it live

Pick the most recently updated open PR with pending CI in a high-activity public repository, then poll only that PR once a minute:

REPO=NousResearch/hermes-agent
DEMO_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/gh-delta-live-demo"
WATCH_DIR="$DEMO_DIR/watch"
# Pick the most recently updated open PR with pending CI.
PR=$(gh search prs --repo "$REPO" --state open --checks pending \
  --sort updated --order desc --limit 1 \
  --json number --jq '.[0].number')

# Save the target locally once; watch add does not query GitHub.
# The loop reuses it to check one PR instead of scanning the whole repository.
npx gh-delta watch add "pr:$PR" \
  --repo "$REPO" \
  --watch-dir "$WATCH_DIR" \
  --until closed \
  --format text

# Check every 60 seconds; the first check establishes the baseline.
while true; do
  npx gh-delta \
    --repo "$REPO" \
    --monitor-id live-demo-60s \
    --state-dir "$DEMO_DIR" \
    --watch-dir "$WATCH_DIR" \
    --entities pr \
    --format text
  sleep 60
done
# Press Ctrl-C to stop.

The first tick is the baseline. Later ticks report changes to that one PR. Quiet ticks are normal. This demo still spends shared GraphQL quota.

gh-delta watch add pr:3 --until merged --watch-dir ./watch \
  --label thread=t-0004 --label package=F001-P05

Labels and watch sync: usage.

Install

Node 22+ and authenticated GitHub CLI access are required.

# npm binary
npm install --global gh-delta

# GitHub CLI extension
gh extension install diegomarino/gh-delta
gh delta --version

# agent skill (interactive)
npx skills add diegomarino/gh-delta --skill gh-delta

# or install globally for Codex without prompts, then verify
npx skills add diegomarino/gh-delta --skill gh-delta --agent codex --global --yes
npx skills list --global --agent codex

For a one-off run, use npx gh-delta. The skill is guidance only: it does not authorize GitHub mutations.

Quick start

In a GitHub checkout, create durable local monitor state and take a first tick:

gh-delta init
gh-delta --format compact

init writes a non-overwriting .gh-delta.json after a baseline. Later ticks reuse that identity. A first run exits 0; a changed run exits 10; exit 1 is retryable; exit 2 needs configuration or snapshot repair. JSON is always the default. Use --format compact for agents, text for logs, or template for per-delta lines.

The quick demo below shows the initial baseline followed by a later compact JSON report after GitHub state changes:

Output formats

The same observed change has four representations. Click any preview for the full-size generated output.

Agent context	Streaming consumers
compact: bounded summary and semantic changes	ndjson: one delta per line plus an end record
Full integration contract	Operator log
json: complete fingerprints and optional detail	text: concise human-readable actions

Generated contract schemas are available offline through gh-delta schema --format compact|ndjson|json.

Quiet NDJSON ticks: --omit-end (usage).

What an agent usually does

Class	Meaning	Usual agent response
new, first-seen	New or newly observed work	Inspect and queue the item; do not assume ownership.
ci-changed	CI state changed	Green: inspect review/merge state. Failed: relay the failing check.
review-changed, review-requests-changed	Review decision or audience changed	Notify the right reviewer or return requested changes to the worker.
head-changed, base-changed	Code or target base changed	Re-check CI and reviews before trusting earlier approval.
merged, closed, reopened	Lifecycle changed	Verify it, then propose branch/work-queue follow-up.
new-comments, review-comments-added, unresolved-threads-added	New discussion needs attention	Read the discussion before merge or dispatch. new-comments is conversation-only; review-comments-added is inline review replies.
became-mergeable, became-conflicting	Mergeability changed	Inspect protections/conflicts; never merge only because CI is green.
stale	No meaningful change for a period	Send one bounded reminder to the current owner/reviewer.
missing, presumed-deleted, reappeared	Observation continuity changed	Check scope/permissions; only treat the terminal class as gone.
updated, relabeled, assignees-changed	Other meaningful metadata changed	Reassess routing and inspect GitHub when the delta lacks enough detail.

The contract is canonical for class semantics, exit codes, schemas, snapshots, and every flag.

One agent pattern

Wait for a PR’s CI without polling from an LLM turn:

PR_NUMBER=42
gh-delta wait --repo owner/repo --monitor-id worker-42 \
  --state-dir "${XDG_STATE_HOME:-$HOME/.local/state}/gh-delta/snapshots" --entities pr --timeout 30m \
  --number "$PR_NUMBER" \
  --until-summary ciRollup=green,failed

On exit 10, inspect the JSON reason (until or already-satisfied) and the PR before proposing a next action. See the runnable, network-free agent worker example and the fan-out coordinator for one-fetch, many-worker operation.

Strict watch lists

gh-delta --repo owner/repo --monitor-id scheduled --entities pr \
  --state-dir ./state --watch-dir ./watch --watch-strict \
  --rate-limit-floor 100 --format ndjson

Also --entities issue and pr,issue. Usage.

Docs

Documentation map.

• Usage: installation variants, state identity, watch/outpost operation, and programmatic use.
• Recipes: ten copyable situation → command → response flows.
• Troubleshooting: auth, snapshots, logs, and errors.
• Examples: deterministic local example smokes and integration shapes.
• Agent watch-loop prompt: scheduler-owned loop.
• Architecture and release checklist: maintainers.

The official GitHub Action and Homebrew tap are external publication work; this repository ships only the safe local integration shapes until those artifacts exist.

License

MIT