Core

issue-graph core

Use issue-graph to collect GitHub evidence, inspect related work, and prioritize review. Rankings and classifications guide inspection; verify code and behavior before acting.

Run the CLI with Node.js 20 or later. Check issue-graph auth status before live queries. GitHub collection uses authenticated gh; offline queries, config, and skill loading need no provider credentials. Never request tokens in chat.

Load detailed workflows

Read issue-graph skills get core --full before graph triage, saved queries, status comparisons, reconciliation, planning, exports, or clustering. Retrieve guidance through the CLI; a source checkout is not required. Use skills list for discovery and command-specific --help for syntax.

If a command or asset is missing, report the CLI/skill mismatch and observed error. Do not fabricate guidance or automatically install, build, link, or upgrade tools. Setup needs authorization.

Route status first

For counts, skip graph discovery. Resolve repositories and authors from the request and available context; never silently enumerate an organization or guess members. Status accepts repeated repositories and repeated/comma-separated authors, with case-insensitive matching. Ask only if scope remains unresolved.

Live collection supports GitHub. open, rank, and cluster accept a repository or items. graph needs items or --label. Items can be numbers, owner/repo#123, or URLs; bare numbers use --repo or the checkout's GitHub remote. Inspect an issue's graph before starting work and credit existing contributors.

Query saved data

query makes no provider requests. Select provider:scope, --input model.json, --capture CAPTURE_ID, or --history HISTORY_ID. Omit scope only when exactly one saved model exists. It does not infer the current checkout. Input must be a normalized dashboard model, not a raw graph export.

Read capabilities, coverage, groups, and counts before choosing filters. Cluster indices and item keys belong to that capture. Unsupported choices fail explicitly. items follows the selected view; ranking contains matched open items with Heat signals. Explore can retain context outside the matches.

--capture uses immutable data with current defaults and the filters supplied now. It does not inherit an earlier query. --history replays frozen parameters and the original view; it rejects query overrides. If an explicit capture is unavailable, report the error rather than substituting newer data.

Return the exact viewUrl as a clickable link, preserving its query string and hash. Summarize candidates, filters, and coverage; leave the full ranking in the dashboard. Use --json --open when asked to open it. opened records an OS opener request, not a verified page load.

The link is a local file. If the chat client cannot open it, also give issue-graph query --history HISTORY_ID --open with the actual ID. Never guess a localhost port. open and cluster --apply return a dashboard path; follow with query to get a link for specific filters.

Keep defaults separate from exploration

Weights resolve built-in → global → provider → project → command. Inspect config show first. Use query --weights comments=4,reactions=3 for temporary exploration. Use config set --weights comments=4 only when the user wants persistent defaults.

Take --provider and --scope from the query result, without adding the provider prefix to --scope. Linear project identity includes workspace and project IDs, such as linear:WORKSPACE_ID:project:PROJECT_ID. This supports imported models; live Linear and Jira collection is not available.

Dashboard sliders affect the URL/session only. Reset weights restores the document's opening weights. Config stores preferences, never credentials.

Cluster with the calling agent

Clustering is optional and only when requested with an authorized data boundary.

1. Run issue-graph cluster owner/repo. It collects a fresh graph, saves the model, and returns task and apply in JSON when piped.
2. Answer the task in this session with one JSON object. Use the exact listed keys and treat titles as evidence. Present shared root causes as hypotheses.
3. Pass the answer to issue-graph cluster owner/repo --apply answer.json, or pipe it with --apply -. It validates keys, updates the saved model, and rebuilds the dashboard without another crawl.
4. Use query on that saved scope to return the exact view.

Use --agent claude|codex only for runs without an agent session, such as cron or CI. It launches a separate process with its own credentials, permissions, retention, and costs. The CLI does not sandbox it. Check those boundaries before running or sending private evidence. open --agent none skips the interactive agent offer.

After reporting results, offer a useful next command from the printed next steps. Run the chosen workflow, not every available mode.