Metadata-Version: 2.5
Name: prhub
Version: 0.1.1
Summary: One GitHub poller for many coding agents: they wait on local PR and deploy state instead of each polling the API
Project-URL: Homepage, https://github.com/danielnc/prhub
Project-URL: Documentation, https://github.com/danielnc/prhub#readme
Project-URL: Repository, https://github.com/danielnc/prhub
Project-URL: Issues, https://github.com/danielnc/prhub/issues
Project-URL: Changelog, https://github.com/danielnc/prhub/blob/main/CHANGELOG.md
Author: prhub contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ci,claude-code,cli,codex,coding-agents,deployments,github,pull-requests,rate-limit
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# prhub

**One GitHub poller for many coding agents.**

[![CI](https://github.com/danielnc/prhub/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/danielnc/prhub/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/danielnc/prhub/badge)](https://scorecard.dev/viewer/?uri=github.com/danielnc/prhub)
[![PyPI](https://img.shields.io/pypi/v/prhub)](https://pypi.org/project/prhub/)
[![Python versions](https://img.shields.io/pypi/pyversions/prhub)](https://pypi.org/project/prhub/)
[![Codecov](https://codecov.io/gh/danielnc/prhub/graph/badge.svg)](https://codecov.io/gh/danielnc/prhub)
[![CodeRabbit reviews](https://img.shields.io/coderabbit/prs/github/danielnc/prhub?label=CodeRabbit%20reviews)](https://coderabbit.ai)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Coding agents (Claude Code, Codex, Cursor, …) spend a lot of their time waiting: for CI on the PR they just pushed,
for a review, for a merge, for the deploy. Left alone, each one waits the same way, with its own polling loop:

```sh
gh pr checks 2814 --watch
until gh pr view 2814 --json state | grep -q MERGED; do sleep 30; done
gh run watch 123456
```

Every one of those loops spends the same budget: the **5,000 requests per hour** of the one GitHub token they all
share. With a dozen agents the budget is gone within the hour, and then *every* `gh` command fails for everyone,
you included, until it resets. On the author's machine, a single agent's monitoring loop once made about 190
GraphQL calls a minute and emptied the shared budget in under half an hour.

prhub replaces all of those loops with **one daemon per machine**. Once a minute it reads every PR and commit
anyone is waiting on in a single batched GraphQL request, and writes the state to local files. Agents block on
those files with `prhub wait`, which never calls GitHub.

```sh
prhub wait api#2814 --until done                  # open, approved at the current head, CI green, mergeable
prhub wait api#2814 --until checks --timeout 1800 # CI finished, whatever the result
prhub wait acme/api@3a1e48e --until deployed      # this commit is live in production
prhub state https://github.com/acme/api/pull/42   # current state, instantly
prhub list --ready                                # your PRs that are ready to merge, right now
prhub status                                      # daemon health and the GitHub budget left
```

## How it works

```
                 ┌──────────────── one machine ────────────────┐
  GitHub API ◄── │ prhub daemon ──► ~/.local/state/prhub/*.json │ ◄── prhub wait / state / list
  (1 batched     │   every 60 s                                 │     (any number of agents,
   query/min)    └──────────────────────────────────────────────┘      no API calls)
```

- **Discovery.** Every few minutes the daemon runs one search for your open PRs (`is:pr is:open author:@me`, or
  your own query), so agents don't have to register anything.
- **Polling.** Every minute, one GraphQL request reads every tracked PR (40 per request) and every watched commit,
  together with each repo's recent deployments. With 30 to 40 open PRs that costs about 1 point per poll on the
  author's machine, roughly 60 to 120 points an hour, however many agents are waiting.
- **Waiting.** `prhub wait` tracks whatever it is asked about, nudges the daemon for an early poll (at most one
  every 15 s), then reads local files until the condition holds. Only data fetched *after* the wait started is
  judged, so a stale file never ends a wait.
- **Backing off.** Below 1,000 points left the daemon slows to every 3 minutes, below 300 to every 10, and when
  GitHub rate-limits it, it waits for the reset. During a rate limit `prhub status` says `PAUSED`, and waits keep
  waiting rather than failing, so agents don't fall back to polling by hand against the same exhausted limit.

## Install

Requires Python 3.11+ and the [GitHub CLI](https://cli.github.com), logged in (`gh auth login`). prhub reads the
token from `gh auth token` on every poll, never stores it, and has no other dependencies.

```sh
uv tool install prhub            # or: pipx install prhub
prhub install-launchd            # macOS: run the daemon at login
prhub install-systemd            # Linux: run it as a systemd user service
prhub status                     # "daemon: healthy" within a minute
```

To try it without installing a service, run `prhub daemon` in a terminal. Uninstall: on macOS,
`launchctl bootout gui/$(id -u)/dev.prhub.daemon` and delete `~/Library/LaunchAgents/dev.prhub.daemon.plist`; on
Linux, `systemctl --user disable --now prhub` and delete `~/.config/systemd/user/prhub.service`.

## Pull requests

`prhub wait <pr> --until <condition>[,<condition>…]` returns as soon as any one condition holds.

| condition | met when |
|---|---|
| `done` | open, not a draft, CI SUCCESS, merge state CLEAN (configurable), and an APPROVED review **of the current head** that is newer than the head commit |
| `green` | the CI rollup is SUCCESS |
| `checks` | CI finished, whatever the result |
| `merged` | the PR was merged |
| `closed` | the PR was merged or closed |
| `review` | a new review arrived after the wait started |
| `change` | anything relevant changed: state, draft, CI, review, merge state, head commit |

`done` deliberately does not trust GitHub's `reviewDecision` alone: it stays APPROVED after a new push unless the
repository dismisses stale reviews, and a force-push with an unchanged patch relabels an old review onto the new
head. `prhub state` marks such a PR `review=APPROVED(stale: no approval of this head)`.

When CI goes red, `state` and `wait` also print the names of the failing checks.

## Commits: CI and deploys

The same daemon watches commits, in any repository, so agents stop polling `gh run watch` and the Actions API.

```sh
prhub wait acme/api@3a1e48e --until green                      # every CI run on the commit passed
prhub wait api@3a1e48e --until green --workflow deploy         # only runs whose name contains "deploy"
prhub wait https://github.com/acme/api/commit/3a1e48e --until deployed --env production
prhub state @3a1e48e                                           # a commit of the clone you are in
```

| condition | met when |
|---|---|
| `checks` | every run on the commit finished, whatever the result |
| `green` | every run passed (exits `3` as soon as one fails) |
| `deployed` | the commit is live in `--env` (default `production`, or `any`) |
| `change` | anything about the commit's runs or deploys changed |

It works the same whatever a repository's workflow names, default branch or release style:

- **CI** is every check suite that ran something on the commit. Suites from apps that never start a run (they sit
  QUEUED forever) and cron-triggered runs (they attach to whatever the branch head is) are left out. A run
  cancelled because a newer run of the same workflow replaced it is not a failure.
- **Deployed** reads [GitHub Deployments](https://docs.github.com/en/rest/deployments), plus commit statuses named
  like `deployed/<env>`. A successful deploy of a *later* commit counts when that commit contains yours (asked once
  per new deployment through the compare API), so nightly releases, batched deploys and a cancelled deploy followed
  by a newer one all answer correctly. If a repository records no Deployments, use
  `--until green --workflow <name of its deploy workflow>`.

A commit stays tracked for 6 hours after the last `state` or `wait` that asked about it.

## Naming things

| you type | means |
|---|---|
| `https://github.com/acme/api/pull/42`, `acme/api#42` | a PR |
| `42` | PR 42 of the clone in the current directory |
| `api #42`, `api#42` | a PR, by repo name or nickname (see below) |
| `https://github.com/acme/api/commit/3a1e48e`, `acme/api@3a1e48e` | a commit (7 to 40 hex characters) |
| `api@3a1e48e`, `@3a1e48e` | a commit, by nickname, or in the current clone |

Nicknames come from `[aliases]` in the config, and from the names of the git clones found under `clone_roots`.

## Exit codes

`0` the condition was met · `1` timed out · `2` bad arguments, or no such commit · `3` the condition can never be
met (the PR closed; for a commit, a run failed under `green` or its deploy failed) · `4` the daemon is not running.

## Agent setup

**Tell your agents.** Add something like this to your agents' instructions (`CLAUDE.md`, `AGENTS.md`, …); a
longer version is in [docs/agents.md](docs/agents.md):

```markdown
## Waiting on GitHub: use prhub, never poll
Every agent on this machine shares one GitHub token. To wait for a PR, CI or a deploy, run
`prhub wait <pr or owner/repo@sha> --until <condition>` (in the background if you need to keep working), and use
`prhub state <pr>` or `prhub list --ready` for the current state. These read local files and cost nothing.
Never loop over `gh pr checks`, `gh pr view`, `gh run watch` or `gh api` with `sleep`.
If `prhub status` says PAUSED, that is a GitHub rate limit: keep waiting, don't poll by hand.
```

**Enforce it (Claude Code).** `prhub hook claude` is a `PreToolUse` hook that refuses `gh pr checks --watch`,
`gh run watch`, `watch … gh …` and shell loops that `sleep` around `gh pr`, `gh run` or `gh api`, and tells the
agent which `prhub wait` to use instead. One-off reads and every write pass through untouched, and the hook stands
aside entirely when the daemon is not healthy. Add it to `~/.claude/settings.json`:

```json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash",
    "hooks": [ { "type": "command", "command": "prhub hook claude", "timeout": 5 } ] } ] } }
```

Put `PRHUB_ALLOW=1` anywhere in a command to let one loop through on purpose.

## Configuration

`~/.config/prhub/config.toml` (override the path with `PRHUB_CONFIG`). Every key is optional:

```toml
search = "is:pr is:open author:@me org:acme"  # what the daemon discovers by itself
interval = 60                                 # seconds between polls
discover_every = 180                          # seconds between discovery searches
clone_roots = ["~/code"]                      # clones under here become repo nicknames

[aliases]
api = "acme/api"                              # nickname -> owner/repo, or the name of a local clone
web = "acme/web-app"

[done]
merge_states = ["CLEAN", "HAS_HOOKS"]         # merge states that count as mergeable for `done`
```

Any PR or commit an agent waits on is tracked automatically, even if the search would not find it (someone else's
PR, another organization). Closed PRs drop out an hour after they close.

## Files

Everything lives in `~/.local/state/prhub` (override with `PRHUB_HOME`):

| path | what |
|---|---|
| `prs/<owner>__<repo>__<n>.json` | one record per PR: a summary plus the raw GraphQL fields |
| `commits/<owner>__<repo>__<sha>.json` | one record per watched commit |
| `watch.json`, `commit-watch.json` | what agents asked to track, and who asked (`PRHUB_CALLER`, else a tmux or Herdr pane id) |
| `events.jsonl` | every state change, one JSON line each |
| `daemon.json`, `daemon.log` | daemon health, the GitHub budget left, and the log |

Other tools can read these too. A dashboard, a merge queue or a status bar can use them without calling GitHub.

## Limits

- github.com only for now; GitHub Enterprise Server is not supported.
- One daemon per machine and per GitHub token. Agents on other machines need their own daemon.
- The state is up to one poll interval old (60 s by default). `prhub state --fresh` asks for a poll first.
- `done` checks the review decision, CI and merge state that GitHub reports. If your merge rules need more (a
  specific reviewer, resolved threads), check those before merging.

## Contributing

Bug reports and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues
privately, as described in [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)
