Getting started

5-minute quickstart. By the end you'll have a browsable wiki of every coding-agent session you've ever run.

Prerequisites

  • Python ≥ 3.12
  • git
  • Sessions from at least one supported agent already on disk (Claude Code, Codex CLI, Cursor Agent CLI, OpenClaw, Copilot, Gemini, etc.) — see multi-agent-setup.md for default paths.

A bare llmwiki sync runs every enabled coding-agent source whose store exists on disk. Configure sources in config.json under adapters.<name> or run llmwiki configure-sources after install. Use --adapter <name> to limit a single run.

That's it. No npm, no brew, no database, no account.

Install

The git clone holds code + demo seeds only. Your transcripts, wiki pages, and built site live in a separate vault directory outside the repo, so personal data never lands in git. (See the README for the product overview.)

1. Clone the code and set up a venv

Clone anywhere — the directory is just the engine, not your data.

macOS / Linux

git clone git@github.com:AlexanderMakarov/llm-wiki.git
cd llm-wiki
python3 -m venv .venv && source .venv/bin/activate
./setup.sh

Windows

git clone https://github.com/AlexanderMakarov/llm-wiki.git
cd llm-wiki
python -m venv .venv && .venv\Scripts\activate
setup.bat

setup.sh / setup.bat is idempotent and:

  1. Installs the markdown runtime dep via pip install --user. Syntax highlighting runs in the browser via highlight.js, so the build stays stdlib-only.
  2. Runs llmwiki adapters to show which agents are detected.
  3. Reports sync --status so you see how many sessions would convert.

setup does not scaffold raw/, wiki/, site/ inside the clone — that data belongs in your vault (step 2). If no vault is configured yet, setup warns and points you here instead of growing data in the git checkout.

2. Create a vault and point config.json at it

Make an empty directory anywhere for your personal data, then tell llmwiki where it is via a gitignored config.json at the repo root:

mkdir -p ~/llmwiki-vault
cat > config.json <<'JSON'
{
  "vault": { "default_path": "/home/you/llmwiki-vault" }
}
JSON
llmwiki init          # scaffolds raw/ wiki/ site/ INTO the vault

With vault.default_path set, sync / build / synth / queue / lint / init all target the vault automatically — no --vault flag needed. Override it for a single run with --vault PATH.

Checking detected agents

After install, run llmwiki adapters to see which session stores were found:

python3 -m llmwiki adapters

Example output:

Registered adapters:
  name              present   enabled     active   description
  claude_code       yes       auto        yes      Claude Code — reads ~/.claude/projects/...
  openclaw          yes       explicit    yes      OpenClaw — reads configured roots...

Run llmwiki configure-sources after install to probe stores and write adapters.<name> settings. The interview asks a shared lookback first (default today−30) and shows Sessions · Earliest · In last 30 days per source before Enable; skip configure to keep unlimited history. Full support map: multi-agent-setup.md. Lookback keys: configuration-reference.md.

Shell completion

Pressing TAB after llmwiki lists every command, and a typed prefix narrows the list (llmwiki sy offers sync and synth). Only command names complete — not flags, and not names under a command. Only the llmwiki entry point completes; python3 -m llmwiki does not.

On macOS / Linux, ./setup.sh offers this at the end when run in an interactive terminal: it asks Add llmwiki TAB completion to ~/.bashrc? [Y/n] (or ~/.zshrc when your login shell is zsh), and on yes writes the line below and prints which file it changed. Re-running setup replaces that line with the current command list instead of adding a second one, and leaves the rest of the file alone. On macOS, bash users get ~/.bash_profile instead of ~/.bashrc, because Terminal and iTerm start bash as a login shell, which does not read ~/.bashrc. For any other shell it changes nothing and prints the bash line for you to add yourself. Set LLMWIKI_SKIP_COMPLETION=1 to skip the question; it is never asked when setup runs non-interactively.

To enable it by hand (for example after pip install), paste the line for your shell into its startup file and open a new terminal.

bash — ~/.bashrc (~/.bash_profile on macOS):

_llmwiki_complete() { COMPREPLY=(); if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "init sync build usage adapters configure-sources graph lint doctor queue migrate install-agent-kit candidates synth add remove search query trace version all watch install-automation" -- "${COMP_WORDS[1]}")); fi; }; complete -o default -F _llmwiki_complete llmwiki # llmwiki-completion

zsh — ~/.zshrc:

(( $+functions[compdef] )) || { autoload -Uz compinit && compinit; }; _llmwiki_complete() { _arguments '1:command:(init sync build usage adapters configure-sources graph lint doctor queue migrate install-agent-kit candidates synth add remove search query trace version all watch install-automation)' '*::arg:_files'; }; compdef _llmwiki_complete llmwiki # llmwiki-completion

Three commands after install

With vault.default_path set (step 2 above), these all read and write the vault, not the clone:

llmwiki sync     # pull new sessions from your agent store → <vault>/raw/sessions/*.md
llmwiki synth    # fill wiki/sources/ and harvest wiki/candidates/ (then review)
llmwiki build    # compile <vault>/raw/ + <vault>/wiki/ → <vault>/site/

llmwiki all runs all three in one go, then builds the graph and reports quality findings.

Day-to-day for agents: point your MCP client at python3 -m llmwiki.mcp so tools like wiki_search / wiki_read_page hit the same vault (see MCP reference). For humans: Open <vault>/site/index.html after build (plain files; nothing has to keep running) to check pipeline state, metrics, and settled entities/concepts — and try:

  • ⌘K or Ctrl+K — command palette
  • / — focus the search bar
  • g h / g p / g s — jump to home / projects / sessions
  • j / k — navigate sessions table
  • ? — keyboard shortcut help

Add a non-session document

Session sync is the default path, but notes and external sources are first-class too. llmwiki add writes into <vault>/raw/docs/; the same synth → review candidates → build loop then folds them into wiki source pages alongside sessions. Mix kinds freely:

llmwiki add notes.md                  # local markdown file
llmwiki add https://example.com/post  # web page
llmwiki add ./paper.pdf               # PDF
llmwiki add ./research-folder/        # folder of docs

By default add writes raw docs and rebuilds the site so they show up under Raw / Home; it does not synthesize wiki/sources/ unless you pass --synthesize. Run llmwiki synth later (or opt in on the same add) when you want wiki source pages. Pass --no-build to skip the site rebuild. Flags (--title, --tag, --project, --dry-run, stdin -, and more): CLI reference — add.

Next: let it run itself

You only have to do that by hand once. Hand the loop to a daily job:

llmwiki install-automation

The wizard asks one question — should the daily job just collect your sessions, or also summarise them into wiki pages? — then offers the optional extras and a schedule, and shows you the exact command line before it writes anything. Collecting only never contacts an AI provider; summarising does, which is why the wizard points you at llmwiki synth --estimate first. Every answer is also a flag, for an unattended install: CLI reference.

Where your data ends up

Everything lands in your vault directory (the vault.default_path from step 2), not the git clone:

/home/you/llmwiki-vault/      ← vault root (NOT …/wiki)
├── raw/sessions/             # converted transcripts
│   ├── ai-newsletter/
│   │   ├── 2026-04-04-<slug>.md
│   │   └── ...
│   └── <other-project>/
├── wiki/                     # LLM-maintained wiki pages
│   ├── index.md
│   ├── log.md
│   ├── overview.md
│   ├── sources/
│   ├── candidates/
│   ├── entities/
│   └── concepts/
├── site/                     # generated static HTML
│   ├── index.html
│   ├── search-index.json
│   ├── projects/
│   └── sessions/
└── llmwiki-state.json        # unified sync + queue + synth + quarantine state

The vault lives outside the repo, so it is never committed and never sent anywhere. The clone itself stays clean — only code and demo seeds. raw/, wiki/ (except the committed demo/wiki/), site/, config.json, and llmwiki-state.json are gitignored; the per-path table that used to live in the README is this tree.

Queue without auto-sync

If you are not using SessionStart hooks, drive the unified queue by hand:

llmwiki queue status
llmwiki queue run --limit 20
llmwiki migrate state   # one-time: merge legacy .llmwiki-* into llmwiki-state.json

Flags and output: docs/reference/cli.md.

New in recent versions

  • Model pages (/models/) — structured profile pages for every LLM model referenced in your sessions, with pricing, context window, and usage stats.
  • Project topics — auto-detected topic chips on project pages, extracted from session content.
  • Multi-agent support — sync sessions from Claude Code, Codex CLI, Copilot, Cursor, and Gemini CLI simultaneously. Each session gets a colored badge showing which agent produced it.

Building the wiki (Karpathy layer 2)

The sync step populates the vault's raw/sessions/ with markdown. To build the actual wiki on top of that — wiki/sources/, wiki/entities/, wiki/concepts/, linked by [[wikilinks]] — you need an LLM in the loop. That's where Claude Code (or any supported agent) comes in.

Inside a Claude Code session at the llm-wiki repo root (with your config.json pointing at the vault):

/wiki-ingest raw/sessions/ai-newsletter/

The agent reads the source markdowns from the vault, writes summary pages, cross-links entities, and updates wiki/index.md. See CLAUDE.md for the full Ingest Workflow.

Then re-run llmwiki build to get the compiled wiki into the HTML site.

Auto-sync on session start (optional)

To make sync happen automatically every time you start Claude Code, add a SessionStart hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "(python3 /absolute/path/to/llm-wiki/llmwiki/convert.py > /tmp/llmwiki-sync.log 2>&1 &) ; exit 0"
          }
        ]
      }
    ]
  }
}

The ( ... &) ; exit 0 pattern backgrounds the sync and makes sure it never blocks Claude Code starting.

Next steps

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date