Skip to main content
Whether you’re hitting your first ProviderUnavailableError or fine-tuning a large corpus workflow, this page covers the questions that come up most often. Each answer links out to deeper reference pages where relevant. If your question isn’t here, check the GitHub Issues tracker - it’s the best place to surface new problems and search prior reports.
llmwiki requires Node.js >= 24. This minimum was established in v0.5.0 to support modern test-mocking APIs and ESM features used throughout the compiler.Check your version before installing:
If you’re on an older Node release, pin to llm-wiki-compiler@<0.5.0 until you can upgrade your runtime. Earlier versions supported Node 18 and above.
ProviderUnavailableError means llmwiki could not find valid LLM credentials for the active provider. No compilation calls were made and nothing was written.The most common cause is a missing or misconfigured API key. For the default Anthropic provider, set one of:
llmwiki also reads credentials from ~/.claude/settings.json (the env block) as a fallback, so if you already have Claude Code configured locally, a bare llmwiki compile should work with no exports at all.To see all accepted provider environment variables:
If you don’t have an Anthropic API key, see the next question for keyless alternatives.
Yes. llmwiki supports four keyless or non-Anthropic providers:Example using the Claude Agent provider:
Review the provider terms of service that apply to your account type before using claude-agent for automated compilation workloads.For Codex, run codex login, set LLMWIKI_PROVIDER=codex-agent, and set LLMWIKI_EMBEDDING_PROVIDER. A missing binary or unusable login fails with a Codex-specific error and never falls back to an API key.Codex Agent requires a compatible Codex CLI; the minimum verified version is 0.152.1. Update with npm install -g @openai/codex@latest if llmwiki reports that the installed CLI does not support its required secure flags. Export Codex Agent and embedding settings in the shell: explicit Codex selection bypasses the project .env file so llmwiki never opens a file that may contain API keys.
Set LLMWIKI_PROVIDER (and any required credentials for the new provider) and re-run compile. llmwiki’s incremental hash-based change detection means only sources whose content has changed since the last compile are sent through the LLM pipeline again - your existing pages are not lost or regenerated wholesale.
Keep in mind that different providers use different models, so regenerated pages may differ stylistically from those produced by the previous provider.
The first compile must run every source through the two-phase LLM pipeline (concept extraction → page generation). For a large corpus, this is expected to take a while.Subsequent compiles are incremental. Hash-based change detection skips any source whose content hasn’t changed since the last compile. Re-running on an unchanged corpus typically takes only a few seconds.If the first compile is still slower than expected, consider:
  • Switching to a faster model: set LLMWIKI_MODEL to a faster variant for your provider (e.g. a smaller Anthropic or Ollama model).
  • Checking per-concept truncation warnings: if many sources discuss the same topic, the prompt budget cap may be firing. Review stderr for truncation warnings and adjust LLMWIKI_PROMPT_BUDGET_CHARS if needed.
  • Starting smaller: use llmwiki quickstart <source> to ingest and compile a single source first, then add the rest incrementally.
llmwiki query uses a hybrid retrieval stack: semantic chunk embeddings narrow the candidate set, BM25 reranks it, and wikilink-graph expansion adds neighbors. If semantic retrieval isn’t working, results fall back to lexical (full-index BM25) selection.Check whether an embedding store exists:
Look for embeddings.bin or embeddings.json. Binary takes precedence when both exist. File presence alone does not prove the index is usable: embedding-store-unavailable means it could not be loaded. See storage recovery and limits.If both are missing, embeddings haven’t been built yet (they are created during compile when the provider supports them). Possible causes:
  • No embedding support on the active provider. The copilot and claude-agent providers do not expose embedding endpoints. For claude-agent, set VOYAGE_API_KEY to enable semantic retrieval; for copilot, switch to the openai provider and supply OPENAI_API_KEY.
  • Freshly initialized project. Run llmwiki compile at least once to build both pages and embeddings.
You can also run the eval harness to see your wiki’s overall health score and identify gaps:
Yes. The wiki/ directory produced by llmwiki is Obsidian-compatible by design.
  • [[wikilinks]] are generated in slug-based form ([[slug|Display Title]]) so Obsidian resolves the file directly, even when the display title differs from the slug.
  • Alias-aware resolution: a [[term]] link resolves to any page that declares term in its aliases frontmatter, not just the page whose slug matches. This means links survive renames and synonyms - rename a page and declare the old name as an alias, and all existing links continue to work.
  • Tags and Map of Content: compiled pages carry LLM-extracted tags, and wiki/MOC.md groups concept pages by tag for Obsidian’s graph view.
Simply open wiki/ (or the project root) as an Obsidian vault.
Use the --lang flag on compile to generate wiki content in a specific language:
To apply the setting permanently for a project, set the environment variable instead:
The --lang flag wins over LLMWIKI_OUTPUT_LANG when both are set. The flag also works on llmwiki query to generate answers in the specified language. Unset, llmwiki produces output in whatever language the model derives naturally from your source material (typically English).
When a source file is deleted, any wiki pages that were produced exclusively from that source become orphaned - their source is gone and they can no longer be updated. Pages that had multiple contributing sources are marked stale if at least one owner is still present.llmwiki detects this automatically by comparing the hashes recorded in .llmwiki/state.json against the current state of sources/ on disk. No recompile is needed to detect it.To see which pages are affected:
To clean up orphaned pages and recompile stale ones:
For a preview with no LLM calls or writes:
See Detecting and Repairing Stale Pages for the full repair workflow.
The scale story has matured well past a few dozen sources. Several mechanisms keep large corpora manageable:
  • Semantic chunk retrieval (the v3 JSON or binary index) narrows hundreds of pages down to a small top-K via cosine similarity before any LLM selection, with BM25 reranking on top. Large stores automatically use binary storage to avoid the JSON size limit; binary limits still depend on dimensions and text size, and retrieval loads the index into memory.
  • Incremental compilation means only changed sources re-run. Re-running on an unchanged large corpus takes seconds.
  • Per-concept prompt budget (LLMWIKI_PROMPT_BUDGET_CHARS, default 200000) prevents popular shared concepts from exhausting the model’s context window. Each contributing source gets a fair share when the cap fires, with a truncation warning to stderr.
If you’re compiling a very large corpus and hitting context-window limits on popular concepts, raise the budget for a model with a larger context window:
Lexical fallback kicks in automatically when no embedding store is present, so even before embeddings are built, query still works - just without semantic ranking.
By default, llmwiki view binds to 127.0.0.1 (loopback only). This is intentional - the viewer renders your local source files and wiki pages, and exposing it on a network interface requires an explicit opt-in.To allow access from another machine on your local network, you must provide both flags together:
Be thoughtful about what you expose. The viewer path-confines all file reads to wiki/ and sources/, but any machine that can reach the port can browse your compiled wiki and (with source windows enabled) your raw ingested sources. Use this only on trusted networks.
Wildcard hosts are accepted, but --allow-lan acts as an explicit acknowledgment that you intend to expose the server beyond loopback. Omitting either flag causes the server to fall back to 127.0.0.1.
Create .llmwiki/eval/thresholds.yaml in your project with your minimum acceptable scores:
Then add llmwiki eval to your CI pipeline. It exits non-zero when any threshold is violated and lists the violations in the report:
For the full LLM-as-judge citation support check (which sends citation samples to your provider), use --suite full. The fast suite (no API key required) covers health score, citation coverage, citation precision, and corpus stats.For a deeper walkthrough of CI threshold configuration, see /guides/ci-quality-gates.
They serve different downstream use cases:Use llmwiki query when you want a direct answer. Use llmwiki context (or MCP get_context_pack) when you want to supply structured evidence to an agent or build your own reasoning layer on top.Both commands expose a --json flag for machine-readable output.
Yes. llmwiki watch monitors your sources/ directory and automatically triggers an incremental recompile whenever a file changes:
Watch mode uses the same hash-based change detection as llmwiki compile, so only the files that actually changed are sent through the LLM pipeline. It’s useful during active research or writing sessions where you’re frequently updating or adding source files.
Running llmwiki watch continuously prevents stale pages from accumulating - each source edit is recompiled immediately rather than discovered later by llmwiki lint. See Detecting and Repairing Stale Pages for more on the stale-page lifecycle.
Didn’t find what you were looking for? Check the GitHub Issues tracker to search prior bug reports and questions, or open a new issue with a clear reproduction case. Include your Node version, provider, and any relevant stderr output.