Skip to content

WhyGraph 2.3.0

Project notes give agents and Chat the facts the code does not show, a project can move between portals as one bundle, and the portal now tells you when a release is out, with whygraph update to install it. The planning harness in your editor is reworked: research sources you extend with a file, one implementor per step, a separate evaluator with UI evidence, and a bundled web search for best practices that ranks below your repository's own evidence.

Upgrading and rolling back

Upgrading to 2.3.0 is manual one last time: re-run the installer, then whygraph up. From 2.3.0 on, whygraph update does it. 2.3.0 adds columns to each project's WhyGraph database and to the portal's database, so an older image cannot open them after the upgrade. To go back, see Rolling back after this release.

What's new

  • Update notice and whygraph update. A local portal now tells you when a newer release is out, with a banner that links its notes (production shows an Updates card to instance admins), and whygraph update does the upgrade on the host: it downloads the new installer, dumps the database, installs and recreates the portal, and stops at a release that needs manual steps unless you pass --force. The portal makes one new call a day to api.github.com for the public release list and sends nothing about you or your projects; turn it off with the Settings toggle, or WHYGRAPH_UPDATE_CHECK=0 / DO_NOT_TRACK=1 in a production or directly run portal. See Upgrading, The update check and Production upgrades.
  • Export and import a project. A project admin can export a project as one .zip - its notes and purpose card, commit and file descriptions, rationale cards, your own chats if you tick a box, and a few settings - and import it into another project of the same repository, on any portal, local or production, in any direction. Import starts with a dry-run preview that lists every wide confirmed note in full; the target's data always wins, imported notes carry an imported badge, imported rationale cards can be removed in one step, and a backup is written first. See Export and import a project.
  • Project notes. A note is a short fact the code does not show - a decision, a constraint, a gotcha, a convention - anchored to a symbol, lines, a path, an area or the whole project. Members add and confirm notes in a new Notes page and the Explorer's Notes tab; the Chat assistant gets find_notes and propose_note (23 tools now) and cites note #N; rationale cards carry the confirmed notes under notes; MCP agents get whygraph_propose_note and whygraph://note/{id}; and /whygraph-note proposes one from your editor. Agents only propose - a proposal does nothing until a member confirms it. For Claude Code, two hooks installed with the agent files deliver the project-wide notes when a session starts and a file's confirmed notes when it is read, edited or written. See Project notes and Claude Code hooks.
  • Project purpose. A project admin can have the portal draft a four-line statement of what the project is for - from the README, a few docs, reduced manifests and top-level names, read from git and sent to the [analyze] model with one call - then confirm it as a project note. It is optional (a card on the Overview and an unticked wizard checkbox) and is read like any project-wide note. See Project purpose and Security.
  • A reworked planning harness. /whygraph-plan now triages a task and splits it into child plans only when the size signals agree, researches it with one researcher per source from a sources/ folder you extend by dropping in a file, writes the plan on one shared spine, and asks at most three questions, after research, only when the answer changes the shape of the plan. The research reports are kept beside the plan, so a revise does not run them again. /whygraph-implement starts a fresh implementor for each step at the model the plan names, with a review gate after each step in Claude Code and a separate acceptance run. All four editors move together. See Planning a change.
  • An evaluator and UI evidence. In Claude Code and Cursor a read-only whygraph-evaluator judges each step against its plan entry, the whole change against your conventions, and captured screens against each step's Expected UI. A small script drives the Playwright you installed in your project to record screenshots, page snapshots and console and network signals before and after each step, and /whygraph-ui-check runs a capture by hand. See Evaluation and UI evidence.
  • Harness rules a script enforces. plan-tool.sh lints a plan and runs a step's literal Verify commands into a record that the evaluator reads; a step with no passing record is escalated. Claude Code hooks limit what the implementor, synthesizer and reviewer can run. A source that reaches an outside service runs in a separate whygraph-researcher-external agent that gets no working set and always asks you first; WhyGraph bundles no such source, and the docs show how to add one. Update all agent files together, or every step escalates. See The plan check, Verify evidence and Sources that reach an outside service.
  • Best practices from the web for /whygraph-plan. A new bundled research source, best-practices.md, searches the web for current guidance on the task's design choice and cites each finding by title, URL and year. It always asks first, sends only the search terms, and never opens a page. Its findings rank below your repository's own evidence: they appear only under the plan's ## Prior art, tagged (external), and never change a step, a constraint or the plan's confidence. Claude Code only. See Best practices from the web.
  • Agent-file overrides. A committed .whygraph-overrides/ folder lets a team replace, append to or switch off the agent files WhyGraph ships (skills, subagents, research sources, rules), and Update agent files installs the result without an Edited prompt. A file WhyGraph changed after you replaced it is flagged with the difference, and mistakes in the folder are listed as warnings that never stop an update. See Overriding the bundled files. An append can also grant an agent more tools (tools / allowed-tools frontmatter), for example an MCP server for a research source, while the file keeps following WhyGraph's updates.
  • Chat modes: Engineer and Lead. A Mode select beside the model pickers sets how the assistant approaches a question: Engineer for code-first answers, Lead for the state of the work - what shipped, what is in flight or stuck, and who knows each area. A mode is a preset with its own starter questions, never a tool subset, and a project can set the mode a new chat starts in ([chat].mode). See Modes.
  • References in your question. Symbols, file paths, #412 and commit SHAs you name in a question are looked up in the index before the model sees it, so the assistant knows which are real and where they live. The lookup has a 1.5 second budget and never fails a turn. See References in your question.
  • Areas and the Lead tools. A project can name parts of its codebase as areas (Settings > Areas, with Suggest areas from recent commits). The assistant can filter changes by area, and gets four tools: get_work_in_flight (open pull requests and issues, with idle time, stale flags, reviewers and milestones), get_area_owners (who knows this code), compare_refs and get_milestones. See Areas, open work and owners.
  • More from GitHub. A scan now also keeps pull request reviewers and review decisions, milestones, and tags (in a private refs/whygraph/tags/* namespace). See What the GitHub crawl stores. In production, pull request, review, issue and milestone webhooks and tag pushes refresh that data without a full scan, at most once every five minutes per project; subscribe the GitHub App to the Pull request, Pull request review, Issues and Milestone events to get them (see The GitHub App).
  • Rate a Chat reply. A finished reply has a thumbs up and a thumbs down; thumbs down takes a reason and an optional note. See Rating a reply.
  • Tool outcomes and timings in Agent activity. The Overview now shows, per kind of call, the error rate and the mean time per call, and flags calls that ended in an internal error. A new Chat tool calls list counts the Chat assistant's tool use by name. Counting moved to when a call ends. Still counts only. See Agent activity.
  • A reply after the last tool round. If the final allowed round comes back empty, Chat asks the model once to answer in text. See How a turn ends.
  • A failed tool result stays failed. The error flag of a tool result is kept when a chat is reloaded, branched or shortened, and is sent to Anthropic.
  • Pull request comments are capped. whygraph://pr/{number} returns the first 50 comments, each cut to 4,000 characters, with an omitted key when anything was cut. See the MCP reference.
  • Chat signals script. scripts/chat_signals.py ranks the turns of a local project database by ratings and by what happened to them.

Fixes

  • The Describe now estimate matches what a run spends. It undershot the real cost by about 3x (#86). It now replays how a run splits each commit: it sizes every file of a commit, packs them into chunks the way the describer does, counts one model call per chunk plus the call that merges them, and counts merge commits by their changes against the first parent (it left them out, though they are described). Its sizes are measured on two repositories, and it knows how claude-haiku-4-5 and claude-opus-4-7 differ from claude-sonnet-5-5: each lands within 5 % of what a sample really cost. Another model is estimated as claude-sonnet-5-5.
  • Large merge commits get the cheap stub. A merge touching more files than [analyze].large_commit_file_count against its first parent is no longer described in one pass; like any large commit, its files are described on demand.
  • Large repositories scan. A long git log no longer times out, and GitHub 502 answers and truncated GraphQL answers are retried at a smaller page size.
  • Claude Sonnet 5.5 cache reads are priced right. The bundled price table charged cache reads at $0.20 per million tokens; it is $0.10. Usage recorded from now on is estimated at the new price; rows already written keep their cost, and an organization's own price override is unchanged. See Prices and overrides.
  • Rolling back after this release. This release adds columns to each project's WhyGraph database and to the portal's 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

  • A sharper Chat eval. scripts/eval_tool_choice.py reports the cache split, uncached input and side spend per turn; runs multi-turn cases as one session; fails an answer that cites a commit or pull request the repository does not have, or calls a tool that does not exist; and adds a held-out case set, an offline replay of request sizes on recorded sessions, and blind baseline-versus-candidate packets with an optional second judge model.
  • Broken scratch repos are rebuilt. scripts/dev_fixtures.sh re-clones a dev-mode scratch repo whose HEAD names no commit instead of skipping it, so its first scan no longer fails with "failed to resolve current branch".