---
title: Trace linked issues and pull requests
description: Trace the issues and pull requests linked to one item, control crawl depth and budget, compare snapshots, and export JSON or HTML.
url: "https://issue-graph.dev/docs/graph"
docs_index: /llms.txt
lastUpdated: "2026-09-27T00:00:00.000Z"
navTitle: "Graph"
canonical_url: "https://issue-graph.dev/docs/graph"
---

# Trace linked issues and pull requests

> For an index of all documentation, see [/llms.txt](/llms.txt).

## Start from an issue or PR

Pass an item as `owner/repo#123`, as an issue or PR URL, or as a bare number when you run the command inside a GitHub checkout:

```bash
issue-graph graph vercel-labs/agent-browser#1113 --depth 1 --budget 12 --no-save
issue-graph graph https://github.com/vercel-labs/agent-browser/issues/1113 --depth 1 --budget 12 --no-save
```

`graph` prints a formatted report in a terminal and Markdown when piped.

To start from several seeds, or to rank the open issues with a label:

```bash
issue-graph graph 64 246 281 --repo owner/repo --no-save
issue-graph rank owner/repo --label bug --no-save
```

Replace `owner/repo` and the seed numbers with your own. A run with several seeds also reports connected components.

## Read the graph

Nodes represent issues and PRs. Edges come from mentions in bodies and comments, timeline cross-references, connected events, and closing references. Each node records its fetched state and any available author, discussion, and PR metadata. Each edge records its source and, when available, its actor and date.

The report flags competing PRs, shared changed files, possibly superseded work, and closing claims that lack a GitHub closing link. Use these signals to choose what to inspect, and check the implementations and scope before you recommend closing anything.

`rank` orders open nodes by discussion activity, using comments, participants, reactions, inbound references, and time open. Graph JSON exports include the same ranking in `priorities`.

## Control the crawl

| Flag                | Default                                                                    | Effect                                                                 |
| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `--depth N`         | `2`                                                                        | Same-repository recursion from depth-zero seeds                        |
| `--budget N`        | `80`; `1000` for unfiltered `open`, `rank`, or `cluster` repository scopes | Total node cap, from 1 to 1000                                         |
| `--hub-threshold N` | `12`                                                                       | Fetch a non-seed node but stop expanding it above this reference count |
| `--concurrency N`   | `4`                                                                        | Concurrent node requests, from 1 to 32                                 |

Cross-repository references are fetched one hop deep. The hub threshold does not apply to explicit seeds, so to inspect an unexpanded hub, run the re-seed command the report suggests.

Each node query reads up to 100 comments, 100 timeline items, 100 PR files, and 50 closing references, without paginating past those limits. Search-based seed discovery is limited by the node budget and by GitHub's 1000-result search ceiling.

When you interpret the graph, check `cappedOut`, unfetched nodes, and unexpanded hubs. Raising `--budget` does not change the per-node limits.

## Example capture

The example captured on 2026-09-22 includes five nodes in `vercel-labs/agent-browser`: closed issue #1113, merged PR #1137, closed regression #1148, and open follow-ups #1371 and #1607. See [Get started](/docs/get-started) for their links and descriptions.

The capture reached its depth limit with 19 references left unfetched and omits the 22 edges to those references. Neither the node cap nor the hub threshold truncated it. States were read over a time window rather than at one instant, and a new run can return different results. The landing page uses a separate capture of the Portless backlog.

## Compare snapshots

`graph` saves history under `~/.issue-graph/`, or under `ISSUE_GRAPH_HOME` when it is set, keyed by repository and seed list. Run the same seed list again to see new nodes, state changes, and new links:

```bash
issue-graph graph vercel-labs/agent-browser#1113 --depth 1 --budget 12
```

History lookup depends on seed order, so pass the seeds in the same order each time. `--no-save` skips saving a new capture but still compares the run with existing history. Changes to your access or crawl limits between runs also change what the comparison can show.

## Export JSON and HTML

```bash
issue-graph graph vercel-labs/agent-browser#1113 --depth 1 --budget 12 --no-save -o graph.json -o graph.html
```

`-o PATH.json` writes `seeds`, `depth`, `nodes`, `cappedOut`, `components`, `overlaps`, and `priorities`. Graph JSON has no `schemaVersion` field. The report still prints to stdout, formatted in a terminal and as Markdown in a pipe.

`-o PATH.html` writes the static Next.js dashboard with Explore, Impact, Swarm, and Rank views. Open the file directly in your browser without running a server. If you move it, move its sibling `_next/` assets and `font-LICENSE.txt` with it. Impact shows relationships found in the graph and does not establish causality.

To query the same data from the CLI, export a dashboard without `--no-save`, or start with `issue-graph open owner/repo`. Then use `query` for shared filters, scoring, exact links, and replay, as described in [Dashboard and saved queries](/docs/dashboard).

Export paths write files even with `--no-save` and can overwrite existing paths. Review private results before sharing them.

## Add cluster labels

Print a clustering task for your agent, then load its reviewed labels into an explorer:

```bash
issue-graph cluster owner/repo
issue-graph cluster owner/repo --apply clusters.json
issue-graph graph 64 246 281 --repo owner/repo --clusters clusters.json -o graph.html --no-save
```

`cluster` saves the run and prints the task. `--apply` loads your agent's answer into that run's dashboard. `--clusters PATH` reads prepared labels into any graph export. The input can be an array of clusters or an object with `clusters` and `cleanup` fields:

```json
{
  "clusters": [
    {
      "label": "Investigate shared behavior",
      "root_cause": "Hypothesis to verify",
      "members": [{ "key": "owner/repo#64", "verdict": "inspect" }]
    }
  ],
  "cleanup": [{ "key": "owner/repo#64", "text": "Verify scope before acting" }]
}
```

See [Agents and skills](/docs/agents) for running an external agent and [Permissions and privacy](/docs/security) for handling private data.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)