Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Find related issues and pull requests before you start work. For humans and agen
<img alt="issue-graph: open issues and pull requests from vercel-labs/portless grouped into five root-cause clusters, such as proxy port allocation and TLS trust" src="https://issue-graph.dev/readme-hero-light.png">
</picture>

issue-graph reads GitHub issues and pull requests, or Linear issues, and follows the references between them: closing links, mentions, cross-references, and Linear relations. It shows existing fixes, competing PRs, and open follow-ups as one graph, groups open work into clusters, and opens the result in a local dashboard. It only reads from GitHub and Linear.
issue-graph reads GitHub issues and pull requests, or Linear issues, and follows the references between them: closing links, mentions, cross-references, and Linear relations. It shows existing fixes, competing PRs, and open follow-ups as one graph, groups open work into clusters, and opens the result in a local dashboard. It only reads from GitHub and Linear. Crawling, graph classification, and ranking need no model; semantic `classify` inference can incur charges, so preview it first with `--dry-run`.

## Install

Expand Down Expand Up @@ -59,6 +59,37 @@ The dashboard groups items into connected components by default. Your agent can

Runs save locally under `~/.issue-graph/`, and `issue-graph dashboard` shows every saved run with a project switcher. `issue-graph query` filters a saved capture from the CLI and returns a link to the exact dashboard view. See [Dashboard](https://issue-graph.dev/docs/dashboard).

## Semantic suggestions

`classify` suggests request types, components and reported signals for open issues in one public repository. Every suggestion requires human review; probabilities are uncalibrated, reported impact is not verified severity, and errors are not categories. It never changes GitHub.

Preview evidence, taxonomy and cache eligibility before authorizing inference. Preview queries GitHub but makes no Gateway calls, reads no Gateway key and writes nothing:

```bash
issue-graph classify --repo owner/repo --dry-run --limit 1 --max-calls 1 --format json
```

After review, explicitly allow a small number of new calls, or reuse results without new inference:

```bash
issue-graph classify --repo owner/repo --limit 1 --max-calls 1 --format json
issue-graph classify --repo owner/repo --limit 1 --max-calls 0 --format json
issue-graph classify --repo owner/repo --limit 1 --cached --format json
```

- New inference needs environment `AI_GATEWAY_API_KEY`. Never put keys in commands or chat. `--max-calls` caps HTTP attempts, not spending; configure an account spending limit. Unknown costs are not zero, and historical cache costs are separate from current spending.
- Routing is fixed: `https://ai-gateway.vercel.sh/v1/evaluate`, model `typesafe-ai/jev`, `providerOptions.gateway.only: ["typesafe-ai"]`. There is no provider/model fallback. Requests are capped at 24,000 UTF-8 bytes, with a 30-second deadline and 256 KiB response cap; oversized evidence is not truncated.
- `--max-calls 0` still queries GitHub and can save eligible public evidence. `--cached` uses the same saved repository and limit without network, keys or writes. It is not live verification and exits 1 even when all saved answers hit. Missing evidence fails without network fallback.
- Response reuse expires 24 hours after evaluation and rechecks input identity, receipts, locks and current policy. `--refresh` requests fresh evidence/evaluation but cannot bypass locks or unsafe storage. Do not blindly retry unknown outcomes or delete locks.
- Active inference sends titles, bodies and comments to Gateway. Local evidence snapshots also contain public text; reports, receipts and response cache exclude raw bodies/comments. Review provider policy and local retention. `ISSUE_GRAPH_HOME` defaults to `~/.issue-graph` and must be owned by you and not group- or world-writable; `classify/` uses owned `0700` directories and regular single-link `0600` files, no symlinks. Permissions are not encryption.
- `--no-snapshot` disables evidence/cache/receipt storage and durable locks, not the `classify/STOP` check. It has no crash recovery and is not a safe bypass for unknown requests. STOP blocks new calls, not valid hits or in-flight completion.

For component suggestions, adapt the fictional [taxonomy example](https://github.com/vercel-labs/issue-graph/blob/main/skill-data/core/examples/taxonomy.json) and pass the same `--taxonomy PATH` to preview and inference. It uses `schemaVersion: 1` and catalog version `"1"`; it is not a maintainer-approved catalog. Without it, components are unavailable rather than invented.

Output is Markdown in a terminal and schemaVersion 1 JSON in pipes; `--json` is boolean. Exit 0 means complete live scope, including valid abstentions or zero-call reuse; 1 means partial coverage, failure, deferred work or saved-only `--cached`; 2 means invalid usage/configuration. No exit code authorizes acceptance or GitHub changes.

See [Semantic suggestions](https://github.com/vercel-labs/issue-graph/blob/main/skill-data/core/references/workflows.md#semantic-suggestions) for taxonomy limits, scheduling, review policy, cache provenance and storage behavior. Agents can retrieve it with `issue-graph skills get core --full`.

## For AI agents

Install the agent skill from this repository:
Expand All @@ -84,6 +115,7 @@ Run `issue-graph --help` for the full list, or `issue-graph <command> --help` fo
| Map work | `open`, `graph`, `linear` | [Graph](https://issue-graph.dev/docs/graph), [Linear](https://issue-graph.dev/docs/linear) |
| Prioritize | `rank`, `cluster`, `reconcile`, `plan` | [Backlog](https://issue-graph.dev/docs/backlog), [Agents](https://issue-graph.dev/docs/agents) |
| Dashboard | `dashboard`, `query`, `runs`, `config` | [Dashboard](https://issue-graph.dev/docs/dashboard) |
| Semantic suggestions | `classify` | [Semantic suggestions](https://issue-graph.dev/docs/classify) |
| Pull requests | `status` | [Status](https://issue-graph.dev/docs/status) |
| Setup | `auth`, `schema`, `skills` | [Reference](https://issue-graph.dev/docs/reference) |

Expand Down
129 changes: 129 additions & 0 deletions apps/docs/content/docs/classify.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
---
title: Suggest issue classifications with a model
navTitle: Semantic suggestions
description: Preview evidence and cache eligibility for classify, authorize model inference with explicit limits, and read every suggestion as review-required.
lastModified: 2026-11-13
---

## Preview before inference

`classify` asks `typesafe-ai/jev` for a request type, a component, and the impact that each open issue reports. It reads one public repository on github.com and never changes GitHub. Every suggestion requires human review: probabilities are uncalibrated, reported impact is not verified severity, and errors are not categories.

Start with a preview. It queries GitHub, prepares the Gateway requests, and reports cache eligibility for each issue. It reads no Gateway key, makes no Gateway call, and writes nothing:

```bash
issue-graph classify --repo owner/repo --dry-run --limit 5 --format json
```

Replace `owner/repo` with a public repository. The preview reports coverage, exclusions, planned calls, request sizes, and cache state. It does not show predictions, including for issues that would reuse a cached answer.

## Choose a run mode

| Mode | Command | What it does |
| --- | --- | --- |
| Preview | `issue-graph classify --repo owner/repo --dry-run` | Queries GitHub and reads cache; no Gateway key, call, or write |
| Allow inference | `issue-graph classify --repo owner/repo --max-calls 5` | Reuses cache hits and may pay for eligible misses |
| Reuse only | `issue-graph classify --repo owner/repo --max-calls 0` | Queries GitHub for current evidence; misses, expiry, and refresh defer |
| Saved view | `issue-graph classify --repo owner/repo --cached` | No network, key access, or writes; not live verification |
| Refresh | `issue-graph classify --repo owner/repo --refresh` | Captures evidence again and ignores saved answers without deleting them |

New inference needs the `AI_GATEWAY_API_KEY` environment variable. Low limits make the first paid run small and keep failures cheap to inspect.

## Flags

| Flag | Default | Values |
| --- | --- | --- |
| `--repo owner/repo` | Required | One public github.com repository |
| `--limit N` | `50` | 1 to 500 open issues |
| `--max-calls N` | `50` | 0 to 500 HTTP attempts, including retries and all workers |
| `--concurrency N` | `1` | 1 to 4 workers |
| `--max-retries N` | `0` | 0 to 3 retries for known HTTP 429 responses |
| `--min-interval-ms N` | `0` | 0 to 60000 milliseconds between requests |
| `--taxonomy PATH` | None | Explicit JSON file; no default is loaded |
| `--format FORMAT` | `auto` | `auto`, `json`, or `markdown` |
| `--json` | Off | Boolean JSON output on stdout; takes no filename |

`--cached` conflicts with `--dry-run`, `--refresh`, `--no-snapshot`, and a positive `--max-calls`. `--no-snapshot` keeps receipts in memory, which removes crash recovery, and still checks `classify/STOP`.

## What leaves your machine

Capture runs `gh` against github.com and requires the repository URL returned by the API to be the github.com URL. A repository on another host fails with `repository-identity-unverified`, so an Enterprise server selected by `GH_HOST` cannot have its issue text sent to Gateway.

Active inference sends the title, body, and captured comments of each eligible issue to `https://ai-gateway.vercel.sh/v1/evaluate`. Routing is fixed to model `typesafe-ai/jev` with provider `typesafe-ai` and no fallback.

| Limit | Value |
| --- | --- |
| Request body | 24,000 UTF-8 bytes; oversized issues defer instead of truncating |
| Deadline | 30 seconds, including the response read |
| Response body | 256 KiB |
| Comments per issue | 300, captured across 4 pages of 10, 100, 100, and 90 |

Incomplete comment coverage never proves that an issue lacks information. Reads are read-only, and no flag changes GitHub.

To block new calls, create an `STOP` file under the state root:

```bash
mkdir -p ~/.issue-graph/classify && touch ~/.issue-graph/classify/STOP
```

STOP blocks new inference in every mode, including `--no-snapshot` runs. It does not cancel a request that is already in flight, and valid cache hits still return.

## Cache, receipts, and locks

Saved evidence, answers, receipts, and locks live under `ISSUE_GRAPH_HOME/classify/`. The default root is `~/.issue-graph`. Set `ISSUE_GRAPH_HOME` to move it.

| Path | Contents |
| --- | --- |
| `evidence/<scope-hash>/` | Captured public issue titles, bodies, and comments |
| `cache/<input-hash>/` | Answers, hashes, and timestamps for one prepared request |
| `receipts/<date>/<request-id>/` | Pending and final receipts for one Gateway attempt |
| `locks/<input-hash>.json` | A pending or unknown outcome that blocks the same request |

Answers are reusable for 24 hours after evaluation. Before reusing one, the command rechecks the input identity, receipts, locks, and current policy. The evidence snapshot holds public issue text, and the answer cache and receipts hold hashes, metadata, and answers rather than that text.

The state root must be owned by you and not group or world writable. The command creates `0700` directories and regular `0600` files and rejects symlinks. Permissions are not encryption.

A pending or unknown outcome leaves a lock when snapshots are enabled, and later runs block the same request instead of paying for it again. Inspect the receipts before you delete a lock, and do not rerun an unknown request blindly. Response cache or final receipt persistence failures keep the pending state on purpose.

## Billing

`--max-calls` caps HTTP attempts, not spending. One cold evaluation without retries uses one attempt per eligible issue, and retries or several workers add attempts. Reported cost can be unknown, a cached historical cost is separate from current spending, and an aborted or STOP-blocked run does not prove that no charge occurred.

Set a spending limit on the AI Gateway account that owns the key. Treat `--max-calls` as a request cap and the account limit as the monetary boundary.

## Output and exit codes

A terminal gets Markdown and a pipe gets schemaVersion 1 JSON. `--format` chooses explicitly, and `--json` implies `json`.

| Exit code | Meaning |
| --- | --- |
| `0` | Complete live scope, including valid abstentions and zero-call reuse |
| `1` | Incomplete coverage, failure, deferred work, an unknown outcome, or `--cached` |
| `2` | Invalid arguments or local configuration |

No exit code authorizes accepting a suggestion or changing GitHub.

## Component taxonomy

Without `--taxonomy`, components are reported as unavailable (`taxonomy-missing`) rather than invented. Supply a JSON file to classify components against your own catalog:

```json
{
"schemaVersion": 1,
"repo": "owner/repo",
"version": "1",
"components": [
{
"id": "proxy",
"description": "Local proxy, port allocation, and TLS trust.",
"examples": ["The dev server listens on a different port than the proxy expects."]
}
]
}
```

`schemaVersion` must be `1`, and `repo` must match `--repo`. The file holds 1 to 64 components, each with an `id`, a `description` of 1 to 2000 characters, and up to 5 `examples` of 1 to 500 characters. IDs match `[a-z][a-z0-9-]{0,47}`, must be unique, and cannot be `multiple`, `new`, `insufficient`, `constructor`, or `prototype`. The file is limited to 64 KiB, and unknown fields fail validation.

The repository includes a fictional [taxonomy example](https://github.com/vercel-labs/issue-graph/blob/main/skill-data/core/examples/taxonomy.json). Adapt it and pass the same path to the preview and the paid run so both use one catalog.

Read [Permissions and privacy](/docs/security) before you store or share saved evidence.
1 change: 1 addition & 0 deletions apps/docs/content/docs/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"linear",
"status",
"backlog",
"classify",
"agents",
"library",
"security",
Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/lib/docs-paths.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ export const docsSlugs = [
"linear",
"status",
"backlog",
"classify",
"agents",
"library",
"security",
Expand Down
44 changes: 42 additions & 2 deletions scripts/verify-package.ts
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,32 @@ try {
verifyArchive(tarball, sourceManifest, digest);
const entries = run([tools.tar, "-tzf", tarball], repo, process.env).stdout.trim().split("\n");
const files = entries.filter((name) => !name.endsWith("/"));
const runtimeFiles = readdirSync(join(repo, "src"), { recursive: true, encoding: "utf8" })
.filter((name) => /\.(?:ts|js)$/.test(name) && !/\.test\.(?:ts|js)$/.test(name))
.flatMap((name) =>
["js", "d.ts"].map(
(extension) => `package/dist/${name.slice(0, -3).split(sep).join("/")}.${extension}`,
),
);
const expectedFiles = [
...runtimeFiles,
...[
"package.json",
"LICENSE",
"README.md",
"CHANGELOG.md",
"SECURITY.md",
"skills/issue-graph/SKILL.md",
"skill-data/core/SKILL.md",
"skill-data/core/references/workflows.md",
"skill-data/core/examples/taxonomy.json",
].map((name) => `package/${name}`),
];
assert.deepEqual(
files.filter((name) => !name.startsWith("package/dist/dashboard/")).sort(),
expectedFiles.sort(),
"published contents must match source modules and approved assets",
);
assert.equal(new Set(files).size, files.length, "archive must not contain duplicate files");
for (const entry of entries) {
assert.ok(entry.startsWith("package/"), `unexpected archive root: ${entry}`);
Expand All @@ -392,7 +418,8 @@ try {
/^dist\/dashboard\/_next\/static\/[a-zA-Z0-9_./()[\]-]+\.(?:css|woff2)$/.test(name) ||
name === "skills/issue-graph/SKILL.md" ||
name === "skill-data/core/SKILL.md" ||
name === "skill-data/core/references/workflows.md",
name === "skill-data/core/references/workflows.md" ||
name === "skill-data/core/examples/taxonomy.json",
`unexpected published file (source, internal docs, or maps): ${name}`,
);
assert.ok(
Expand Down Expand Up @@ -692,6 +719,19 @@ try {
invoke([...statusArgs, "--save"], 1, { ISSUE_GRAPH_HOME: join(blocker, "status") }).stderr,
/ENOTDIR|EEXIST|not a directory/i,
);
const classify = run(
[
node,
"--import",
import.meta.resolve("tsx"),
join(repo, "tests/verify-classify.ts"),
installed,
],
consumer,
{ ...env, NODE_OPTIONS: "" },
);
assert.match(classify.stdout, /PASS: \d+ classify\/legacy\/package checks/);
console.log(classify.stdout.trim().split("\n").at(-1));
const linearHtmlPath = join(consumer, "linear", "graph.html");
const linearHtml = invoke(
["linear", "ENG-1", "--html", linearHtmlPath, "--no-save", "--json"],
Expand Down Expand Up @@ -766,7 +806,7 @@ try {
const calls = readFileSync(env.PACKAGE_TEST_GH_LOG as string, "utf8")
.trim()
.split("\n");
const expectedChecks = suppliedTarball ? 58 : 59;
const expectedChecks = suppliedTarball ? 59 : 60;
assert.equal(
checks,
expectedChecks,
Expand Down
Loading
Loading