# Code Wiki Recon

> 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.

- Skill: `yangwhale/code-wiki-recon` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add yangwhale/code-wiki-recon`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yangwhale/code-wiki-recon/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: yangwhale (https://skillmd.com/u/yangwhale)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yangwhale/code-wiki-recon

---


# 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](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`:

```javascript
() => {
  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:

```javascript
() => 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:

```javascript
() => 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](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](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**.