Configuration
Every tuning knob in llmwiki, explained.
Config file
Copy the default config and edit it:
cp examples/sessions_config.json config.json
config.json is gitignored so your settings stay local. The converter auto-loads it if present.
Minimal config:
{
"redaction": {
"redact_username": false,
"real_username": "your-unix-username",
"replacement_username": "USER"
}
}
Replace
your-unix-usernamewith the output ofwhoami. Withredact_username: truethe converter uses it to scrub paths like/Users/<name>/…or/home/<name>/…before writing toraw/; the defaultfalsekeeps real paths for a private vault.
Full schema
{
"filters": {
// Skip sessions with a record younger than this many minutes.
// Prevents the converter from reading a .jsonl mid-write.
"live_session_minutes": 60,
// If non-empty, only convert projects whose slug matches one of these.
"include_projects": [],
// Skip projects whose slug contains one of these substrings.
"exclude_projects": [],
// Record types to drop entirely (noise / hook progress / queue ops)
"drop_record_types": [
"queue-operation",
"file-history-snapshot",
"progress"
],
// Skip automated / headless agent launches (default on). Claude: SDK
// entrypoint / promptSource; Cursor Agent CLI: subagentInfo or
// approvalMode=auto-review; OpenClaw: never skipped. Applies at ingest
// and synthesis. See docs/multi-agent-setup.md § automated.
"exclude_headless": true,
// Skip transcripts with zero user messages and zero tool calls (default
// on). Aborted launches and other empty rows have nothing to synthesize
// and inflate harvest citation counts. Applies at ingest and synthesis.
"exclude_empty": true,
// Skip sessions whose cwd is a throwaway temp dir (/tmp, /var/folders,
// …). Default OFF: a git worktree under /tmp is often real work, so we
// don't silently drop it. Turn on only if your temp dirs hold nothing
// but e2e/scratch junk.
"exclude_temp_cwd": false
// Optional shared sync lookback as absolute YYYY-MM-DD (#192).
// Omit (default) = unlimited history. Per-adapter override:
// adapters.<name>.since as YYYY-MM-DD, or "all" for no date gate.
// CLI --since overrides both for one run. See configuration-reference.md.
// "since": "2026-07-31"
},
"redaction": {
// false (default): raw/ keeps real home paths (private vault).
// true: paths like /Users/<you>/ become /Users/USER/ — use before
// sharing raw/ or publishing the site. Token/email redaction always runs.
"redact_username": false,
// Your OS username. Auto-detected from $USER if left empty.
"real_username": "",
// What to replace real_username with.
"replacement_username": "USER",
// Additional regexes to redact (Python re syntax).
// Anything matching → "<REDACTED>".
"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": {
// Max chars per tool result before truncation.
"tool_result_chars": 500,
// Max lines from a Bash stdout before truncation.
"bash_stdout_lines": 5,
// Max lines from a Write tool content preview.
"write_content_preview_lines": 5,
// Max chars per user prompt.
"user_prompt_chars": 4000,
// Max chars of assistant text rendered in the markdown body.
"assistant_text_chars": 8000
},
// Drop <thinking> blocks from assistant messages entirely.
// These are verbose and often redundant with the visible response.
"drop_thinking_blocks": true,
// Per-adapter config. Optional since: YYYY-MM-DD override or "all" (no date gate).
"adapters": {
"obsidian": {
"vault_paths": ["~/Documents/Obsidian Vault"],
"exclude_folders": [".obsidian", "Templates", "_templates", ".trash"],
"min_content_chars": 50
}
}
}
Synthesis backend
llmwiki synth turns each raw session/document into a wiki/sources/ page. Which LLM (if any) writes those pages is picked by synthesis.backend in config.json. Per-engine settings live in nested blocks (synthesis.claude, synthesis.cursor_cli, synthesis.ollama); legacy flat claude_* / Ollama keys still work as fallbacks. Override the backend for one run with llmwiki synth --backend <name> (does not write config.json).
{
"synthesis": {
// "dummy" (default) | "ollama" | "claude" | "cursor_cli"
"backend": "cursor_cli",
"cursor_cli": { "model": "composer-2.5", "timeout": 180 },
"claude": { "model": "sonnet", "lean": true },
"ollama": { "model": "llama3.1:8b" }
}
}
| Backend | What it does | Needs |
|---|---|---|
dummy |
Canned stub page: metadata summary, one [[ProjectEntity]] link, plain-text ## Raw Mentions. For previews/tests. |
nothing |
ollama |
Local LLM over the Ollama HTTP API. Configure synthesis.ollama.{model,base_url,timeout,max_retries,usable_body_chars,context_window_tokens} (flat legacy keys still work for the first four). |
running ollama serve |
claude |
Synchronous claude -p CLI calls (#16). Prefer nested synthesis.claude.{model,path,timeout,lean,effort,usable_body_chars,context_window_tokens}; flat claude_* keys remain as fallbacks. Default model sonnet. llmwiki install-automation pins absolute synthesis.claude.path when unset so systemd catch-up still finds the binary (#275). |
claude on $PATH (or synthesis.claude.path / claude_path) |
cursor_cli |
Synchronous Cursor Agent CLI (agent -p / cursor-agent) (#230). Nested synthesis.cursor_cli.{model,timeout,usable_body_chars,context_window_tokens} only (default model composer-2.5). Binary from $PATH — no path key. Lean flags: -p, --mode ask, --sandbox enabled, --allowed-tools truncated_tool_call (shrinks tool schemas; still no empty system-prompt / empty-MCP switch). |
agent or cursor-agent on $PATH, authenticated |
Not the same as session ingest. synthesis.backend: cursor_cli is the generator that writes wiki pages. The contrib adapters cursor_cli (Agent CLI chats under ~/.cursor/chats/) and cursor_ide (IDE Composer / state.vscdb) only ingest transcripts into raw/ — configuring one does not select the other.
Choosing the document body budget
A long document is stored whole and chunked in memory at synth time; each chunk is one backend call, and the outputs are stitched into one wiki page. The chunk size is the backend's usable body budget — how many raw-body characters one call can carry. It applies to documents only: session and evidence bodies keep the fixed 8,000-character send cap.
Each backend block (synthesis.claude, synthesis.cursor_cli, synthesis.ollama) takes two optional keys:
| Key | Meaning |
|---|---|
usable_body_chars |
Characters per document chunk, used as-is. Set this when you know exactly what you want. |
context_window_tokens |
The model's context window. The budget is usable_tokens × 2.05 characters, where usable_tokens = window − scaffolding − 2,000 prompt − 2,600 output − working margin (scaffolding and margin per backend class, table below). The 2.05 ratio is the measured transcript ratio, which is on the small side of real prose, so the budget errs toward fitting. There is no upper cap on a derived budget. The 1,000-character floor applies only to what you set yourself: a context_window_tokens too small for the reserves (or an explicit tiny usable_body_chars, used as-is). |
An agent-backed call spends much of its window on things other than your body, so the derived budget reserves them per backend class:
| Backend class | Scaffolding | Working margin | Example: 32,768 / 200,000-token window |
|---|---|---|---|
Ollama (/api/generate) |
~500 tokens | max(2,048, 10% × window) |
50,003 / 358,545 characters |
Claude, lean on (default) |
890 tokens | max(8,192, 25% × window) |
39,126 / 296,245 characters |
Claude, lean off (synthesis.claude.lean: false / claude_lean: false) and Cursor CLI (never lean) |
35,000 tokens | max(16,384, 35% × window) |
1,000 (floor, you set a tiny window) / 185,320 characters |
The scaffolding is the per-call agent context from reference/synthesis-cost.md; the margin is headroom for the agent's own reasoning and tool use. An explicit usable_body_chars is used as-is — none of these reserves apply to it.
Resolution order — first hit wins:
usable_body_chars;context_window_tokens;- what the backend knows about its model — Claude:
haiku,sonnetandopus(alias or full id containing the name) are 200,000 tokens, ≈400,000 characters; Ollama: the model'snum_ctxread from/api/show(Modelfile parameter), capped by its trained context length — a trained maximum alone is not adopted, because the server does not load it by default; Cursor:composer-2.5andcomposer-2.5-fastare 200,000 tokens (Cursor does not publish Agent CLI windows, so any other id gets the assumed window below); - the assumed window — 200,000 tokens for the agent backends (Claude with a custom model id, Cursor), which gives ≈296,000 characters for lean Claude and ≈185,000 for non-lean Claude and Cursor; 8,192 tokens for Ollama when its window cannot be detected, which the Ollama reserves leave at ≈2,100 characters. Set
context_window_tokens(orusable_body_chars) when your model's real window is smaller or larger.
The 1,000-character floor is for an explicit tiny value only. A derived default (assumed, alias, or detected window) never lands on it silently: if a window cannot carry the per-call reserves at all, llmwiki logs a warning and uses 8,000 characters (the session cap) for the agent backends, or 1,000 for Ollama, whose window is genuinely that small.
Ollama page calls send options.num_ctx only when the window came from config (context_window_tokens / usable_body_chars) or a Modelfile num_ctx from /api/show. The assumed 8,192-token budget fallback is not forced onto the server, so a larger server-level default (OLLAMA_CONTEXT_LENGTH or the runtime default) is left alone. An explicit usable_body_chars larger than the window raises the requested num_ctx to fit, scaffolding and margin included.
Claude and Cursor per-page timeout is the baseline for a session-sized body (≤ 8,000 characters). Larger document chunks scale that timeout linearly with body size so a lean-Claude ~296k-char chunk can finish under the default 180s unit instead of failing the whole document on the first slow call. Raise timeout if even the scaled budget is tight; lower usable_body_chars if a model degrades on long input.
How to choose: leave both unset unless a run is too slow or too fragmented. Raise context_window_tokens to your model's real window to get fewer, larger calls. A document is capped at 512 KiB of Markdown regardless of budget — add rejects a larger one. See reference/synthesis-cost.md for the cost side.
{
"synthesis": {
"backend": "ollama",
"ollama": { "model": "llama3.1:8b", "context_window_tokens": 32768 }
}
}
Claude calls run in lean mode by default: tool schemas, MCP servers, skills, CLAUDE.md, and the agent system prompt are stripped from each invocation, since a synthesis call only reads stdout and can't use any of them. That is ~9x cheaper per page, measured — see reference/synthesis-cost.md for the numbers and for why the Claude default model is sonnet rather than a cheaper model. Set "lean": false under synthesis.claude (or flat "claude_lean": false) to opt out. Cursor's lean set is ask + sandbox plus a tiny --allowed-tools allowlist (~25–30% less prompt than the full tool catalog on Composer); the agent system prompt still cannot be emptied for normal accounts.
The old agent / agent_delegate backend (pending-prompt files + --list-pending / --complete) was removed in v1.4.0 — use claude or cursor_cli instead.
Sanity-check what's active and what a run would cost:
llmwiki synth --check # prints the resolved backend + availability
llmwiki synth --estimate # cached-vs-fresh token + dollar estimate (+ candidate backlog)
llmwiki synth --backend cursor_cli --estimate # one-run backend overlay (no config write)
llmwiki synth --sessions-only # pending sessions only (skip docs)
llmwiki synth --docs-only # pending docs only (skip sessions)
Synthesis is incremental. <vault>/llmwiki-state.json (synth.files) records an mtime per raw file; a nightly sync/synthesize only processes files that are new or changed since the last run — the daily LLM bill is proportional to new content, not to corpus size. --force re-runs everything (use after switching backends, e.g. to replace dummy-stub pages with real ones — pages with only stub links produce a topic graph with no edges).
Downgrade protection: dummy is the resolved default when synthesis.backend is unset (or a typo — unknown values warn and fall back), so a --force run in that state used to overwrite every real page with link-free stubs and silently empty the knowledge graph. The pipeline now refuses that downgrade: stub output is never written over a real page, even under --force — such pages are reported as protected in the run summary. To deliberately re-synthesize a real page, delete it first. (An unavailable backend does not fall back — the run aborts with an error.)
Environment variables
| Variable | What it does |
|---|---|
LLMWIKI_CONFIG |
Override the config file path. Defaults to ./config.json then examples/sessions_config.json. |
Vault content root is vault.default_path in config.json (not an env var). The removed LLMWIKI_ROOT env var is no longer read.
CLI flags
llmwiki sync
python3 -m llmwiki sync [options]
--adapter <name...> Only run the named adapter(s); default: all available
--since YYYY-MM-DD One-run lookback (overrides filters.since / adapters.*.since)
--project <substring> Only sync projects whose slug contains this substring
--include-current Don't skip live (<60 min) sessions
--force Ignore the state file; reconvert everything
--fail-on-errors Exit 1 if any file fails to convert
--vault PATH Write into an external vault (also sets active state file)
--status Show last-sync + counters + quarantine (no sync)
Per-file conversion errors do not fail the run by default: each one is
counted in the summary, recorded in llmwiki-state.json quarantine
entries, and visible via llmwiki sync --status, while the rest of the
corpus still converts. Pass --fail-on-errors for a hard gate (CI,
scripted pipelines that must not proceed past a partial sync).
There is no sync --dry-run — use add --dry-run for document intake
previews, or inspect with sync --status / synth --estimate.
Durable lookback (optional): set filters.since to an absolute YYYY-MM-DD in config.json, or adapters.<name>.since to a date / "all" (no date gate for that source). Unset = unlimited history. llmwiki configure-sources asks the shared date first (default today−30) and shows Sessions · Earliest · In last 30 days per source before Enable. See configuration-reference.md — Sync lookback.
llmwiki build
python3 -m llmwiki build [options]
--out <dir> Output directory; default: ./site
--synthesize Call the `claude` CLI once to generate an Overview
--claude <path> Path to the claude binary; default: /usr/local/bin/claude
--local-root <path> Value shown in place of a session's stored home directory;
default: this machine's home directory
llmwiki init
No options. Scaffolds raw/, wiki/, site/ and seeds wiki/index.md, wiki/log.md, wiki/overview.md.
llmwiki adapters
No options. Lists every registered adapter and whether its session store is present on the current machine.
.llmwikiignore
Gitignore-style file at the repo root. One pattern per line. Sessions matching any pattern are skipped during sync.
Example:
# Skip a whole project
confidential-client/*
# Skip anything before a date
*2025-11-*
# Skip a specific session
ai-newsletter/2026-04-04-*secret*
Adapter configuration
Claude Code
Default session store: ~/.claude/projects/
Override via the adapter config block (above).
Obsidian
Default vault locations checked:
~/Documents/Obsidian Vault~/Obsidian
Override in config.json:
{
"adapters": {
"obsidian": {
"vault_paths": [
"~/Documents/Obsidian Vault",
"~/work/second-vault"
],
"exclude_folders": [".obsidian", "Templates"],
"min_content_chars": 100
}
}
}
Files smaller than min_content_chars are skipped (mostly empty notes).
Codex CLI
Production core adapter. Default roots: ~/.codex/sessions and ~/.codex/projects. Override with adapters.codex_cli.roots. Included on a bare llmwiki sync when a root exists. Full detail: adapters/codex-cli.md.
Which agents + what “automated” means
Support map, core vs contrib (--adapter opt-in), Cursor Agent CLI vs IDE, and per-source headless rules: multi-agent-setup.md.
Changing the theme
Theme colours live in llmwiki/build.py inside the CSS string constant, under the :root block. The main tokens:
--accent: #7C3AED; /* primary accent (purple) */
--accent-light: #a78bfa;
--accent-bg: #f5f3ff;
Change these and rebuild. The dark-mode variants auto-derive unless you override them too.
MCP tool timeouts
Long-running MCP tools (wiki_add, wiki_sync) default to a 120-second wall-clock budget. Override per tool under mcp.tool_timeouts in config.json:
{
"mcp": {
"tool_timeouts": {
"wiki_add": 120,
"wiki_sync": 120
}
}
}
See reference/mcp.md and the configuration reference table rows.