vercel-labs/issue-graph: Map the complete reference graph around GitHub issues, pull requests, and repository backlogs.

Map the complete reference graph around GitHub issues, pull requests, and repository backlogs. - vercel-labs/issue-graph

Summary

vercel-labs/issue-graph is a Node.js CLI that traces linked GitHub issues and pull requests so engineers can see related fixes, competing changes, and unresolved follow-ups before picking up work. It authenticates through the GitHub CLI and runs queries live against GitHub, so results reflect the repository's current data rather than a static index.

What it is useful for

The tool targets the moment before you start an issue or review a PR, when you want to know whether someone already proposed a fix, whether a related PR was superseded, or whether an open follow-up means a closed bug is still incomplete. The README example traces issue #1113 in vercel-labs/agent-browser and surfaces its merged fix, a regression, and two open follow-ups to check.

Beyond single-issue traces, the same CLI supports broader backlog work. issue-graph rank owner/repo --label bug surveys labeled open issues, issue-graph status owner/repo --author X counts open PRs per author (and can show PR evidence with --view prs), and issue-graph reconcile owner/repo plus issue-graph plan owner/repo produce reconciliation and "next action" outputs in JSON for scripted workflows. Saved snapshots land under ~/.issue-graph/, and query replays those captures with filters and scoring weights without making new provider requests.

It also has an agent-facing surface: issue-graph cluster owner/repo prints a root-cause clustering task for a coding agent, and --agent claude or --agent codex sends it to a headless agent. There is a published library (issue-graph) with separate shell (gh-based) and HTTP (fetch-based) transports for embedding the runtime-agnostic core.

How engineers can use it

The README documents this command sequence for a fresh setup:

npm install --global issue-graph@latest
issue-graph --help
gh auth login
gh auth status

To trace a public issue without saving history, the documented form is:

issue-graph graph vercel-labs/agent-browser#1113 --depth 1 --budget 12 --no-save

--depth controls how far the trace follows links, and --budget caps the number of GitHub queries; both can leave gaps in coverage, and the README asks you to inspect the report for missing references and crawl limits. For an HTML export, pass -o graph.html (and keep the sibling _next/ directory and font-LICENSE.txt when sharing).

For a recurring view, issue-graph open owner/repo captures the backlog and launches the Next.js dashboard; issue-graph query github:owner/repo --state open --view rank replays saved filters without another GitHub call, and issue-graph config set --weights comments=3,age=1 persists scoring defaults in ~/.issue-graph/config.json.

Documented limitations to keep in mind: each run queries GitHub so results can change between captures, status reports unknown counts as ? or null (the README recommends checking coverage before trusting totals), and exports or cluster prompts can contain private repository metadata that anyone holding the HTML file can read. Source development uses Node 20.19.x or 22.12+ (24 recommended) with pnpm; see CONTRIBUTING.md and apps/docs/content/docs/get-started.mdx for full setup, since several commands behave differently in a TTY versus a pipe and the README itself may run ahead of the latest published release.