llm-code-wiki

Code Wiki — Maintained Documentation Alongside Any Source-Code Project

Adapts the LLM Wiki pattern (llm-code-wiki; Karpathy's gist) to a source code monorepo. The LLM incrementally builds and maintains a persistent, interlinked markdown vault that documents every package, app, domain, and cross-cutting concept in the repo — plus ingested specs, PR summaries, articles, and design notes.

Core principle

Code comments go stale. README files rot. Architecture diagrams drift from reality. The wiki is compounding, cross-referenced, and kept current — sources (code, specs, PRs, articles) are read once and integrated into package summaries, domain overviews, ADRs, and architecture syntheses. Every claim links to a source; contradictions with newer code get flagged; the index stays in sync with what the repo actually looks like.

Obsidian is the reading room. The LLM is the maintainer. Your repo is the source of truth.

When to use

• Single-package repos — libraries, services, or apps where a README isn't enough and you want per-module/area pages
• Monorepos — Turborepo, pnpm workspaces, Nx, Bazel, Rush, Lerna, Go workspaces, Cargo workspaces
• Hybrid repos — a primary package at the root with nested apps/packages/domains
• Onboarding — a wiki that an LLM keeps up to date reduces the cost of new contributors (human or agent)
• Agent-assisted development — coding agents read the vault before making edits; they edit the vault as they go
• Architecture bookkeeping — ADRs, cross-package conventions, deprecation notices, migration plans
• Spec/PR/article ingestion — you clip an article, write a spec, review a PR — all feed into the vault

Do NOT use when: the team has a documentation CMS they prefer, or nobody will curate ingestion (vault quality = source quality).

Architecture (three layers)

The top-level wiki directory name is yours — llm-wiki/ (default), docs/, knowledge/, anything at repo root. Inside, raw/ and <vault>/ are fixed; <vault> defaults to <repo-name>-vault/ (e.g. mono-repo-vault/), override with --vault-name:

<repo>/<wiki-dir>/           # e.g. my-repo/llm-wiki/
├── raw/                     # Layer 1 — IMMUTABLE source of truth
│   ├── articles/            # clipped articles, blog posts
│   ├── specs/               # design docs, specs, RFCs
│   ├── prs/                 # PR summaries, review notes
│   ├── tickets/             # Linear / Jira / GitHub issue exports
│   ├── transcripts/         # meeting / design-session notes
│   └── assets/              # images, diagrams referenced by sources
├── <vault>/                   # Layer 2 — LLM-owned knowledge base (the Obsidian vault)
│   ├── index.md             # Content catalog (LLM updates every ingest/scan)
│   ├── log.md               # Append-only timeline
│   ├── apps/<app>/          # [conditional] One folder per application workspace (web, mobile, CLI); overview lives at apps/<app>/<app>.md
│   ├── packages/<pkg>/      # [conditional] One folder per library/service workspace package; overview at packages/<pkg>/<pkg>.md
│   ├── domains/<domain>/    # [conditional] One folder per cross-package feature area; overview at domains/<domain>/<domain>.md (domain-scoped packages live under domains/<domain>/packages/<pkg>/<pkg>.md)
│   ├── concepts/            # Cross-cutting technical concepts (auth, testing patterns, etc.)
│   ├── dependencies/        # External libraries used by the monorepo (React, Mongo, etc.)
│   ├── issues/              # Known bugs, tech debt, workarounds — synthesized across tickets
│   ├── roadmap/             # Forward-looking plans — migrations, initiatives, quarterly goals
│   ├── sources/             # One summary page per ingested source
│   ├── architecture/        # High-level architecture syntheses
│   ├── adrs/                # Architecture Decision Records
│   ├── comparisons/         # Cross-approach / cross-library analyses
│   └── .templates/          # Page templates (reference only, not indexed)
├── CLAUDE.md                # Schema + conventions (Claude Code)
└── AGENTS.md                # Same content for Codex/Cursor/Antigravity/OpenCode

apps/, packages/, and domains/ are conditional — the detector creates them only when the repo has matching containers. A single-package repo has none of these; its workspace pages live at the vault root (or under concepts/ / architecture/ for cross-cutting topics). A library-only monorepo has packages/ but no apps/. Pinned containers are recorded in <wiki>/CLAUDE.md and <wiki>/AGENTS.md.

Source of truth is the code itself. The vault is a compiled layer above it. If the vault disagrees with the code, the code wins — the vault gets updated.

Four core operations

1. Scan — walk the repo, detect packages/apps/workspaces, propose stub packages/*.md pages, and surface in-repo .md docs as ingest candidates. See references/scan-workflow.md.
2. Ingest — read a source (article, spec, PR, transcript, or in-repo doc), discuss takeaways, write a source summary, update 5-15 relevant pages, update index, append to log. In-repo docs (under a docs container) are ingested in place — the summary records source_path + last_sync_commit (when ingested with a clean working tree on main) so /code-lint flags staleness when the file changes. PDF/DOCX support is deferred — see references/ingest-workflow.md "Future formats". See references/ingest-workflow.md.
3. Query — read index.md, drill into 3-10 pages, synthesize with inline [[wikilinks]], offer to file the answer back. See references/query-workflow.md.
4. Lint — health check including code-drift detection: packages on disk missing from the vault, vault pages referencing deleted/renamed packages, stale package summaries whose exports have changed. See references/lint-workflow.md.

Quick start

# 1. Initialize a wiki at the repo root (default top-level dir is llm-wiki/;
#    inner Obsidian vault is named <repo>-vault by default — here, my-repo-vault/)
python ${CLAUDE_PLUGIN_ROOT}/skills/llm-code-wiki/scripts/init_vault.py \
    --wiki ~/Personal/my-repo/llm-wiki \
    --repo ~/Personal/my-repo \
    --topic "my-repo"

# 2. Scan the repo to create stub pages for every package
/code-scan

# 3. Drop a source (article, spec, PR) into raw/ and ingest
/code-ingest raw/specs/auth-migration.md

# 4. Ask questions
/code-query "which packages depend on common-context-node-ts?"

# 5. Health check (surfaces code-drift too)
/code-lint

Slash commands

Command	Purpose
/code-init	Bootstrap a fresh wiki with schema + starter structure (configurable top-level dir name)
/code-scan	Walk the repo, detect packages/apps/workspaces, create/update stub package pages
/code-ingest <path>	Read a source from raw/, discuss, update vault, log it
/code-query <question>	Search vault, synthesize answer with citations, offer to file back
/code-lint	Health check — orphans, broken links, stale claims, code drift
/code-log	Show recent log entries (uses unix tools on log.md)

Sub-agents

Agent	When dispatched
code-scanner	Walk the repo, detect packages, propose or update stub package pages
code-ingestor	Delegated ingest flow — reads source, proposes updates, applies after approval
code-linter	Runs the health-check workflow (mechanical + semantic + code drift)
code-librarian	Answers queries using index-first search with citations

Python tools (scripts/)

Standard library only. Run with python scripts/<tool>.py --help.

Script	Purpose
init_vault.py	Create folder structure + seed schema files. --wiki <path> is the wiki root (top-level dir; name is yours).
scan_monorepo.py	Walk the repo, detect package.json / pyproject.toml / Cargo.toml / go.mod workspaces; emit a diff of missing/renamed/deleted package pages
ingest_source.py	Extract text + metadata from a source file — prepares a brief for the LLM
update_index.py	Regenerate index.md from vault page frontmatter
append_log.py	Append a standardized ## [YYYY-MM-DD] <op> | <title> entry
wiki_search.py	BM25 search over vault pages (fallback when index alone isn't enough)
lint_wiki.py	Orphans, broken links, stale pages, missing frontmatter, log gap, + code-drift (packages on disk vs. in vault)
graph_analyzer.py	Link graph stats — hubs, orphans, components
export_marp.py	Render an architecture page as a Marp slide deck (for reviews, onboarding)

Cross-tool compatibility

Schema lives in <wiki>/CLAUDE.md (Claude Code) or <wiki>/AGENTS.md (Codex/Cursor/Antigravity/OpenCode/Gemini). The plugin ships both. The scripts run identically everywhere. See references/cross-tool-setup.md.

Note: your repo's root CLAUDE.md is separate from the wiki's CLAUDE.md. The root file defines the repo's build/style conventions; the wiki file defines how the vault is structured. Both are active simultaneously when working from the repo root.

Page categories

Category	What it documents	Directory
app	One application workspace (web, mobile, CLI) — platform, entry points, domains consumed, deployment	<vault>/apps/<app>/<app>.md
package	One library/service workspace — what it exports, who depends on it, key patterns	<vault>/packages/<pkg>/<pkg>.md
domain	A feature area spanning multiple packages (e.g. "auth", "healthkit", "billing")	<vault>/domains/<domain>/<domain>.md
concept	Cross-cutting technical idea (e.g. "GlobalContext pattern", "integration test setup")	<vault>/concepts/
dependency	An external library/package used by the monorepo — versions in use, upgrade history, gotchas	<vault>/dependencies/
issue	A known bug, tech-debt item, or workaround — synthesized across tickets/PRs/discussions	<vault>/issues/
roadmap	Forward-looking plan — migration, initiative, quarterly goals with status + milestones	<vault>/roadmap/
source	Summary of an ingested spec, PR, article, transcript, etc.	<vault>/sources/
architecture	High-level synthesis — build system, module graph, request flow, deployment topology	<vault>/architecture/
adr	Architecture Decision Record — a dated, citable decision with context + consequences	<vault>/adrs/
comparison	A vs. B analysis (libraries, approaches, patterns)	<vault>/comparisons/

Why this works (vs. just READMEs or generic docs)

READMEs / generic docs	Code Wiki
Written once, go stale	Incrementally updated on every ingest/scan
One-directional (README describes package)	Bidirectional — packages link to domains link to ADRs link to sources
Updates are manual chores	LLM does the cross-reference maintenance
Drift is invisible until you read	Lint surfaces drift mechanically
Searchable only by file	Indexed by category + frontmatter + BM25
Specs/PRs/articles live in separate systems	Ingested and linked alongside code documentation

Related skills

• obsidian-markdown — bundled with this plugin. Covers Obsidian-specific syntax (wikilinks, embeds, callouts, properties, comments, highlights). The four sub-agents (code-scanner, code-ingestor, code-linter, code-librarian) invoke it whenever they create, edit, or verify a vault page so the output renders correctly in Obsidian.
• llm-wiki — the generic personal-knowledge-base version of this skill. Same pattern, different page categories. Use llm-wiki for non-code topics (research, books, journaling).
• para-memory-files — PARA memory; useful if you have personal memory feeding into a repo wiki.

Reference docs

• references/wiki-schema.md — full vault layout, page frontmatter, naming conventions
• references/page-formats.md — package, domain, concept, source, architecture, ADR, comparison templates
• references/detection-workflow.md — how containers are classified and pinned
• references/scan-workflow.md — how the scanner detects packages and proposes pages
• references/ingest-workflow.md — detailed ingest flow
• references/query-workflow.md — query patterns, citation format, re-filing answers
• references/lint-workflow.md — health-check heuristics including code-drift detection
• references/obsidian-setup.md — Obsidian plugins, hotkeys, vault config
• references/cross-tool-setup.md — per-tool setup (Codex, Cursor, Antigravity, etc.)
• references/monorepo-principles.md — why this pattern works for code, how it differs from the generic LLM Wiki

Templates (assets/)

• CLAUDE.md.template, AGENTS.md.template, cursorrules.template — schema loaders per tool
• index.md.template, log.md.template — starter index and log
• page-templates/ — app, package, domain, concept, dependency, issue, roadmap, source, architecture, adr, comparison

Iron rules

1. The code is the source of truth. If the vault contradicts the code, the code wins — update the vault.
2. The LLM never edits files in raw/. Sources are immutable.
3. All LLM writes go to <wiki>/<vault>/. No exceptions.
4. Every vault page has YAML frontmatter with title, category, summary, updated.
5. Every ingest or scan touches ≥3 files: the changed/new page(s), index.md, log.md.
6. Every claim on a package/domain page cites either a source page ([[sources/xxx]]) or a code path (packages/foo/src/bar.ts).
7. Good query answers get filed back — explorations compound.