Skip to content

Quickstart

You've installed WhyGraph. Now point it at a repo. This is the happy path: init, scan, wire an editor, sanity-check.

1. Initialize

From the repo you want to analyze:

whygraph init

On a terminal this runs a short guided setup - pick your agent, the analyze/rationale LLMs (with optional API keys), and the source-control provider (with an optional GitHub token), then review a summary that masks every secret and confirm. It creates .whygraph/whygraph.db, writes a commented whygraph.example.toml (never any secrets) and a ready-to-run whygraph.toml (with the secrets you entered), and adds the right .gitignore entries. Every prompt is defaulted, so a bare Enter accepts it. It's idempotent - run it again any time; an existing whygraph.toml is only touched if you ask. It does not index CodeGraph yet; that's the next step.

Prefer no prompts? whygraph init --yes (and any non-interactive shell - pipes, CI, the git hooks) accepts every default without asking, writing a default whygraph.toml only if none exists.

2. Scan

whygraph scan

scan walks your git history, optionally crawls the remote for PRs and issues, refreshes the CodeGraph index, and writes a per-commit LLM description. That fills .whygraph/whygraph.db with the evidence WhyGraph serves.

The remote crawl is off by default

A fresh scan stays git-only and needs no token, because [scan].provider defaults to "off". To pull PRs and issues, set provider = "github" (or "auto") in whygraph.toml.

For a fast, offline pass - no remote calls, no LLM - skip both phases:

whygraph scan --no-remote --skip-analyze

Descriptions backfill lazily later, so this is a fine way to get started quickly. See Scanning your repo for what each phase does.

Prefer a visual view?

Once you've scanned, whygraph serve opens a local, read-only web panel over the graph, evidence, and rationale - browse it in the browser instead of (or alongside) your editor. See The Explorer playground.

3. Wire your editor

Register the MCP server with your agent. For Claude Code:

whygraph init --agent claude

That writes .mcp.json at the repo root and copies the bundled assets into .claude/. Other agents work the same way - --agent cursor, --agent vscode, --agent codex. See Wiring your editor for each one's config path.

4. Sanity-check the server

whygraph-mcp   # Ctrl-C to exit

If it launches without error, your editor can launch it too. That's it - ask your assistant why a function exists, and WhyGraph answers from history.

Where to next

  • Concepts

    Evidence, rationale cards, and the CodeGraph split.

    Concepts

  • Using WhyGraph

    How an agent calls the tools mid-task.

    MCP usage

  • Explorer playground

    Browse the graph, evidence, and rationale in a local web panel.

    Playground