← Docs hub

Configuration Reference

Complete reference for all CLI subcommands, flags, environment variables, and configuration options.

CLI subcommands

llmwiki init

Scaffold the raw/, wiki/, site/ directory structure and seed initial wiki files.

python3 -m llmwiki init

No options. Creates directories and seeds wiki/index.md, wiki/log.md, wiki/overview.md if they don't already exist.

llmwiki sync

Convert agent session transcripts (.jsonl) into markdown under raw/sessions/.

python3 -m llmwiki sync [options]

llmwiki build

Compile the static HTML site from raw/ and wiki/. Also writes AI-consumable exports into the output directory: llms.txt, llms-full.txt, graph.jsonld, sitemap.xml, rss.xml, robots.txt, and ai-readme.md. There is no separate export subcommand.

python3 -m llmwiki build [options]

llmwiki adapters

List every registered adapter and whether its session store is present.

python3 -m llmwiki adapters

No options.

llmwiki graph

Build the knowledge graph from wiki/ wikilinks.

python3 -m llmwiki graph [options]

llmwiki lint

Run every registered quality rule against the wiki and print a report. Rules the wiki switched off in its llmwiki.json never run, and every report names them.

python3 -m llmwiki lint [options]

Why --min-refs changes how many cross-reference findings you see. synth writes a [[wikilink]] for every topic it names, and the candidate harvest materializes a page only for a target named by enough distinct source pages to look significant. Everything below that bar is left unmaterialized on purpose, so link_integrity honours the same threshold rather than reporting the product's own design decisions as defects. The gate is three-way:

So lowering the threshold widens the middle band into the reported band: --min-refs 1 reports every unresolved link, which on a mature wiki can be hundreds of findings that were all deliberate declines. Nothing is hidden permanently — the lower threshold always brings them back. The stock value lives in one place, llmwiki.vault_settings.DEFAULT_MIN_REFS, which the harvest reads too, so the step that declines to create a page and the check that reports the missing page cannot drift apart. llmwiki all --min-refs N sets it for the synth and lint stages of a pipeline run.

llmwiki all (v1.2)

Run the full pipeline: sync → synth → build → graph → lint. Every stage runs by default; each has an opt-out flag. AI-consumable exports are written by build, not a separate step.

python3 -m llmwiki all [options]

llmwiki version

Print the current version.

python3 -m llmwiki version

Config file (config.json)

Copy the example and edit:

cp examples/sessions_config.json config.json

config.json is gitignored. The converter auto-loads it if present at the repo root.

Full schema

{
  "filters": {
    "live_session_minutes": 60,
    "include_projects": [],
    "exclude_projects": [],
    "drop_record_types": ["queue-operation", "file-history-snapshot", "progress"],
    "exclude_headless": true,
    "exclude_temp_cwd": false
  },

  "redaction": {
    "real_username": "",
    "replacement_username": "USER",
    "extra_patterns": [
      "(?i)(api[_-]?key|secret|token|bearer|password)[\"'\\s:=]+[\\w\\-\\.]{8,}",
      "sk-[A-Za-z0-9]{20,}",
      "[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+"
    ]
  },

  "truncation": {
    "tool_result_chars": 500,
    "bash_stdout_lines": 5,
    "write_content_preview_lines": 5,
    "user_prompt_chars": 4000,
    "assistant_text_chars": 8000
  },

  "drop_thinking_blocks": true,

  "adapters": {
    "obsidian": {
      "vault_paths": ["~/Documents/Obsidian Vault"],
      "exclude_folders": [".obsidian", "Templates"],
      "min_content_chars": 50
    },
    "codex_cli": {
      "roots": ["~/.codex/sessions", "~/.codex/projects"]
    },
    "gemini_cli": {
      "roots": ["~/.gemini"]
    },
    "openclaw": {
      "roots": ["~/.openclaw/agents", "<vault>/.openclaw-sessions-inbox"]
    }
  }
}

Sync lookback

Optional absolute date gate so bare llmwiki sync does not ingest years of history (#192). Unset shared and per-adapter keys mean unlimited — same as today’s default.

Precedence (per adapter, highest first): CLI --since → adapter YYYY-MM-DD → adapter "all" → filters.since → unlimited. "all" is valid only on the per-adapter key. An invalid date string exits 2 (same as a bad --since).

How sync applies it

• Early prune — file-based sources drop candidates whose SessionRef.mtime is before the effective lookback before loading; Cursor IDE filters on Composer header timestamps before any bubble payloads are loaded. A post-load latest_record_time gate still runs.
• No state on lookback skip — sessions skipped only because of lookback are not written into llmwiki-state.json sync.files, so widening the window later can reconsider them on a normal sync.
• Lookback GC — after a successful non-dry-run sync, for each coding-agent adapter with a durable lookback (config filters.since / adapters.<name>.since, not a one-run CLI --since), remove that adapter’s sync.files keys ("<adapter>::…") whose stored mtime is before the lookback. Notes/export intake (is_ai_session: false, e.g. Obsidian) is not GC’d. Sources with no durable lookback are untouched. GC does not delete raw/, and does not touch queue / synth / quarantine / ops.
• Sync hint — every sync ends with a line pointing at filters.since, adapters.<name>.since, and llmwiki configure-sources.

configure-sources quiz — shared start date first (Enter = today−30, or keep a stored date; or type YYYY-MM-DD). Then each source: facts block (Sessions · Earliest · In last 30 days, path found or not) → Enable ([Y/n] when a default path exists and ingest is ready, [y/N] otherwise) → path → start date (Enter = use shared, or YYYY-MM-DD). Non-interactive / skipped interviews invent no dates. See CLI configure-sources.

Section reference

Vault file (llmwiki.json)

<vault-root>/llmwiki.json holds the settings that belong to the wiki itself rather than to this install. It sits at the vault root beside wiki/, raw/ and the vault's llmwiki-state.json, and it is meant to be committed: copying, sharing, or publishing the vault carries it along. The example wiki shipped with the project has one — demo/llmwiki.json.

Two similarly-named JSON files, so keep them apart:

lint.disabled_rules

Names the quality checks that do not apply to this wiki. A disabled rule is never constructed, never runs, and contributes no findings — and is named as skipped in every report, whether or not anything was found, so a short report can never be mistaken for a clean one. It is on/off only: a wiki cannot re-grade a finding's severity, and cannot switch a rule off for part of itself.

Two shapes are accepted. A bare list, when you do not want to record a reason:

{
  "lint": {
    "disabled_rules": ["content_freshness"]
  }
}

Or an object mapping each rule to a written reason — preferred, because the reason is what you or a reviewer will read six months from now:

{
  "lint": {
    "disabled_rules": {
      "content_freshness": "This wiki is a committed snapshot, so this check measures elapsed calendar time rather than a defect in the pages."
    }
  }
}

Rule names are the ones the report prints as ## <rule> headings; the full list is in reference/cli.md, and any run that rejects a name prints the valid ones.

Keep a reason to a sentence or two. It is printed verbatim, on one line of every report the wiki produces, so a paragraph-length reason wraps badly in a CI log.

Worked example

Write the file at the vault root and run the check:

cat > /path/to/vault/llmwiki.json <<'JSON'
{
  "lint": {
    "disabled_rules": {
      "content_freshness": "This wiki is a committed snapshot, so this check measures elapsed calendar time rather than a defect in the pages."
    }
  }
}
JSON

python3 -m llmwiki lint --vault /path/to/vault

The report names what it skipped, above the findings:

  scanned 3 pages
  2 issues: 1 errors, 1 warnings, 0 info
  skipped 1 of 17 rules (disabled in llmwiki.json):
    - content_freshness — This wiki is a committed snapshot, so this check measures elapsed calendar time rather than a defect in the pages.

## index_sync (1)
  [error] index.md: page 'sources/demo-source.md' not listed in index.md

## link_integrity (1)
  [warning] entities/Widget.md: broken wikilink [[Gadget]]

lint --json carries the same declaration under disabled_rules, which is always present — empty when the wiki declares nothing — so a consumer can read it without probing for the key:

{
  "summary": { "error": 1, "warning": 1 },
  "issues": [
    { "rule": "index_sync", "severity": "error", "page": "index.md", "message": "page 'sources/demo-source.md' not listed in index.md" },
    { "rule": "link_integrity", "severity": "warning", "page": "entities/Widget.md", "message": "broken wikilink [[Gadget]]" }
  ],
  "total_pages": 3,
  "disabled_rules": {
    "content_freshness": "This wiki is a committed snapshot, so this check measures elapsed calendar time rather than a defect in the pages."
  },
  "ran": ["frontmatter_completeness", "index_sync", "link_integrity", "orphan_detection"]
}

ran names the checks that actually produced the report, in registry order. disabled_rules covers only the narrowing the wiki declared; --rules (and the MCP tool's rules argument) narrows a run without declaring anything, so without ran a short report is indistinguishable from a full one.

A declaration that cannot be honoured is an error, never a silent skip

None of these fall back to "this wiki declares no opt-outs". A declaration nobody can read might be switching every check off, so reporting the wiki as clean would be a guess dressed up as a result — and a typo must never leave a check switched on that you believed you had switched off.

Switching a check off hides real findings

This is not a noise filter. A disabled rule does not run, so anything it would have found is simply absent from the report — and the report will look shorter and healthier for it. Reserve the declaration for checks that cannot apply to a wiki, not for checks that are merely inconvenient.

content_freshness on a committed snapshot is the legitimate case, and the one the shipped example uses. That check asks whether a page has gone untouched for three months; on a frozen, published copy the answer is decided by the calendar rather than by anything wrong with the pages, so the check would redden on a date rather than on a defect. Where staleness is real, refreshing the content is the honest cure — switching the check off only removes the reminder that the content has aged.

Environment variables

Vault content root is vault.default_path in config.json. The removed LLMWIKI_ROOT env var is no longer read.

.llmwikiignore

Gitignore-style file at the repo root. One pattern per line. Sessions matching any pattern are skipped during sync.

# Skip a whole project
confidential-client/*

# Skip anything before a date
*2025-11-*

# Skip a specific session
ai-newsletter/2026-04-04-*secret*

# Comments start with #
# Blank lines are ignored

Per-adapter configuration

Each adapter can be configured in the adapters section of config.json. The key must match the adapter's registry name.

Every adapter accepts optional since (YYYY-MM-DD or "all") — see Sync lookback. Bare llmwiki sync runs every ingest-ready coding-agent adapter whose store is present and not explicitly disabled. Notes/export intake needs enabled: true (#326). Run llmwiki configure-sources to probe paths, set lookbacks, and write settings. Support map: multi-agent-setup.md.

Example:

{
  "filters": {
    "since": "2026-07-31"
  },
  "adapters": {
    "copilot_chat": {
      "roots": ["/custom/path/to/vscode/workspaceStorage"]
    },
    "openclaw": {
      "since": "all"
    }
  }
}