{"id":50815832,"url":"https://github.com/muneebhashone/gh-research","last_synced_at":"2026-06-13T09:30:48.113Z","repository":{"id":359855117,"uuid":"1247763740","full_name":"muneebhashone/gh-research","owner":"muneebhashone","description":"Deterministic CLI for AI agents to research GitHub Issues \u0026 Discussions - ranked, aggregated, JSON output.","archived":false,"fork":false,"pushed_at":"2026-05-23T19:19:28.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T20:23:56.479Z","etag":null,"topics":["ai-agents","claude-code","cli","developer-tools","github-api","github-discussions","github-issues","llm-tools","python","research"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muneebhashone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T18:44:28.000Z","updated_at":"2026-05-23T19:19:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/muneebhashone/gh-research","commit_stats":null,"previous_names":["muneebhashone/gh-research"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/muneebhashone/gh-research","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muneebhashone%2Fgh-research","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muneebhashone%2Fgh-research/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muneebhashone%2Fgh-research/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muneebhashone%2Fgh-research/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muneebhashone","download_url":"https://codeload.github.com/muneebhashone/gh-research/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muneebhashone%2Fgh-research/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34279898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","cli","developer-tools","github-api","github-discussions","github-issues","llm-tools","python","research"],"created_at":"2026-06-13T09:30:47.566Z","updated_at":"2026-06-13T09:30:48.105Z","avatar_url":"https://github.com/muneebhashone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-research (`ghr`)\n\nA CLI that conducts research over **GitHub Issues, Discussions, and repository\nmetadata** and returns AI-optimized JSON. It is a *deterministic data + analysis\nengine* — it fetches, ranks, and aggregates (engagement/\"hot\" scoring, label\nfrequency, activity trends, pain-points, cross-repo aggregation) and leaves the\nnatural-language synthesis to the calling agent. Built for AI agents like Claude\nCode, not humans, though it works fine for either.\n\nIt answers questions such as: *what repos are trending, what issues are people\ncommonly facing in a project (or a whole ecosystem), what are the hottest\ndiscussions, is this project booming or dying, dig into project X.*\n\n## Why not just use `gh`?\n\n`gh` is built for humans and exposes raw endpoints. `ghr` adds an agent-friendly\ncontract on top: a two-tier command surface, deterministic ranking/aggregation\nprimitives, a uniform JSON envelope with machine-readable errors and exit codes,\nsafe result caps, a local response cache, and a [`SKILL.md`](./SKILL.md) that\nteaches an agent how to drive it.\n\n## Install\n\nClone the repo, then install it as a `uv` tool (this puts `ghr` on your PATH in an\nisolated environment):\n\n```bash\ngit clone https://github.com/muneebhashone/gh-research.git\ncd gh-research\nuv tool install .\nghr --help\n```\n\nTo upgrade later, `git pull` and re-run `uv tool install . --reinstall`.\n\nFor development (run from the source tree without installing):\n\n```bash\nuv sync\nuv run ghr --help\n```\n\n## Use it as an agent skill\n\nThis repo ships a [`SKILL.md`](./SKILL.md) that teaches an AI agent (Claude Code,\nCursor, etc.) how to drive `ghr`. Install it with [skills.sh](https://www.skills.sh):\n\n```bash\nnpx skills add muneebhashone/gh-research\n```\n\nUseful flags: `--global` (install for all projects), `--agent '*'` (all detected\nagents), `--list` (preview the skill without installing). The skill *uses* the\n`ghr` CLI, so install the CLI too (see [Install](#install) above).\n\n## Authentication\n\n- REST features (issues, repos, search) work **unauthenticated** at low rate limits.\n- **Discussions require a token** (GitHub's GraphQL API is auth-only).\n- **Semantic issue search** (`issues search --search-type semantic|hybrid`) also requires\n  a token and has its own stricter 10 req/min limit. `semantic` ranks by meaning for\n  natural-language queries; `hybrid` blends semantic + keyword; omit it for classic lexical.\n- Token resolution order: `--token` \u003e `GH_TOKEN` \u003e `GITHUB_TOKEN` \u003e `gh auth token`\n  (if the GitHub CLI is installed and logged in) \u003e stored config/keyring.\n\n```bash\nghr auth status          # shows whether a token is found, and its source (never the token)\nghr auth login --token \u003cPAT\u003e   # optional: store one (keyring if available, else config)\n```\n\n## Quickstart\n\n```bash\nghr research digest cli/cli                       # one-call repo overview\nghr research trending --language python --days 30 # recently-popular repos (stars/day)\nghr research pain-points facebook/react           # top-reacted open bug issues\nghr research hot-discussions vercel/next.js        # client-ranked hottest discussions\nghr research activity cli/cli                       # booming vs dying\nghr research common-issues --topic cli --language go\n\nghr issues search --repo microsoft/vscode --label bug --sort reactions --limit 5\nghr issues search \"auth fails on mobile\" --repo cli/cli --search-type semantic  # semantic index\nghr discussions list vercel/next.js --limit 10\nghr rate                                            # rate-limit budgets\n```\n\nGlobal flags go **before** the subcommand, e.g. `ghr --jq '.data.repos[].full_name' research trending`.\n\n## Output contract\n\nEvery command prints one JSON object:\n\n```json\n{ \"ok\": true, \"data\": { \"...\": \"...\" }, \"error\": null,\n  \"meta\": { \"command\": \"...\", \"result_count\": 8, \"truncated\": false,\n            \"cache\": {\"hits\": 0, \"misses\": 1},\n            \"rate_limit\": {\"resource\": \"search\", \"remaining\": 27, \"limit\": 30, \"reset\": 0} } }\n```\n\nExit codes: `0` ok · `2` usage · `3` not-found · `4` auth-required · `5` rate-limited ·\n`6` upstream · `7` partial/capped. See [`SKILL.md`](./SKILL.md) for the full agent guide.\n\n## Safe caps \u0026 configuration\n\nSensible defaults (result limit 30, max 100/page, search auto-stops at the 1000-result\nAPI cap, per-command request/time budgets) are all overridable via flags, `GHR_*`\nenvironment variables, or a `config.toml` — precedence: **flag \u003e env \u003e config \u003e default**.\n\n## Development\n\n```bash\nuv run pytest          # tests (HTTP mocked with respx; no network)\nuv run ruff check      # lint\nuv run ruff format     # format\nuv run mypy src/ghr    # types (strict)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuneebhashone%2Fgh-research","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuneebhashone%2Fgh-research","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuneebhashone%2Fgh-research/lists"}