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:
- Installs the
markdownruntime dep viapip install --user. Syntax highlighting runs in the browser via highlight.js, so the build stays stdlib-only. - Runs
llmwiki adaptersto show which agents are detected. - Reports
sync --statusso 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
- architecture.md — the 3-layer Karpathy + 8-layer build breakdown
- configuration-reference.md — every CLI flag, env var, and config option
- multi-agent-setup.md — running all 6 agents at once
- privacy.md — redaction +
.llmwikiignore+ localhost-only binding - deploy/github-pages.md — deploy to GitHub Pages
- faq.md — common questions answered
- troubleshooting.md — common errors and fixes
- adapter-authoring.md — write your own adapter
- api-guide.md — use llmwiki as a Python library
- adapters/claude-code.md — Claude Code adapter details
- adapters/obsidian.md — use an Obsidian vault as an additional source