https://github.com/muneebhashone/gh-research
Deterministic CLI for AI agents to research GitHub Issues & Discussions - ranked, aggregated, JSON output.
https://github.com/muneebhashone/gh-research
ai-agents claude-code cli developer-tools github-api github-discussions github-issues llm-tools python research
Last synced: 11 days ago
JSON representation
Deterministic CLI for AI agents to research GitHub Issues & Discussions - ranked, aggregated, JSON output.
- Host: GitHub
- URL: https://github.com/muneebhashone/gh-research
- Owner: muneebhashone
- Created: 2026-05-23T18:44:28.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-23T19:19:28.000Z (about 1 month ago)
- Last Synced: 2026-05-23T20:23:56.479Z (about 1 month ago)
- Topics: ai-agents, claude-code, cli, developer-tools, github-api, github-discussions, github-issues, llm-tools, python, research
- Language: Python
- Size: 133 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# gh-research (`ghr`)
A CLI that conducts research over **GitHub Issues, Discussions, and repository
metadata** and returns AI-optimized JSON. It is a *deterministic data + analysis
engine* — it fetches, ranks, and aggregates (engagement/"hot" scoring, label
frequency, activity trends, pain-points, cross-repo aggregation) and leaves the
natural-language synthesis to the calling agent. Built for AI agents like Claude
Code, not humans, though it works fine for either.
It answers questions such as: *what repos are trending, what issues are people
commonly facing in a project (or a whole ecosystem), what are the hottest
discussions, is this project booming or dying, dig into project X.*
## Why not just use `gh`?
`gh` is built for humans and exposes raw endpoints. `ghr` adds an agent-friendly
contract on top: a two-tier command surface, deterministic ranking/aggregation
primitives, a uniform JSON envelope with machine-readable errors and exit codes,
safe result caps, a local response cache, and a [`SKILL.md`](./SKILL.md) that
teaches an agent how to drive it.
## Install
Clone the repo, then install it as a `uv` tool (this puts `ghr` on your PATH in an
isolated environment):
```bash
git clone https://github.com/muneebhashone/gh-research.git
cd gh-research
uv tool install .
ghr --help
```
To upgrade later, `git pull` and re-run `uv tool install . --reinstall`.
For development (run from the source tree without installing):
```bash
uv sync
uv run ghr --help
```
## Use it as an agent skill
This repo ships a [`SKILL.md`](./SKILL.md) that teaches an AI agent (Claude Code,
Cursor, etc.) how to drive `ghr`. Install it with [skills.sh](https://www.skills.sh):
```bash
npx skills add muneebhashone/gh-research
```
Useful flags: `--global` (install for all projects), `--agent '*'` (all detected
agents), `--list` (preview the skill without installing). The skill *uses* the
`ghr` CLI, so install the CLI too (see [Install](#install) above).
## Authentication
- REST features (issues, repos, search) work **unauthenticated** at low rate limits.
- **Discussions require a token** (GitHub's GraphQL API is auth-only).
- **Semantic issue search** (`issues search --search-type semantic|hybrid`) also requires
a token and has its own stricter 10 req/min limit. `semantic` ranks by meaning for
natural-language queries; `hybrid` blends semantic + keyword; omit it for classic lexical.
- Token resolution order: `--token` > `GH_TOKEN` > `GITHUB_TOKEN` > `gh auth token`
(if the GitHub CLI is installed and logged in) > stored config/keyring.
```bash
ghr auth status # shows whether a token is found, and its source (never the token)
ghr auth login --token # optional: store one (keyring if available, else config)
```
## Quickstart
```bash
ghr research digest cli/cli # one-call repo overview
ghr research trending --language python --days 30 # recently-popular repos (stars/day)
ghr research pain-points facebook/react # top-reacted open bug issues
ghr research hot-discussions vercel/next.js # client-ranked hottest discussions
ghr research activity cli/cli # booming vs dying
ghr research common-issues --topic cli --language go
ghr issues search --repo microsoft/vscode --label bug --sort reactions --limit 5
ghr issues search "auth fails on mobile" --repo cli/cli --search-type semantic # semantic index
ghr discussions list vercel/next.js --limit 10
ghr rate # rate-limit budgets
```
Global flags go **before** the subcommand, e.g. `ghr --jq '.data.repos[].full_name' research trending`.
## Output contract
Every command prints one JSON object:
```json
{ "ok": true, "data": { "...": "..." }, "error": null,
"meta": { "command": "...", "result_count": 8, "truncated": false,
"cache": {"hits": 0, "misses": 1},
"rate_limit": {"resource": "search", "remaining": 27, "limit": 30, "reset": 0} } }
```
Exit codes: `0` ok · `2` usage · `3` not-found · `4` auth-required · `5` rate-limited ·
`6` upstream · `7` partial/capped. See [`SKILL.md`](./SKILL.md) for the full agent guide.
## Safe caps & configuration
Sensible defaults (result limit 30, max 100/page, search auto-stops at the 1000-result
API cap, per-command request/time budgets) are all overridable via flags, `GHR_*`
environment variables, or a `config.toml` — precedence: **flag > env > config > default**.
## Development
```bash
uv run pytest # tests (HTTP mocked with respx; no network)
uv run ruff check # lint
uv run ruff format # format
uv run mypy src/ghr # types (strict)
```