karpathy-wiki

Karpathy Wiki

A Claude Code skill for auto-maintained LLM wikis — based on Andrej Karpathy's LLM Wiki pattern.

Instead of re-deriving answers from raw documents every time (RAG), the LLM incrementally builds and maintains a wiki — a structured, interlinked collection of markdown files. The wiki compounds with every source you add and every question you ask.

For day-to-day usage and the workflow walkthrough, see MANUAL.md.

What it does

As you work with Claude Code, any durable knowledge — research findings, resolved confusions, validated patterns, gotchas, architectural decisions — gets written as a small capture file and processed by a detached background worker into a persistent wiki. The wiki is git-versioned. Your flow is never interrupted.

User commands:

• wiki status — health report (categories, page counts, depth-violation count, soft-ceiling indicator, quality rollup, last ingest, drift, recent ingester-reported issues, fork-asymmetry). Implemented.
• wiki capture — write a chat-driven capture (the agent's canonical entry point; supports --kind chat-only|chat-attached, body via stdin or --body-file).
• wiki ingest-now — drift-scan + drain inbox/ on demand.
• wiki issues — show recent ingester-reported issues, grouped and severity-ordered.
• wiki use project|main|both — change per-cwd wiki mode.
• wiki init-main — bootstrap ~/.wiki-pointer (interactive).
• wiki doctor — deep lint + smartest-model re-rate of quality blocks. Not yet implemented (stub returns "not implemented" exit 1). Deferred to a future ship; tracked in TODO.md.

Everything else is automatic. The plugin handles both a main knowledge base (~/wiki/) and per-project wikis (<project>/wiki/) via the wiki-resolve.sh resolver: every capture call resolves the right wiki for the cwd before writing. Drop a file into a wiki's inbox/ and the next session-start ingests it directly — no fabricated wrapper capture required.

Install

Clone the repo and the user CLI symlink:

git clone https://github.com/toolboxmd/karpathy-wiki ~/dev/karpathy-wiki
ln -s ~/dev/karpathy-wiki/bin/wiki ~/.local/bin/wiki   # or anywhere on PATH

Then register the plugin with Claude Code by adding two entries to ~/.claude/settings.json — the marketplace pointer and the enabled-plugins flag:

{
  "extraKnownMarketplaces": {
    "karpathy-wiki-local": {
      "source": {
        "source": "directory",
        "path": "/Users/<you>/dev/karpathy-wiki"
      }
    }
  },
  "enabledPlugins": {
    "karpathy-wiki@karpathy-wiki-local": true
  }
}

Replace /Users/<you>/dev/karpathy-wiki with your actual repo path. Then run /reload-plugins in any Claude Code session. Hooks, commands, and the SKILL are auto-discovered from the plugin manifest — no manual hook wiring required.

Note on local install: Claude Code's plugin system requires plugins to come from a registered marketplace, even for local-directory sources. The extraKnownMarketplaces entry above declares this repo IS a (single-plugin) marketplace; .claude-plugin/marketplace.json makes that real. A bare ~/.claude/plugins/karpathy-wiki symlink is NOT enough — Claude Code won't load slash commands from it.

How it works

The skill is split into four focused parts, each loaded only when its moment arrives:

• skills/using-karpathy-wiki/SKILL.md — loader, auto-injected into every session by the SessionStart hook (via hookSpecificOutput.additionalContext for Claude Code; additional_context for Cursor; additionalContext for Copilot CLI / SDK-standard). Defines iron laws, triggers, and points at the other three.
• skills/karpathy-wiki-capture/SKILL.md — main agent, on-demand. Capture-authoring protocol: format, body floor, bin/wiki capture invocation.
• skills/karpathy-wiki-read/SKILL.md — main agent, on-demand. Deterministic 6-step orientation ladder for finding wiki coverage of a user question (orient → count candidates → inline-read OR Explore subagent OR web search → cite). Loaded for any user question, per Iron Rule 4.
• skills/karpathy-wiki-ingest/SKILL.md — spawned claude -p ingester only. Deep orientation protocol, page format, validator contract, manifest protocol, commit protocol.

Two hooks live at repo level:

• hooks/session-start — runs in this order: (1) subagent / ingester fork-bomb guard, (2) loader injection of the using-karpathy-wiki skill, (3) wiki resolution from cwd, (4) inbox/ scan with 5-second mtime defer (rsync/unzip protection) → emits capture_kind: raw-direct captures, (5) raw/ drift detection + raw-recovery (accidentally-dropped files in raw/ move back to inbox/ under the manifest lock), (6) drain pending captures via detached ingester spawn, (7) reclaim stale .processing files (>10 min).
• hooks/stop — session-end stub (transcript sweep is post-MVP).