WhyGraph 2.0.0¶

2.0.0 turns WhyGraph from a per-repository command line tool into a local portal: one server that holds all your projects, runs their scans, and serves an MCP endpoint per project. Your history carries over, but how you start WhyGraph, where keys live, and how agents connect all change. Read the breaking changes before you upgrade.

Breaking changes¶

whygraph init, whygraph serve, whygraph analyze and whygraph-mcp are removed. Add a repository from the portal's Projects page instead of running init; the portal is the web panel that serve used to start; per-commit descriptions come from scan and from Describe now. init, serve and whygraph-mcp remain only as stubs that print a pointer to the portal and exit with status 2. analyze is gone entirely.
Agent configs are now HTTP. Every agent (Claude Code, Cursor, VS Code / Copilot, Codex) connects to http://localhost:<port>/mcp/<slug> instead of launching a stdio server. To migrate, re-add each repository in the portal: it offers to migrate or remove each old whygraph entry per agent file.
The installer replaces the whygraph-mcp shim with a stub that prints the removal message, so a stale 1.x agent config that still runs whygraph-mcp fails with an explanation rather than a bare "not found".
whygraph scan refuses in portal-managed repositories. Scan from the portal. Headless scan still works in a repository the portal does not manage (CI, a plain checkout), and in one you have removed from the portal.
Git hooks require the running portal. Hooks no longer run a local scan; they ask the portal to scan. Commits made while the portal was down are caught up the next time it starts. The hook helper now lives inside the git directory at .git/whygraph/whygraph-scan (not in .whygraph/hooks/), and is never written through a symlink.
API keys and GitHub tokens in your shell env no longer reach WhyGraph. The portal container is started with none of your environment, so exporting ANTHROPIC_API_KEY, OPENAI_API_KEY or GH_TOKEN has no effect on it or on the scans it runs. Enter them in the portal's Settings. Keys and tokens already written in a repository's whygraph.toml are moved into the portal's encrypted store when the file is imported. Headless whygraph scan outside the portal still reads the standard variables.

Deprecated config keys. These 1.x keys still work in 2.x, log one deprecation warning per process, and stop being supported in 3.0:

1.x key	Use instead
`[scan].provider`	`[scan].forge`
`[scan].max_workers`	`[analyze].max_workers`
`[llm.<provider>].model`	`[llm].model = "<provider>/<model>"`, or a task's own `model` (`[<task>].model`)
Task-level `timeout_sec` (`[analyze].timeout_sec`, `[rationale].timeout_sec`)	`[llm.<provider>].timeout_sec`

A 1.x file resolves to the same providers, models and timeouts it did before. See Deprecated keys.

Upgrade path¶

Install 2.0.0 with the installer. If you ran the old playground, whygraph serve --stop removes a leftover container that may hold port 8765.
Start the portal and share the folder that holds your repositories:
```
whygraph up --add-folder ~/Work
```
Add each existing repository from the Projects page, exactly like a new project. Their data is reused: .whygraph/whygraph.db is backed up and migrated, the .codegraph/ index is kept, 1.x hooks are replaced by the portal's, and old agent entries are migrated to HTTP.
Enter your provider keys and GitHub token under Settings.

The full upgrade guide covers custom database paths, agent approval prompts and going back.

What's new¶

The portal. whygraph up starts one local server for every project, with setup, a Projects page, an add-project wizard, per-project settings and global Settings. The Explorer and Chat assistant move into it, one per project.
Per-project HTTP MCP. Each project gets its own endpoint at /mcp/<slug>; the portal writes and migrates the config for all four agents.
Config v2. One [llm] table with provider/model names, per-task overrides, and a forge setting; 1.x files keep working.
Live scans. Scans run inside the portal with streamed progress, run history and a log tail, an estimate up front, and single-flight runs that merge queued triggers.
GitHub clones with polling. Add a project straight from a GitHub URL; the portal clones it with a host-scoped credential helper and keeps it current by polling, so the token never lands in .git/config, argv or logs.
A design system. The playground is rebuilt on shadcn primitives and design tokens, with a light and dark theme.
Security hardening. Host, Origin and fetch-metadata guards on the API, credentials in an encrypted store with a rotatable keyring, a path check that never follows a symlink out of a project root, configured remotes that can never become git options, and atomic project removal.