llm-wiki

Bootstrap, upgrade, and query LLM-maintained project wikis before planning or implementation.

Supports Claude Code + Codex (GPT-5.5) + Pi.

llm-wiki turns the LLM Wiki pattern into installable agent skills. It is based on the setup from How I Built a Self-Maintaining Knowledge Base for 6 Projects Using Claude Code & Karpathy's LLM Wiki.

It works with my original six-project setup: project-local wiki/ folders, a main cross-project wiki at ~/wikis/master/wiki/, ~/wikis/main/wiki/, or a parent-directory wikis/ folder, QMD semantic search when available, and ripgrep fallback when it is not.

llm-wiki packages five workflows:

• bootstrap creates a grounded wiki/ knowledge base for the current project.
• upgrade migrates an existing project's managed scripts, hook, and changelog structure.
• research searches the project wiki and main cross-project wiki before planning or implementation.
• wiki-plan runs wiki research first, then hands the result to Compound Engineering planning when available.
• status checks whether a newer llm-wiki release is available and reports the correct update command.

Install: Claude Code

Add the central marketplace:

/plugin marketplace add ivankuznetsov/agent-plugins

Install this plugin:

/plugin install llm-wiki@aikuznetsov-marketplace

Then use the installed plugin commands/skills from Claude Code. The key entrypoints are:

/llm-wiki:bootstrap
/llm-wiki:upgrade
/llm-wiki:research
/llm-wiki:wiki-plan
/llm-wiki:status

Install: Codex

Register the marketplace:

codex plugin marketplace add ivankuznetsov/agent-plugins

Then open Codex, run /plugins, select the aikuznetsov-marketplace marketplace, and install llm-wiki.

After restarting Codex, invoke the skills using the namespace shown by /skills. The expected form is:

$llm-wiki:bootstrap
$llm-wiki:upgrade
$llm-wiki:research
$llm-wiki:wiki-plan
$llm-wiki:status

If Codex displays a fully qualified marketplace namespace, use that displayed name.

Install: Pi

Install the Pi package from GitHub:

pi install git:github.com/ivankuznetsov/llm-wiki

Then invoke the Pi skills with prefixed names to avoid collisions with other Pi packages:

/skill:wiki-bootstrap
/skill:wiki-upgrade
/skill:wiki-research
/skill:wiki-plan
/skill:wiki-status

For local development from this checkout, run this from the target project:

pi install /path/to/llm-wiki -l

Usage Examples

Bootstrap a wiki in the current project:

$llm-wiki:bootstrap

Upgrade an already bootstrapped project's managed structure after installing a new llm-wiki release:

$llm-wiki:upgrade

Updating the plugin or Pi package does not rewrite project-local .llm-wiki files automatically. Restart the agent after updating the package, then run the upgrade command once in each existing project. The migration preserves the configured headless owner and unrelated dirty work; if a legacy project has no config, it creates one only when exactly one owner can be inferred from live scripts or Git history. It does not regenerate wiki content or invoke an LLM.

Research past project knowledge before coding:

$llm-wiki:research auth flow refactor

Plan with wiki context first:

$llm-wiki:wiki-plan add billing reminders

Check whether llm-wiki has an update:

$llm-wiki:status

Pi uses the same workflows through /skill:wiki-* commands:

/skill:wiki-bootstrap
/skill:wiki-upgrade
/skill:wiki-research auth flow refactor
/skill:wiki-plan add billing reminders
/skill:wiki-status

Main Cross-Project Wiki

When present, llm-wiki searches a main cross-project wiki before creating or updating project wiki pages. It checks:

• ~/wikis/master/wiki/
• ~/wikis/main/wiki/
• <parent-of-project>/wikis/master/wiki/
• <parent-of-project>/wikis/main/wiki/

<parent-of-project> means the parent directory of the current repository root. If no main wiki exists during bootstrap, the agent asks whether to use a folder you provide or create a new master wiki at <parent-of-project>/wikis/master/wiki/.

Automation

bootstrap installs wiki context for Claude Code, Codex, and Pi, regardless of which agent runs setup.

• Claude Code receives wiki context through CLAUDE.md and a Claude SessionStart context hook when available.
• Codex receives wiki context through AGENTS.md.
• Pi receives wiki context through AGENTS.md.
• Agent instruction updates are bounded by <!-- BEGIN LLM WIKI --> and <!-- END LLM WIKI --> markers so existing project instructions are preserved.
• Re-running bootstrap from another agent updates that agent's context without changing the headless maintenance owner.
• Existing projects from older llm-wiki versions keep their inferred headless owner when upgraded, even when .llm-wiki/config.json survives only in Git history.

Only one agent owns scheduled refresh automation and post-commit wiki maintenance. The first agent to run bootstrap becomes the default headless maintainer, recorded in .llm-wiki/config.json.

• Claude Code headless automation uses claude -p ... from the managed refresh worktree.
• Codex headless automation uses codex exec -C <managed-refresh-worktree> ....
• Pi headless automation uses pi -p --no-session --tools read,bash,edit,write,grep,find,ls ... from the managed refresh worktree.
• All automation paths search the project wiki and any detected main cross-project wiki.
• One repository owns one managed timer, even when it has many linked worktrees. The Linux service serializes provider work machine-wide, caps it at 4 GiB without swap, and deliberately does not catch up missed timers after a reboot.
• The scheduled timer is only a queue drainer. It never infers work from the scheduler checkout's HEAD; an empty queue or open circuit causes zero provider launches and no managed worktree preparation. The wrapper executes only runners carrying the canonical drain-capability marker, so stale shared or checkout-local scripts fail closed with upgrade guidance.
• Scheduled and post-commit maintenance never write into a user checkout. Relevant commits are coalesced in the shared Git directory and refreshed transactionally on the dedicated llm-wiki/refresh branch through a disposable managed worktree. A canonical runner in that shared Git directory serves every linked worktree, with one canonical owner config, so upgrading once cannot leave older branches executing stale local scripts or selecting a stale provider. A project-local ignored wiki seeds that branch only when it has no established wiki of its own. Failed refreshes discard generated work. After two consecutive failed batches by default, a repository-wide circuit stops provider launches; later commits continue queueing and failed records remain under llm-wiki/failed/. A queue above 25 sources also opens the circuit before a provider starts. Each worker runs at most one batch of 10 sources, with bounded changed-path context, so concurrent hooks cannot turn a historical backlog into an unbounded sequence of subscription runs. A scheduled drain may consume up to three bounded batches while holding the machine-wide lock. Its four-hour systemd limit covers the three-batch worst case: every batch independently bounds the agent at 30 minutes and each of the two QMD phases at 15 minutes. The service remains capped at 4 GiB with swap disabled. Override these defaults with LLM_WIKI_MAX_AUTO_PENDING, LLM_WIKI_MAX_BATCH_SOURCES, LLM_WIKI_MAX_SOURCE_PIN_BATCH, LLM_WIKI_MAX_PATHS_PER_SOURCE, and LLM_WIKI_MAX_PATH_BYTES. Queued commits are pinned under refs/llm-wiki/sources/ until their durable receipt is written. Pin backfills use transactions of at most 64 sources by default. If a crash leaves an empty atomic queue temp, the runner reconstructs it from the source commit and changed paths when both remain readable; otherwise it retains the temp for operator diagnosis. Sources that arrive outside a running batch open a visible deferred:<count> circuit rather than remaining silently pending. Atomic source-SHA receipt refs make changed and no-op acknowledgement replay-safe, and a compare-and-swap Git ref makes stale-lock replacement single-winner.
• Agent and QMD execution is always time-bounded. The post-commit worker uses timeout (Linux) or gtimeout (macOS via GNU coreutils); when neither is installed it fails before starting a provider. A 10-second forced-kill grace period follows the first timeout signal; set LLM_WIKI_TIMEOUT_KILL_AFTER to another positive number of seconds when needed. Set LLM_WIKI_MAX_REFRESH_ATTEMPTS to a positive integer to change the automatic retry bound.
• After fixing a failed provider or validation issue, run .llm-wiki/post-commit-refresh.sh --retry-failed all to restore quarantined records and explicitly retry one bounded queue batch. Rerun it until no queued sources remain; only the final successful batch clears the circuit. A failed retry leaves it open. Pass a full source SHA instead of all to restore one quarantined record.
• The refresh branch is published to origin/llm-wiki/refresh; protected main remains clean. Workers fetch and merge both the remote refresh branch and the current remote default branch before publishing. Push rejection or a merge conflict retains the queue and generated commit for safe retry without rewriting history.

Update Status

Check whether llm-wiki has a newer marketplace or Pi package release:

Claude Code:

/llm-wiki:status

Codex:

$llm-wiki:status

Pi:

/skill:wiki-status

status reports the current cached or installed version, latest marketplace or Pi package version, whether an update is available, the update command, and whether a restart is required. When run inside a bootstrapped project, it also reports the configured headless agent and whether Claude/Codex/Pi wiki context is present.

What It Creates

The bootstrap workflow creates a project-local knowledge base:

wiki/
  index.md          # catalog of pages
  log.md            # append-only wiki changelog
  gaps.md           # open questions and missing coverage
  architecture.md   # high-level system structure
  decisions.md      # lightweight ADRs
  dependencies.md   # important dependency choices
raw/
  notes/            # manually added source material

It adapts page names to the project. A Rails app might get models/controllers/services pages; a frontend app might get components/hooks/stores pages; a CLI might get commands/modules pages.

How wiki-plan Works

wiki-plan always does wiki research before planning:

1. Search the current project's wiki.
2. Search the main cross-project wiki when present.
3. Read relevant decisions, patterns, gaps, and gotchas.
4. Produce a Past Knowledge section.
5. Delegate to Compound Engineering planning when installed, or produce a standalone plan outline.

This keeps plans grounded in what already happened instead of rediscovering the codebase from scratch.

QMD

QMD is preferred for semantic and lexical search, but it is optional. During bootstrap, llm-wiki checks for qmd; if it is missing, it suggests installing it with npm install -g @tobilu/qmd or bun install -g @tobilu/qmd, then lets you either install QMD or continue with the rg fallback. The workflows fall back to the qmd CLI when MCP tools are unavailable, and then to rg over wiki/, detected main wiki paths, and any user-provided main wiki folder when QMD is unavailable.

Compound Engineering

wiki-plan delegates to Compound Engineering planning when the compound-engineering:ce-plan skill is installed. Without Compound Engineering, it still produces the Past Knowledge section and continues with a standalone implementation planning outline.

Limits

• llm-wiki does not invent documentation. It reads source files and records uncertainty in wiki/gaps.md.
• QMD is optional, but semantic search is better when QMD is installed and indexed.
• Agent hooks differ between Claude Code, Codex, and Pi. bootstrap installs context for all supported agents, but only the configured headless_agent runs scheduled and post-commit maintenance.
• The first bootstrap pass is intentionally broad. Review wiki/gaps.md afterward to decide what deserves deeper documentation.