gh-delta

imagenpm version imageCI

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.

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

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