issue-graph

Find related issues, competing changes, and unresolved follow-ups before you start work.

issue-graph traces linked GitHub issues and pull requests. Use it to find existing fixes, check PR status by author, and choose what to review next.

Public CLI output captured on September 22, 2026. Capture details.

Start here

Install the npm package with Node.js 20 or later. GitHub queries use your GitHub CLI login.

Try the CLI without a global installation:

npx issue-graph@latest --help

For the installed command used below:

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

Trace public agent-browser issue #1113 without saving a snapshot:

issue-graph 1113 --repo vercel-labs/agent-browser --depth 1 --max-nodes 12 --no-snapshot

To use npx instead, replace issue-graph with npx issue-graph@latest. At the 2026-09-22 capture, issue #1113 was closed, PR #1137 was merged, regression #1148 was closed, and follow-ups #1371 and #1607 were open. Check the open follow-ups before assuming the fix covers them.

Check missing references and crawl limits in the report. Each run queries GitHub, so results can change.

Update an npm installation

npm install --global issue-graph@latest

Use issue-graph --help to check the commands supported by your installed release.

Choose a workflow

Graph and plan default to compact human output in a terminal. Graph still prints Markdown in a pipe; plan prints versioned JSON. Use --format text for the human view outside a terminal, or --format markdown for Markdown. Plan also supports --format json. Human output wraps at up to 100 columns; monochrome bold/dim styling requires a TTY and is disabled by NO_COLOR, CI, or TERM=dumb.

Graph --json PATH writes a graph file; its legacy --format json still prints Markdown, not JSON. Reconcile keeps terminal Markdown and piped JSON defaults and does not support --format text. Status defaults to a terminal table or JSON in a pipe; its --json flag takes no filename.

Explore and compare

Export a graph and a self-contained HTML explorer:

issue-graph 1113 --repo vercel-labs/agent-browser --depth 1 --max-nodes 12 --no-snapshot --json graph.json --html graph.html

Open graph.html directly in a browser to explore relationships, filter nodes, and review cleanup candidates.

Graph and reconcile runs save local history under ~/.issue-graph/ by default. Re-running the same graph seeds shows a snapshot diff; reconciliation tracks repository-level action changes. --no-snapshot skips saving history but does not prevent explicitly requested JSON or HTML exports. Plan writes no snapshots.

Status history is opt-in:

issue-graph status --repo vercel-labs/portless --author ctate,Railly --save
issue-graph status --repo vercel-labs/portless --author ctate,Railly --since last --save

Status reports unknown counts as ? or null. Check coverage before using totals, and review CI and unresolved review threads separately before merging.

Agents and integrations

Install the CLI with npm install --global issue-graph@latest, then install the agent skill separately:

npx skills@latest add vercel-labs/issue-graph

Choose your agent and project scope, preserving any local skill changes. If you cannot access the repository, use npx skills@latest add https://issue-graph.dev. The public site, /skill.md, and repository skill serve the same canonical skill. CLI installation and GitHub authentication are separate setup steps.

Before operational commands, load and read the guidance bundled with the installed CLI:

issue-graph skills get core
issue-graph skills get core --full

Use --full for workflow references, issue-graph skills list for available guides, and command-specific --help for syntax. If the CLI or guidance is missing, report the error and ask for an authorized setup correction. See Agents for setup.

Use --cluster to print a root-cause clustering task for the calling agent. --cluster-run claude or --cluster-run codex sends it to an installed headless agent. Review the payload and the agent's permissions and data policy before using private repository evidence; the CLI does not sandbox that process.

Install the published library with npm install issue-graph@latest. It separates the runtime-agnostic core (issue-graph) from shell (issue-graph/transport/shell, using gh) and HTTP (issue-graph/transport/http, using fetch plus a token) transports. See Library for ESM imports and server-side credential handling.

Documentation

Read the documentation at issue-graph.dev/docs, or browse its source in this checkout:

• Get started: installation, authentication, and a first result
• Graph: depth, caps, snapshots, and HTML
• Status: counts, coverage, and history
• Backlog: reconcile and plan
• Agents: skill setup and optional clustering
• Library: core, shell, and HTTP integrations
• Security: permissions and private data
• Reference: commands and output contracts
• Changelog: release notes

Limits and privacy

The CLI reads GitHub data and can save local snapshots or exports. Depth, node caps, hubs, permissions, and per-node API limits affect coverage. Inspect linked code and current behavior before closing an issue or merging a PR.

Snapshots, exports, logs, and cluster prompts can contain private repository metadata. Anyone with an HTML export can read its embedded data. Review content and storage permissions before sharing. See security guidance and vulnerability reporting.

Source development

Source development requires access to the INTERNAL vercel-labs/issue-graph repository. Use Node.js 20.19.x or 22.12+ (24 recommended), pnpm, and authenticated GitHub CLI access. For initial setup, follow Contributing.

From an authorized checkout, after preserving local changes, update a source installation with:

git pull --ff-only
pnpm install --frozen-lockfile
pnpm build
pnpm link --global

Contributor checks:

pnpm check
pnpm test:package

pnpm build emits the Node CLI and library in dist. Package verification tests a packed local installation, or an existing archive in supplied-tarball mode. See Contributing for the retained-artifact release process. To compare transports against live GitHub data, use pnpm exec tsx scripts/verify-transports.ts <number> <owner/repo> <depth> with appropriate access.

Local website development

From the repository root, start the docs website on a fixed local port:

pnpm dev:docs --hostname 127.0.0.1 --port 3399

Validate the production build separately. The HTTP suite checks production cache behavior, which differs from the development server:

pnpm check:docs
pnpm build:docs
pnpm --filter @issue-graph/docs test:ci

The last command starts and stops its own test server. For a manual browser session or audit, stop the development server and run pnpm --filter @issue-graph/docs start --hostname 127.0.0.1 --port 3399. In another terminal:

DOCS_TEST_URL=http://127.0.0.1:3399 pnpm test:docs:routes
DOCS_TEST_URL=http://127.0.0.1:3399 pnpm audit:docs

The agent-readability audit may follow production canonical URLs from a localhost start URL. Check its destinations when comparing local changes. is-agentic.com requires a publicly reachable URL.

License

Apache-2.0