code-wiki-recon

name

code-wiki-recon

description

First-pass codebase reconnaissance using Google Code Wiki (codewiki.google). Use when the user is opening a new repository for the first time, asks for a quick architectural overview of an unfamiliar codebase, or needs to build a mental model before diving into code. Pulls the auto-generated TOC, architecture diagram, and section summaries from Code Wiki to bootstrap understanding. Strictly a recon tool, not a Q&A oracle — Code Wiki cannot answer deep runtime/optimization questions, only describe architecture.

Code Wiki Recon

Bootstrap understanding of an unfamiliar codebase by pulling Google Code Wiki's auto-generated architecture documentation. Saves significant manual grep/Read exploration on the first encounter.

When to invoke

• User says "first time looking at X repo", "help me understand X's architecture", "what's in this codebase"
• Before doing any non-trivial work on a repo Claude hasn't seen before in this session
• When user shares a GitHub URL and asks for a high-level summary

Do NOT invoke when:

• The user is asking a specific runtime/optimization/debugging question — Code Wiki cannot answer these (see references/limitations.md)
• The repo is small/trivial (<50 files) — just read it directly
• A cache already exists at ~/.claude/cache/code-wiki/{org}-{repo}.md and the user hasn't asked for a refresh

Required tool

Code Wiki is a SPA (Angular/boq) — its TOC and content are JS-rendered, so curl/WebFetch cannot extract them. A real browser is required.

Use chrome-devtools-mcp (preferred) or playwright-mcp. If neither is available on this bot, fall back to manual exploration (see Step 6 below) and tell the user Code Wiki recon is not possible in this environment.

Workflow

Step 1 — Detect coverage

chrome_navigate(https://codewiki.google/github.com/{Org}/{Repo})
chrome_take_snapshot()

Repo segment is case-sensitive in the URL — match the canonical GitHub casing (e.g., AI-Hypercomputer/maxtext, not ai-hypercomputer/maxtext). If unsure, navigate to the GitHub repo first and use the URL bar's casing.

Check the RootWebArea title in the snapshot:

• "{org}/{repo} | Code Wiki" → covered → continue
• "Not Found | Code Wiki" → not covered → skip to Step 6 (fallback)

Step 2 — Pull the TOC

Run via chrome_evaluate_script:

() => {
  const tree = document.querySelector('[role="tree"]');
  if (!tree) return null;
  return Array.from(tree.querySelectorAll('[role="treeitem"]')).map(el => ({
    level: parseInt(el.getAttribute('aria-level') || '1'),
    text: el.innerText.trim().split('\n')[0]
  }));
}

The TOC is Code Wiki's most valuable artifact — it's Gemini's section-by-section decomposition of the codebase.

Step 3 — Capture the main overview

The default landing page has the auto-generated architecture diagram + intro. Grab the body text:

() => document.querySelector('.body-content')?.innerText.slice(0, 8000) || null

Optionally take a full-page screenshot. The save path is constrained by the MCP — try ~/.playwright-mcp/codewiki-{org}-{repo}-overview.png. If the MCP rejects the write (some chrome-devtools-mcp instances disallow file output), skip silently — the screenshot is non-essential, the body text + TOC are the value.

Step 4 — Section summaries (usually free)

Check the body text from Step 3 first. Code Wiki's main overview page typically includes one paragraph per top-level section already (it's the auto-generated "executive summary"). If the body covers all level-1 sections from the TOC, skip the per-section clicks — you have what you need.

Only if a level-1 section is missing from the main overview, click it via its uid from the snapshot, wait ~1s, then:

() => document.querySelector('.body-content')?.innerText.slice(0, 500)

Never pull every leaf section. Detail is fetched on demand by Claude later.

Step 5 — Cache to disk

Write ~/.claude/cache/code-wiki/{org}-{repo}.md using the template at references/cache-template.md.

Required frontmatter fields:

• repo, source, fetched_at (HKT, absolute date), codewiki_commit (from page footer if visible)

The cache file MUST begin with the authority warning verbatim:

Authority warning: This summary is auto-generated by Gemini from public README/code. It is reliable for architecture and module boundaries, unreliable for runtime behavior, optimization, or non-obvious design decisions. Verify by reading actual code before acting on details.

Step 6 — Hand-off

After cache is written, report to the user in one short message:

• Where the cache lives
• TOC top-level section count + names
• 2-3 sentence architecture summary
• Suggested next step based on the user's goal

In subsequent turns of the same session, Read the cache file when architecture context is needed. Don't re-fetch unless the user asks or > 30 days have passed since fetched_at.

Fallback (Code Wiki doesn't cover the repo)

If Step 1 returned "Not Found", or no browser MCP is available:

1. Read README.md (always)
2. Read ARCHITECTURE.md, CONTRIBUTING.md, docs/index.* if they exist
3. Glob "**/*.{md,rst}" and pick the top-level / overview docs
4. List top-level directory layout (Glob "*" + Glob "*/")
5. Write a manual recon doc at the same cache path, mark source: local-exploration in frontmatter, drop the codewiki-specific authority warning, replace with: "Manually compiled from repo docs — verify details by reading actual code."

Never silently skip the recon step just because Code Wiki doesn't cover the repo. The cache file is the contract for downstream Claude turns.

Authority boundary — READ BEFORE CITING

Always read references/limitations.md before answering follow-up questions that lean on Code Wiki's content. Failure risks relaying shallow auto-generated answers as expert knowledge.

Quick rule: if the user's follow-up is about what code exists / how it's organized, citing the cache is fine. If it's about why a design choice was made, how to fix a bug, or how to tune performance, drop the cache and read actual source code.