prhub 0.1.0__tar.gz

prhub-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.coverage
+coverage.xml
+.ruff_cache/

prhub-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to prhub are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/),
+and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-11
+
+First public release.
+
+### Added
+
+- `prhub daemon`: one poller per machine. One batched GraphQL request a minute reads every tracked PR and watched
+  commit; a discovery search finds your open PRs every few minutes. It slows down when the GitHub budget runs low
+  and waits for the reset when rate-limited.
+- `prhub wait` for PRs with `done`, `green`, `checks`, `merged`, `closed`, `review` and `change`. `done` requires an
+  APPROVED review of the current head that is newer than the head commit.
+- `prhub wait` for commits (`owner/repo@sha`) with `checks`, `green`, `deployed` and `change`, plus `--env` and
+  `--workflow`. `deployed` reads GitHub Deployments and `deployed/<env>` statuses, and counts a later deploy that
+  contains the commit.
+- `prhub state`, `prhub list` (`--ready`, `--all`, `--json`), `prhub watch` / `unwatch` and `prhub status`, which
+  says `PAUSED` during a GitHub rate limit.
+- `prhub hook claude`: a Claude Code `PreToolUse` hook that refuses GitHub polling loops and points to `prhub wait`.
+- `prhub install-launchd` (macOS) and `prhub install-systemd` (Linux) to run the daemon as a service.
+- Names for PRs and commits: URLs, `owner/repo#N`, `owner/repo@sha`, nicknames from the config and local clones,
+  and bare numbers or `@sha` inside a clone.

prhub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Naves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prhub-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: prhub
+Version: 0.1.0
+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)

prhub-0.1.0/README.md

@@ -0,0 +1,221 @@
+# 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)

prhub-0.1.0/prhub/__init__.py

@@ -0,0 +1,2 @@
+"""prhub: one GitHub poller for many coding agents."""
+__version__ = "0.1.0"

prhub-0.1.0/prhub/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())