Merge pull request #24 from mtrdesign/feature/remove-codegraph-image

Drop standalone codegraph image, consolidate on one container

Author: cvetty

.github/workflows/publish-codegraph-image.yml

@@ -73,7 +73,7 @@ Invariants that keep the shim correct — preserve them:
 - **Host-user file ownership.** The shim runs `--user "$(id -u):$(id -g)" -e HOME=/tmp` so `.whygraph/` and `.codegraph/` come back owned by the host user and git sees matching ownership (no "dubious ownership"). Keep these when editing the shim.
 - **GitHub token is per-project.** `[scan].token` in each repo's `whygraph.toml` (gitignored, never committed) is exported as `GH_TOKEN` for that scan's `gh` calls (`cli/commands/scan.py:_apply_github_token`), falling back to ambient `GH_TOKEN` / `GITHUB_TOKEN` (the shim passes those through). Do **not** bake a token into the image or assume a container-wide token.
 
-CodeGraph runs from the **in-image `codegraph` binary** (no docker-in-docker, no host socket): `bootstrap.py` prefers the local binary and only falls back to `docker run` on hosts without it. `whygraph scan` refreshes the index each run — `codegraph sync -q` when an index exists, `codegraph init -i` on first run — gated by `--codegraph/--no-codegraph`.
+CodeGraph indexing belongs to **`whygraph scan`, not `whygraph init`** — `init` only bootstraps the WhyGraph DB / config / agent wiring (and its preflight no longer requires `docker`). `whygraph scan` builds or refreshes the index each run — `codegraph init -i` on first run, `codegraph sync -q` thereafter — gated by `--codegraph/--no-codegraph`. CodeGraph runs from the **in-image `codegraph` binary** (no docker-in-docker, no host socket): `bootstrap.py` (`services/codegraph/`) prefers the local binary and only falls back to `docker run` on native (`uv`/`pipx`) hosts without it. There is a **single image** — `ghcr.io/mtrdesign/whygraph` — and that fallback runs `codegraph` inside it (`docker run … whygraph codegraph …`); there is no separate codegraph image.
 
 ### Auto-rescan git hooks
 

CLAUDE.md

@@ -10,7 +10,7 @@ For each symbol, WhyGraph collects evidence from git history and GitHub (commits
 
 - **[uv](https://docs.astral.sh/uv/)** — Python toolchain. Installs Python 3.11+ automatically.
 - **git** — repo history is the primary evidence source.
-- **Docker** — `whygraph init` runs a vendored container image to bootstrap CodeGraph in the current repo. No host Node install needed.
+- **Docker** *(native installs only)* — when no `codegraph` binary is on PATH, `whygraph scan` runs CodeGraph inside the WhyGraph image to index the repo. No host Node install needed. The pure-Docker install (below) already runs everything in that image.
 - **[`gh` CLI](https://cli.github.com/)**, authenticated (`gh auth login`) — required only if your repo is on GitHub. Without it, the GitHub crawl phase is skipped silently.
 - **`claude` CLI** *or* `ANTHROPIC_API_KEY` — needed for the LLM diff-description phase of `whygraph scan` and for `whygraph_rationale_brief`. Both phases skip cleanly if neither is available. The `claude` CLI defaults to your Claude.ai subscription billing.
 
@@ -117,9 +117,7 @@ WhyGraph's MCP server (`whygraph-mcp`) is a standalone console script, so any LL
 Run from the repo you want WhyGraph to analyse:
 
 ```bash
-whygraph init                          # preflight + WhyGraph DB + CodeGraph via Docker (no agent wiring)
-whygraph init --no-codegraph           # skip the CodeGraph bootstrap step
-whygraph init --codegraph-image TAG    # pin a specific whygraph-codegraph image
+whygraph init                          # preflight + WhyGraph DB + example config (no agent wiring)
 whygraph init --skip-preflight         # skip the host-tool diagnostics (CI escape hatch)
 whygraph init --agent claude          # all of the above + writes .mcp.json + populates .claude/
 whygraph init --agent cursor          # writes .cursor/mcp.json
@@ -143,8 +141,8 @@ Don't want Python, Node, `gh`, and CodeGraph on your machine? WhyGraph ships as
 curl -fsSL https://raw.githubusercontent.com/mtrdesign/whygraph/main/scripts/install.sh | sh
 
 cd your-repo
-whygraph init      # bootstrap WhyGraph DB + CodeGraph index
-whygraph scan      # crawl history + refresh index + LLM descriptions
+whygraph init      # bootstrap WhyGraph DB + write config (+ optional --agent wiring)
+whygraph scan      # crawl history + build/refresh CodeGraph index + LLM descriptions
 ```
 
 `install.sh` drops a `whygraph` (and `whygraph-mcp`) shim on your `PATH` that runs the published image (`ghcr.io/mtrdesign/whygraph`) against the current directory — `docker run --rm -v "$PWD:/workspace" … whygraph "$@"`. The container is ephemeral per command: no compose, no `docker exec`, nothing to start or stop.
@@ -173,8 +171,8 @@ The generated `.mcp.json` launches `whygraph-mcp` by bare command name; your edi
 | Command | Purpose |
 |---|---|
 | `whygraph version` | Print installed package version. |
-| `whygraph init [--no-codegraph]` | Run preflight diagnostics (git / docker / gh / LLM credential), bootstrap the WhyGraph DB, and pull the vendored Docker image to populate `.codegraph/codegraph.db`. Pass `--agent <name>` to also wire MCP for an editor. Idempotent. |
-| `whygraph scan` | Walk first-parent history and populate `.whygraph/whygraph.db`: commits + GitHub PRs/issues + TF-IDF scoring + per-commit LLM diff descriptions. Idempotent. `--no-remote` skips the PR/issue crawl for a fast, offline, git-only scan. |
+| `whygraph init` | Run preflight diagnostics (git / gh / LLM credential), bootstrap the WhyGraph DB, and write the example config + `.gitignore` entries. Pass `--agent <name>` to also wire MCP for an editor. Idempotent. Does not index CodeGraph — that happens on `scan`. |
+| `whygraph scan` | Build or refresh the CodeGraph index (`.codegraph/codegraph.db`), then walk first-parent history and populate `.whygraph/whygraph.db`: commits + GitHub PRs/issues + TF-IDF scoring + per-commit LLM diff descriptions. Idempotent. `--no-codegraph` skips the index refresh; `--no-remote` skips the PR/issue crawl for a fast, offline, git-only scan. |
 | `whygraph hooks install / uninstall / status` | Opt-in git hooks (`post-commit` / `post-merge` / `post-rewrite`) that keep WhyGraph current as you commit — see [Keep it fresh automatically](#keep-it-fresh-automatically). |
 | `whygraph render [--out PATH] [--open] [--depth N]` | Render a self-contained HTML viewer of the CodeGraph + WhyGraph data. Single file, vendored Cytoscape, opens with double-click. Cached rationale only. `--depth N` (1–4, default 1) caps which nodes get a populated detail block — fast first paint at default 1 (modules only); pass `--depth 4` for full data. |
 | `whygraph serve [--port 8765] [--open]` | Long-running localhost viewer with on-demand rationale generation. Same UI as `render`, plus a "Generate rationale" button on uncached nodes. |
@@ -292,7 +290,7 @@ whygraph serve --open     # localhost viewer with on-demand rationale
 │   │   ├── agents/                     # planner / researcher / synthesizer / implementor
 │   │   ├── commands/                   # /rationale, /whygraph-plan, /whygraph-implement
 │   │   └── skills/                     # ask-why / plan-change / pre-edit / implement-plan
-│   ├── init.py                         # CodeGraph bootstrap (nvm + codegraph init -i)
+│   ├── init.py                         # WhyGraph DB + config + agent MCP wiring
 │   ├── mcp_server.py                   # FastMCP stdio server (resources/tools/prompts)
 │   ├── mcp_queries.py                  # composite SQL for the MCP layer
 │   ├── backend.py                      # GraphBackend Protocol + SqliteCodegraphBackend

README.md

@@ -19,9 +19,9 @@
 
 FROM python:3.12-slim
 
-# Pinned the same way as docker/codegraph/Dockerfile so the version can be
-# advanced without editing the body. Defaults to `latest` for local
-# convenience; CI/publish should pass an explicit pin.
+# Pinned via build arg so the version can be advanced without editing the
+# body. Defaults to `latest` for local convenience; CI/publish should pass
+# an explicit pin.
 ARG CODEGRAPH_VERSION=latest
 ARG NODE_MAJOR=22
 

docker/codegraph/Dockerfile

@@ -5,8 +5,8 @@
 # the WhyGraph container against the current directory, then pulls the
 # image. After this, the whole workflow is just:
 #
-#   whygraph init      # in a repo: bootstrap DB + CodeGraph index
-#   whygraph scan      # crawl history + refresh index + LLM descriptions
+#   whygraph init      # in a repo: bootstrap DB + config (+ optional --agent wiring)
+#   whygraph scan      # crawl history + build/refresh CodeGraph index + LLM descriptions
 #
 # Usage:
 #   curl -fsSL https://raw.githubusercontent.com/mtrdesign/whygraph/main/scripts/install.sh | sh

docker/codegraph/README.md

@@ -40,26 +40,6 @@
         " Default: enabled. No-op for agents that ship no asset tree."
     ),
 )
-@click.option(
-    "--codegraph/--no-codegraph",
-    "install_codegraph",
-    default=True,
-    help=(
-        "Bootstrap CodeGraph via the vendored Docker image so the project"
-        " ends up with a populated `.codegraph/codegraph.db`. Default:"
-        " enabled. Idempotent — a re-run with the DB already present is"
-        " a no-op."
-    ),
-)
-@click.option(
-    "--codegraph-image",
-    "codegraph_image",
-    default=None,
-    help=(
-        "Override the Docker image used for the CodeGraph bootstrap."
-        " Defaults to the pinned ghcr.io/mtrdesign/whygraph-codegraph tag."
-    ),
-)
 @click.option(
     "--skip-preflight",
     "skip_preflight",
@@ -85,8 +65,6 @@ def init_cmd(
     print_only: bool,
     list_agents: bool,
     install_assets: bool,
-    install_codegraph: bool,
-    codegraph_image: str | None,
     skip_preflight: bool,
     force: bool,
 ) -> None:
@@ -98,9 +76,9 @@ def init_cmd(
     ``.gitignore`` keeps the user-owned config and generated caches out of
     git (``whygraph.toml``, ``.whygraph/``, ``.codegraph/``).
 
-    Also bootstraps CodeGraph by default — runs the vendored Docker image
-    to populate ``.codegraph/codegraph.db`` in the current repo. Pass
-    ``--no-codegraph`` to skip that step.
+    Does **not** index CodeGraph — that happens on ``whygraph scan``,
+    which populates ``.codegraph/codegraph.db`` (and refreshes it on every
+    subsequent run).
 
     With ``--agent X``, registers the WhyGraph MCP server with the named
     agent. All supported agents are project-scoped — their MCP config
@@ -123,23 +101,14 @@ def init_cmd(
     project_root = Path.cwd()
 
     if not skip_preflight:
-        _run_preflight(project_root, with_codegraph=install_codegraph)
+        _run_preflight(project_root)
 
     db_path = _ensure_db_initialized()
     click.echo(f"Initialized WhyGraph database at {db_path}")
 
     _scaffold_example_config(project_root)
     _ensure_gitignore(project_root)
 
-    if install_codegraph:
-        _ensure_codegraph_bootstrapped(project_root, image=codegraph_image)
-    else:
-        click.echo(
-            "Skipped CodeGraph bootstrap. Re-run without `--no-codegraph`"
-            " — or run `codegraph init -i` against the repo by hand —"
-            " before using WhyGraph's rationale or evidence tools."
-        )
-
     if agent_name is None:
         click.echo(
             "Tip: run `whygraph init --list-agents` to see supported agents,"
@@ -161,7 +130,7 @@ def init_cmd(
         _print_install_summary(target, project_root, result, force=force)
 
 
-def _run_preflight(project_root: Path, *, with_codegraph: bool) -> None:
+def _run_preflight(project_root: Path) -> None:
     """Echo the diagnostics block; ``fail`` with a clean error on missing tools.
 
     Imported here (not at module top) so ``--list-agents`` and ``--help``
@@ -170,40 +139,11 @@ def _run_preflight(project_root: Path, *, with_codegraph: bool) -> None:
     from whygraph.cli.preflight import PreflightError, run_preflight
 
     try:
-        run_preflight(project_root, with_codegraph=with_codegraph)
+        run_preflight(project_root)
     except PreflightError as exc:
         fail(str(exc))
 
 
-def _ensure_codegraph_bootstrapped(project_root: Path, *, image: str | None) -> None:
-    """Idempotently materialise ``.codegraph/codegraph.db`` via Docker.
-
-    Echoes a one-line status for both the "already initialized" and
-    "bootstrapping now" cases, and ``fail``s with a clean message if the
-    container run blows up. Lazy import keeps lightweight CLI surfaces
-    fast (mirrors :func:`_ensure_db_initialized`).
-    """
-    from whygraph.services.codegraph import (
-        CODEGRAPH_DB_RELPATH,
-        DEFAULT_CODEGRAPH_IMAGE,
-        CodeGraphBootstrapError,
-        ensure_codegraph_db,
-    )
-
-    db_path = project_root / CODEGRAPH_DB_RELPATH
-    if db_path.exists():
-        click.echo(f"CodeGraph already initialized at {db_path}")
-        return
-
-    img = image or DEFAULT_CODEGRAPH_IMAGE
-    click.echo(f"Bootstrapping CodeGraph via Docker (image: {img})...")
-    try:
-        result_path = ensure_codegraph_db(project_root, image=image)
-    except CodeGraphBootstrapError as exc:
-        fail(f"CodeGraph bootstrap failed: {exc}")
-    click.echo(f"Initialized CodeGraph database at {result_path}")
-
-
 def _scaffold_example_config(project_root: Path) -> None:
     """Write the committable ``whygraph.example.toml`` at the project root.
 

docker/whygraph/Dockerfile

@@ -46,9 +46,10 @@
     help=(
         "Refresh the CodeGraph index before crawling — `codegraph sync` when "
         "an index exists, `codegraph init -i` on first run. Uses the local "
-        "`codegraph` binary if present, else the vendored Docker image. The "
-        "crawl itself doesn't need CodeGraph (only the MCP rationale/evidence "
-        "tools do), so a failure here warns rather than aborting. Default: on."
+        "`codegraph` binary if present, else runs it inside the WhyGraph "
+        "Docker image. The crawl itself doesn't need CodeGraph (only the MCP "
+        "rationale/evidence tools do), so a failure here warns rather than "
+        "aborting. Default: on."
     ),
 )
 @click.option(
@@ -57,7 +58,8 @@
     default=None,
     help=(
         "Override the Docker image used for the CodeGraph refresh fallback "
-        "(ignored when a local `codegraph` binary is found)."
+        "(defaults to the pinned ghcr.io/mtrdesign/whygraph tag; ignored "
+        "when a local `codegraph` binary is found)."
     ),
 )
 @click.option(