auto-llm-wiki

A kit that gives any git repo an autonomous, agent-maintained wiki: a markdown knowledge base written and maintained exclusively by LLM coding agents, shared with the whole team through normal git flow, and readable (optionally in Obsidian) by humans. Based on Karpathy's llm-wiki, adapted for coding teams: knowledge compiles into crosslinked pages instead of being re-derived from scratch every session.

Install into a repo

git clone <this-repo> && cd auto-llm-wiki
./install.sh /path/to/your/repo            # or: --wiki-dir kb

Then commit the new files in your repo. Every teammate who pulls gets the full wiki workflows — no per-person setup. The optional date merge driver needs one setup command per clone (below). Re-run install.sh anytime to refresh the machinery; existing wiki content is never overwritten.

What it installs

• wiki/ — the knowledge base: WIKI.md (the contract), index.md, log/ (journal, one file per entry so branches never conflict on it), overview.md, plus raw/, sources/, systems/, concepts/, decisions/, practices/, notes/.
• .claude/skills/wiki/ — one skill with four workflows: consult (read before non-trivial work), record (write durable learnings), ingest (compile dropped sources), lint (heal the graph).
• .claude/hooks/ — a SessionStart hook that points every session at the index, and a Stop hook that prompts at most once per session to record unrecorded learnings (only when substantive work happened; fails open).
• .claude/settings.json — created, or additively merged if you already have one: the two hook entries are wired here; pre-existing settings are preserved.
• .claude/scripts/wiki-lint-checks.sh — deterministic checks: broken links, generated catalog drift, orphans, dead provenance, staleness vs git history.
• .claude/scripts/wiki-index.sh — deterministic catalog generation and a read-only --check mode for CI; titles and descriptions come from category pages.
• .claude/scripts/wiki-merge-updated.sh and wiki-setup-merge.sh — optional conservative resolution of isolated verification-date conflicts.
• Fragments: wiki merge rules in .gitattributes, wiki/.obsidian/ in .gitignore, and a self-contained ## Wiki section appended to CLAUDE.md.

Generated catalog and parallel branches

After changing category pages, run from the target repo root and commit the result:

.claude/scripts/wiki-index.sh                 # use `kb` for a custom wiki directory
.claude/scripts/wiki-index.sh --check         # CI: fails on drift or invalid metadata

The index uses each page's H1 and single-line description, in deterministic path order within each category. Never edit it by hand. The tracked index can still conflict: resolve page conflicts first, regenerate, stage, then continue the merge or rebase. Regenerate after clean merges too. Add --check to CI for the combined merge result to detect duplicates, stale descriptions, and missing/deleted entries. The installer does not add or replace the adopting repository's CI workflows.

On upgrades, install.sh preserves your existing index and WIKI.md. Review and adopt the generated-index, verification-date, and parallel-branch sections from template/wiki/WIKI.md, then run the generator and review its diff. Move any handwritten index-only knowledge into category pages before regenerating. Refreshed wiki skills expect this generated catalog workflow.

To resolve isolated updated: conflicts locally, run once per clone:

bash .claude/scripts/wiki-setup-merge.sh

This registers the shipped driver in local Git config. .gitattributes travels with the repository; registration does not. Without registration (including on forges), ordinary text merging applies. The driver picks the later valid date only for an isolated frontmatter date conflict where both sides advance or retain the ancestor date. Other conflicts stay unresolved. updated still means last verified, not last edited, and the combined page needs review.

Platforms

macOS and Linux work out of the box. Windows needs Git for Windows — Claude Code runs hooks under Git Bash — plus any Python (python3, python, or the py launcher) for the stop-guard and the installer's settings merge. Catalog generation and the optional merge driver require Python 3.8+. Without Git Bash, hooks fail open: the wiki, skill, and lint still work; the session pointer and stop nudge silently don't fire.

Conventions in one breath

Standard relative markdown links only (renders everywhere, Obsidian-compatible); kebab-case single-topic pages with description/tags/updated/sources frontmatter; every claim has provenance; record only what the next agent can't cheaply re-derive; wiki changes ride your branch in wiki:-prefixed commits. QMD is an optional per-machine search accelerator — qmd collection add <repo>/wiki --name <repo>-wiki && qmd update && qmd embed, installed and wired per machine (never by this kit) — with index+grep as the universal fallback.

Development

bash test/run-tests.sh

Design docs: docs/superpowers/specs/ and docs/superpowers/plans/.