Skip to content

WhyGraph 2.4.0

A rationale card no longer stops at the first few commits that lack a description: it describes them in parallel, comes back marked partial when it runs out of time, and finishes itself in the background. Next to Describe all, the portal now offers Describe core, which describes only the commits behind the files the rest of your code depends on, found from the code index, for a fraction of the cost on a large repository.

Upgrading and rolling back

From 2.3.0, run whygraph update; nothing else to do. 2.4.0 adds a column and five tables to each project's WhyGraph database (the portal's own database is unchanged), so an older image cannot open an upgraded project database. To go back, see Rolling back after this release.

What's new

  • A rationale card no longer waits on the scan to describe its commits. When some commits behind a card have no description yet, whygraph_rationale_brief and the Explorer's Generate rationale describe up to [analyze].max_workers of them in parallel (within 20 seconds), generate the card, and finish the rest in the background. Such a card comes back with partial: true, describing and completing, and the Rationale tab shows a note with a Complete button. A completion runs at most once per card (10-minute cooldown) and counts as a second card generation. See the MCP reference.

  • Describe core and Describe all. The first-scan estimate now offers two ways to write the LLM descriptions: Describe core (primary) describes the commits behind the most-referenced files in the code index (the files that make up 95 % of cross-file references; every text file when there is no usable index), and Describe all describes every commit. Full rescan still describes everything. All three also describe the pending per-file changes of large commits (more than 30 files) in core files. A new "Core commits" scan phase finds core on the first scan and on Quick rescans until a pass completes (capped at 15 minutes after the code index is ready, and resumable); git-hook scans skip it. The estimate card shows "Core: N commits in F files (about $X)" and "All: M commits (about $Y)", and the Overview's described tile adds "core X %". Commits outside core are described when a question reaches them, and are not searchable by description until then. See Projects and Scanning.

  • Cost estimates cover every model the providers list. The bundled price table, re-checked on 2026-11-11, grows from 13 to 352 models: every model on Anthropic's, OpenAI's and DeepSeek's pricing pages (newer and legacy Claude models, the GPT-6, GPT-5.x and o3 families), plus every model OpenRouter lists, priced from OpenRouter's own catalogue (Google, Meta, Mistral, xAI and the rest, and the OpenAI and DeepSeek models only OpenRouter serves). A vendor's own price still wins for an OpenRouter id, and every row can be overridden from the Prices tab. No existing price changed. See Prices and overrides.

Changes to know about

  • [analyze].max_workers now defaults to 4 (was 2). It sets how many commits a scan describes at once, and now also how many a rationale card describes at once. A project that never set it makes up to twice as many parallel calls to its provider; set max_workers = 2 under [analyze] to keep the old pace, or 1 for a small local model. See Configuration.
  • The first Quick rescans can take longer while the "Core commits" phase finds core, then a Quick rescan is fast again. In production a first pass can hold a scan slot for the code index build plus up to 15 minutes. See Production.
  • A linked project waits longer for a card. A local portal now gives its platform up to 55 seconds to build a rationale card (was 10), so a cold card arrives instead of failing; a slow or busy platform answers "try again" and the link stays connected instead of turning unreachable.

Fixes

  • A failed code index refresh now says why. When CodeGraph failed during a scan, the project's Health card and the scan's run page showed every frame of CodeGraph's progress spinner, colour codes included, and a long first index could produce so much of it that the line saying what went wrong was cut off. The message now keeps only the last lines of CodeGraph's output, one line per step, ending with its error (for example Failed: database disk image is malformed).
  • A repository's .git-blame-ignore-revs can no longer break blame. A file with a line that is not a full commit id made every blame fail; one over 64 KiB or 1,000 entries slowed every call. Such a file is now ignored, with one warning in the log.
  • Files that are not UTF-8 blame. A Latin-1 or other non-UTF-8 file no longer fails its evidence lookup.
  • Rolling back after this release. This release adds a column and five tables to each project's WhyGraph database. An older image cannot open an upgraded project database: to go back, restore each project's backups/whygraph-<previous revision>.db, which the portal writes beside its whygraph.db before upgrading it.

For developers

  • Project database migrations 5b8d2e4f6a19 (rationale_cache.deferred_shas) and c4e7a2d9b1f6 (core_state, core_file, core_rename, core_commit, core_bulk_pair). The core tables are recomputed by the next scan and never travel in an export bundle.
  • backfill_all is gone. backfill_evidence_descriptions returns a DescribeOutcome (described, terminal, waiting) and describes in parallel; tests drain its background threads through an autouse fixture.