llm-wiki-kit

llm-wiki-kit is a local-first, hook-based memory runtime for Codex, Claude Code, and opencode. It keeps durable project knowledge in a searchable Markdown wiki and brings relevant context back into later coding sessions.

It is an agent-memory layer, not another model provider: your coding agent still handles model calls and code generation.

Why llm-wiki-kit

• Project-local Markdown: durable knowledge stays readable, editable, and versionable under llm-wiki/.
• Useful context without a capture ritual: hooks surface relevant memory and search results during normal agent work.
• Answer-first capture: routine tasks stay transient. Explicit documentation requests and reusable conclusions can enter a review queue instead of being promoted automatically.
• Traceable retrieval: search returns relevant page sections with file references; lint and eval help maintain the knowledge base.

Supported Agents

| Agent | Integration | |---|---| | Codex | Native hooks | | Claude Code | Native hooks | | opencode | Managed plugin bridge; some hook events are experimental. Integration details |

The goal is not to make users run ingest or record commands. Once installed, the hooks make project memory available during ordinary supported-agent work, while durable knowledge remains in Markdown files you can inspect and edit.

Language Behavior

llm-wiki-kit is designed for mixed Korean and English teams:

• Korean user prompt -> Korean hook guidance.
• English user prompt -> English hook guidance.
• Codex synthetic plan execution prompts — specifically the exact phrase Implement the plan. — are treated as neutral, so they reuse the last real session language or project preference instead of forcing English.
• Project .kit-state.json may set preferredLanguage to ko or en for neutral prompts.
• If there is no clear current prompt language, Claude Code settings.json language is used when present.
• If that setting is missing, local CLAUDE.md and AGENTS.md language signals are used.
• The fallback is English.
• Commands, paths, code identifiers, package names, logs, and original error text are not translated.

Codex and Claude Code users do not need different commands for Korean or English projects.

Quick Start

npm install -g llm-wiki-kit@latest
llm-wiki install --workspace /path/to/project --profile standard
llm-wiki doctor --workspace /path/to/project

Restart active Codex or Claude Code sessions after installation. For opencode, start a new session so its plugin bridge loads.

Install also syncs bundled Codex and Claude Code skills named llm-wiki-* into $CODEX_HOME/skills or ~/.codex/skills, and into ~/.claude/skills. Existing same-name user skills are preserved, and kit-managed skills are updated only when they were not locally edited, except obsolete public llm-wiki skills that the kit removes from active provider skill roots. Use --no-codex to skip Codex hooks and skills, --no-claude to skip Claude hooks and skills, --no-opencode to skip the opencode bridge plugin, and --no-skills when you want to install hooks without writing either skill root.

Native Windows

Native Windows is supported through the npm-generated llm-wiki.cmd shim. Use PowerShell or Windows Terminal with Node.js 20+:

npm install -g llm-wiki-kit@latest
llm-wiki install --workspace C:\path\to\project --profile standard
llm-wiki doctor --workspace C:\path\to\project

On Windows, llm-wiki install does not create a Unix-style ~/.local/bin symlink. It verifies the npm shim on PATH, installs Codex hooks with commandWindows, and writes Claude Code hooks with a Windows-safe node.exe <bin> command. Restart Codex and Claude Code after installation.

Use WSL2 instead when your repository and tooling already live in Linux. Native Windows support is for Windows-hosted projects and the native Codex/Claude Code surfaces.

The default install mode is npm global install. On servers where the global npm prefix is root-owned, use sudo:

sudo npm install -g llm-wiki-kit

If sudo is not available, use a user-local npm prefix as a fallback:

npm config set prefix "$HOME/.local"
npm install -g llm-wiki-kit

For development or pre-publish smoke tests, build one concrete tarball and use the isolated release verifier. Do not install a prepublish candidate globally or point it at a real workspace:

candidate_dir="$(mktemp -d)"
npm pack --json --pack-destination "$candidate_dir"

First use the isolated Linux home/prefix procedure in docs/manual.md. Then transfer that same tarball to a native Windows host and run PowerShell 7 there:

pwsh -NoProfile -File C:\work\llm-wiki-kit\scripts\windows-runner\verify-release.ps1 -Mode Tarball -PackageSpec C:\Temp\llm-wiki-kit-<version>.tgz -ExpectedVersion <version>

What Gets Created

Each project gets a local wiki:

llm-wiki/
├── .kit-state.json
├── raw/
├── wiki/
│   ├── index.md
│   ├── memory.md
│   ├── log.md
│   ├── sources/
│   ├── concepts/
│   ├── decisions/
│   ├── architecture/
│   ├── debugging/
│   ├── context/
│   └── queries/
├── outputs/
│   ├── questions/
│   ├── reports/
│   ├── exports/
│   └── maintenance/
├── evals/
└── procedures/

raw/ is the immutable or redacted evidence layer. General source material belongs in raw/sources/; older raw/inbox/, raw/assets/, top-level llm-wiki/sources/, top-level llm-wiki/templates/, and wiki/entities/ folders are migrated during maintenance. wiki/ is the LLM-maintained knowledge layer. wiki/memory.md is the short hot index injected into hook context before deeper search results. outputs/ stores live Q&A, requested reports, and pending wiki maintenance candidates. .kit-state.json records which runtime version last applied managed templates to the project. Text written by the kit is normalized to NFC so Korean content stays composed (filenames are English ASCII kebab-case per N2).

Normal Use

Use Codex or Claude Code normally, or use opencode with the installed plugin bridge.

The installed hooks:

• inject functional compact context at session start, instructions loaded, and prompt submit. The hook still uses wiki/memory.md, wiki/index.md, relevant wiki search results, maintenance signals, update status, and any compact recovery packet; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
• automatically choose Korean or English hook guidance from the current real user prompt, keep Codex synthetic plan execution prompts neutral, then fall back to remembered session language, project preferredLanguage, Claude Code language, local CLAUDE.md/AGENTS.md, and English.
• operate only in projects that were explicitly initialized with llm-wiki bootstrap, install, or migrate; routine hooks do not bootstrap arbitrary working directories
• record small redacted raw event envelopes and per-turn state
• capture handoff-focused checkpoints only when a captured user question has explicit durable intent, a structured durable conclusion, or a durable wiki/procedure update
• attach safe evidence_refs candidates to generated queue items when changed files or verification commands are available
• before compaction, classify the current turn and save a checkpoint only for explicit durable requests, structured durable conclusions with required evidence, or durable wiki/procedure updates; simple work stays in transient runtime state
• after compaction, keep summaries transient; if pre-compact preservation failed, prepare a recovery packet for the next legal model-visible context hook
• allow tool calls to proceed without secret/PII-based hook blocking
• update chunked llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md style archives only for handoff-worthy durable checkpoints
• avoid automatic wiki/queries/ and wiki/decisions/ promotion in the default answer-first mode
• queue durable cleanup candidates for explicit documentation requests, structured durable conclusions, or queue-worthy recovered stale turn state that were not reflected in durable wiki/procedure files
• recover stale per-turn state into that queue on the next session start or prompt submit only when the buffered turn is queue-worthy
• nudge the active LLM to batch-review accumulated candidates and fold only explicit, repeated, or clearly reusable facts into existing wiki pages
• report stale managed rules/templates during normal hooks and apply changes only through explicit install/update/post-update/maintenance commands
• provide bundled Codex and Claude Code skills for setup, query, lifecycle, and export workflows without replacing user-created same-name active skills except obsolete public llm-wiki skill entries

Korean and English explicit-durable detection are intentionally asymmetric, not parallel. English forms require an object (remember this, record the decision); Korean action verbs (추가해/정리해/남겨둬/기억해/메모해/기록해) count as explicit durable requests only when a wiki/document/page/memory context token (위키/wiki/문서/페이지/메모리) accompanies them, so ordinary work requests like 이 기능 추가해줘 stay transient. The Korean documentation noun/verb 문서화/문서화해 is self-gating (it carries the documentation context itself) and therefore matches without a separate context token; this is a deliberate divergence from the English document verb, which still requires an object. Edge-case forms are not guaranteed to be symmetric across the two languages. Short Korean requests are preserved as long as they contain at least three Hangul syllables.

Only Korean and English are supported. Prompts in other CJK scripts (for example Japanese or Chinese, which contain no Hangul) are treated as English by the fallback chain, with no warning. This is by design, not a bug.

If you need to think about saving every answer manually, the setup has failed. If wiki maintenance delays the actual answer, the setup is being used wrong. The kit uses the answer-first capture mode: simple answers, status checks, and ordinary tool-heavy work stay out of durable wiki and live Q&A, while explicit durable requests, structured durable conclusions, and detected wiki/procedure updates are archived and queued for batch review. Pre-compact preservation always lets compaction proceed. LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off suppresses failure warnings; limited and soft both emit a non-blocking warning if checkpoint storage fails. The hook never reads transcript_path; checkpoints and recovery packets are built only from bounded, redacted turn state captured by hook events.

Operational Commands

Most users should not need these during daily Claude Code/Codex work. They exist for install, update, diagnostics, and agent-side maintenance.

• Install/update: llm-wiki install, llm-wiki update, llm-wiki post-update, llm-wiki projects
• Structure & legacy: llm-wiki bootstrap, llm-wiki migrate, llm-wiki fork
• Diagnostics: llm-wiki doctor, llm-wiki status, llm-wiki version
• Manual: llm-wiki manual
• Agent maintenance helpers: llm-wiki search, llm-wiki context, llm-wiki memory, llm-wiki lint, llm-wiki consolidate, llm-wiki maintenance, llm-wiki eval, llm-wiki export
• Live Q&A archive helper: llm-wiki archive-questions --workspace <project> [--date YYYY-MM-DD] [--dry-run]
• Page scaffold: llm-wiki new <slug> --workspace <project> [--type <type>] [--title "<title>"] [--dir <wiki/...>] [--dry-run] — create a curated page with a complete, lint-clean frontmatter stub (required fields + keywords seeded from the title) so no field is missed on creation.
• Internal hook targets: llm-wiki hook codex|claude|opencode <EventName>
• Cleanup: llm-wiki uninstall

llm-wiki manual prints the full package manual from docs/manual.md. Keep that document current when adding public commands, options, hook behavior, directory conventions, security policy, or update flows.

llm-wiki status is an offline consistency check. It reports the installed runtime version, hook targets, whether the llm-wiki command on PATH resolves to the current runtime, whether bundled Codex and Claude Code skills are current at each provider root, whether the current workspace has the current managed templates applied, how many rules are auto-updateable, how many managed-looking rules need agent cleanup, and how many wiki maintenance items are pending.

llm-wiki update --check [--to <version-or-tag>] is the online update check. It compares the installed package version with the npm registry target without changing files, and reports an available update only when the target version is newer than the installed version.

llm-wiki update upgrades the global npm package when npm has a newer target, reinstalls the hook entries, and reapplies safe managed template updates across known project roots. Before installing, it checks whether npm root -g points at the active runtime package root; after installing, it verifies the active runtime and post-update runtime reached the registry target. If either check fails, it exits nonzero and prints the exact runtime/npm roots plus the manual install/post-update commands to run. If npm install -g fails with EACCES or another permission error, update preserves npm's original error and explains that only the package install should use privilege escalation, followed by post-update or update as the normal Codex/Claude user. If the installed runtime already satisfies the registry target, it prints an already-current result, skips only npm install -g, and still runs post-update maintenance. The text output separates npm install: skipped (runtime already current) from post-update: ran, then reports how many projects were processed and how many managed templates changed, skipped, or stayed unchanged. It also prints project details lines that show each processed directory plus changed paths, skipped path:reason entries, and unchanged counts. Use --current-only when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten. The command prints step progress to stderr, including registry lookup, npm root/prefix checks, npm install, post-update, and project discovery. Use --timeout-ms <ms> to bound external commands and --max-dirs <n> to bound project discovery under large or slow roots such as WSL /mnt/* trees.

Installed npm runtimes also perform a cached update notice check from hooks while the user works. This does not install anything automatically. When a newer npm release is detected, Codex and Claude receive the same passive runtime update status in hook context: current runtime, npm registry target, and the manual command to use when the user asks for update or maintenance work. It is not an instruction to interrupt the current answer or to sell the update to the user. The cache is scoped to the npm command used for lookup so test/fake npm checks do not leak into normal hook sessions. Set LLM_WIKI_KIT_UPDATE_NOTICE=0 only when diagnosing or suppressing that status block.

llm-wiki post-update --workspace <project> reapplies the current runtime's hook entries, bundled Codex and Claude Code skills, and safe managed template updates without running npm install -g. Use post-update --all --workspace <search-root> to reapply templates across discovered project roots. Add --no-codex to skip Codex hooks and skills, --no-claude to skip Claude hooks and skills, or --no-skills to inspect/update hooks/templates without writing either skill root.

llm-wiki search "<query>" is the agent-facing search surface. Hits carry a wiki/path.md#section ref plus a file-accurate L<start>-L<end> line range, so agents read just the matched section with their native Read tool instead of whole pages. Single short body-only matches are dropped as retrieval noise (rollback: LLM_WIKI_KIT_SEARCH_FILTER=0; inspect with --show-filtered), and a no-match exits 0 with an explicit outcome line — retry once with the suggested vocabulary (copy-pasteable command included), then state that the wiki has no record and answer normally. --json emits a versioned redacted schema; --all-projects searches sibling project wikis.

llm-wiki context "<query>" prints the full debug view of the layered context sources used by hooks. Hook injection may render those sources as functional compact context for Codex and Claude, but this CLI stays verbose so maintainers can inspect retrieval, section refs, snippets, memory, index, expansion behavior, context budget metadata, rankReason, matchedFields, scoreBreakdown, confidenceLevel, confidenceReasons, visibilityReason, and evidenceRefs. Wiki pages are indexed by Markdown section, and standard metadata plus scalar values under extensions are searchable; extension matches have a deliberately small boost. Results remain page-compatible by keeping the best section hit per page. The text formatter adds a short why selected line for each hit; hook compact context deliberately omits that extra detail and uses short wiki/path.md#section refs. Use --budget-chars <n> for reviewable context packs, --compact --max-context-chars <n> to preview hook-sized output, and --show-hidden-reason to inspect pages excluded by visibility policy. Daily use should rely on hook injection. By default, pages with memory_type: episodic and episodic query/context/session roles are excluded unless promoted with durable metadata; use --include-episodic only when debugging old automatic records. Archived or superseded pages are hidden unless --include-archived is requested, while stale pages remain searchable with lower score.

Bundled Codex and Claude Code skills:

• llm-wiki-setup
• llm-wiki-query
• llm-wiki-lifecycle
• llm-wiki-export
• llm-wiki-keywords

The high-frequency skills are intended to trigger from ordinary user language, not only explicit commands. Read-only memory questions should route to llm-wiki-query. Durable "remember/document/save/report this" requests, cleanup, queue review, archive, consolidate, lint/eval hygiene, and stale policy/document follow-through should route to llm-wiki-lifecycle. Lifecycle evaluates internal document, maintain, and upgrade-docs mode flags independently: durable persistence defaults to document + maintain, while upgrade-docs runs only on clear update, migration, lint, or old-policy signals.

llm-wiki memory [query] is the review surface for the active wiki. It reports current memory.md focus bullets, durable entry points, active workspace/wiki root, optional retrieval hits for a query, maintenance queue state, and lint/eval health. It is read-only; queue changes still go through llm-wiki maintenance.

llm-wiki lint checks wiki health and detects outdated managed rules from older kit versions. Curated pages are expected to carry title, type, status, memory_type, and last_updated; a missing required field is reported as a warning (and auto-filled on changed durable pages during maintenance), while an invalid value (for example an unknown type or status) is an error. Optional standard fields have runtime defaults, while project-specific metadata belongs under typed extensions with lowercase snake_case keys. It validates optional evidence_refs entries with the prefixes file:, cmd:, raw:, and url:. It also warns when memory.md, index.md, or log.md approaches its budget, a hand-authored memory.md current-focus bullet exceeds the density guidance (memory-focus-bullet-density), importance: 5 is saturated, wiki page count reaches the growth review threshold, hidden episodic pages accumulate, or stale/archived pages lack discoverability. This threshold is a health signal, not a search truncation limit. Semantic content edits should revise last_updated and any verification/evidence metadata whose meaning changed; formatting-only normalization is not verification. Lint does not enforce the last_updated revision mechanically (there is no baseline diff); it is agent guidance surfaced as a health signal. For a single page after authoring, llm-wiki lint <file> --workspace <project> --fail-on-warning --suppress-auto-fixable is an on-demand spot-check (page-local rules plus link resolution; --fail-on-warning fails on warnings too; --suppress-auto-fixable hides frontmatter issues the next Stop hook auto-normalizes); it is no longer required after every write. By default the lint gate is batched: the kit counts durable wiki/** and procedures/** page changes since the last corpus lint and prompts you after N changes (default 10, configurable via lintBatchThreshold in .kit-state.json); run llm-wiki lint --workspace <project> when prompted or before reporting a documentation task complete, and a corpus lint resets the counter. Per-path lint exceptions live in llm-wiki/.kit/lint-exceptions.json (absent = none): each entry suppresses one lint code on a paths glob with a required reason and optional expires; secret-detection codes (secret-like-content family) demote to warning instead of silencing (also under global lintSeverity: off), corpus-integrity codes cannot be excepted, and llm-wiki lint --show-suppressed re-shows dropped issues.

llm-wiki consolidate refreshes only generated marker blocks in wiki/memory.md, wiki/index.md, and wiki/queries/archive-index.md. It balances the memory map across page types, caps generated memory at 12 entries/8KB, caps the index at 80 entries/8 per type/24KB, and caps the archive-index at 16KB; it reports shown and omitted counts. The generated archive-index.md is an episodic page that collects archived/superseded wiki pages plus outputs archives (live Q&A, reviewed maintenance) so they stay findable after archival — search it with llm-wiki context "<query>" --include-episodic. Lint warns at 12KB for memory.md, 24KB for index.md/log.md, and surfaces 16KB / 32KB as upper health thresholds (and flags memory-focus-bullet-density when a hand-authored current-focus bullet exceeds 400 chars); these are warning-level health signals that feed maintenance review, not lint-failing errors (structural problems like broken links, invalid enum values, secret-like content, and YAML errors are the lint errors). Generated maps keep durable non-archived pages and skip episodic/stale/archived/superseded pages. It is an agent maintenance helper, not a command users should run after every turn.

llm-wiki maintenance --workspace <project> --normalize-frontmatter --dry-run previews explicit YAML normalization. Applying it merges legacy source_id into source_ids, fills inferable required core fields, removes redundant defaults, and moves unknown top-level fields under extensions; ambiguous collisions and invalid extension keys are left untouched for review. Hooks never run this normalization automatically.

llm-wiki maintenance --workspace <project> --derive-tags [--dry-run] backfills Obsidian-style tags (type/<type>, memory/<memory_type>, status/<status>) from existing metadata. Preview with --dry-run first. Hooks never run this automatically.

llm-wiki maintenance --workspace <project> --normalize-filenames previews renaming curated pages to the naming policy (lowercase ASCII kebab-case, length and shape rules, title↔filename alignment); --apply performs the rename, appends the prior stem as an alias so existing wikilinks keep resolving, and rewrites internal wikilinks. Conflicting target names are skipped for review. Hooks never run this normalization automatically.

llm-wiki maintenance prints the queue and review due status from llm-wiki/outputs/maintenance/queue.md. Queue states are pending -> approved -> done or skipped. Use llm-wiki maintenance --workspace <project> --approve <id> --target <wiki/...md> only when a human/agent explicitly accepts durable promotion, --done <id> --target <wiki/...md> after the active agent has merged the fact into a durable page, and --skip <id> [--note "..."] for duplicate or non-durable candidates. llm-wiki maintenance --workspace <project> --apply-lifecycle --dry-run previews queue hygiene and deprecated layout cleanup; without --dry-run, candidates remain pending for batch review, old low-signal candidates may be skipped, old reviewed items move to outputs/maintenance/archive/, and known deprecated folders are migrated (raw/inbox/ to raw/sources/, raw/assets/ to raw/sources/assets/, wiki/entities/ to wiki/concepts/, top-level sources/ to wiki/sources/, and top-level templates/ to wiki/context/) before empty deprecated directories are removed. Legacy daily live Q&A files are preserved under outputs/questions/archive/originals/ and converted to chunked outputs/questions/YYYY-MM-DD/live-qa-001.md files. The lifecycle never deletes user content to force conformity: duplicate content is deduplicated only when bytes match, conflicts get *-migrated-<timestamp> names, and unknown directories are left for lint/agent review. Routine hooks never apply this mutating lifecycle; they only surface compact reminders. Approved items are shown before pending items in hook reminders.

llm-wiki eval --workspace <project> [--fixture <path>] [--limit 5] [--json] runs retrieval fixtures from llm-wiki/evals/retrieval.json by default. A missing or empty fixture is a failing evaluation and exits nonzero. Fixtures list query, expected, and unexpected paths; output reports recall, MRR, stale-hit rate, citation coverage, missed expected hits, unexpected hits, hidden unexpected hits, and top hits using the same durable visibility policy as export.

llm-wiki export --workspace <project> [--format all|llms|llms-full|json] [--output <dir>] [--dry-run] [--json] writes durable wiki manifests under llm-wiki/outputs/exports/ by default. llms.txt is an agent onboarding and handoff manifest, not a passive SEO artifact. llms-full.txt is a redacted durable context bundle for compaction recovery or handoff. llm-wiki.json is a structured manifest for future adapters and eval tooling. Export uses the same durable visibility policy as search/eval and redacts credentials before writing.

llm-wiki fork --from <source-workspace> --to <target-workspace> copies durable wiki pages from one workspace to another and stamps each with a forked_from: { workspace, path, hash, copied_at } frontmatter block. Lint warns when a forked page drifts from its recorded hash so sibling workspaces can detect translation edits, status changes, or evidence refresh without manual comparison.

Every public and internal command is registered in src/command-lifecycle.js with its intended lifecycle role. Hooks do not shell out to CLI commands; they share internal modules with the CLI. status, doctor, and tests expose registry drift so commands are not added without hook policy, docs, and tests.

llm-wiki archive-questions splits older legacy llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md files into the chunked llm-wiki/outputs/questions/YYYY-MM-DD/ layout. It preserves the original under outputs/questions/archive/originals/ with a SHA-256 sidecar and replaces the legacy file with a short pointer stub. Use --dry-run first when reviewing a large archive. This is a narrow subset of maintenance --apply-lifecycle (which already archives legacy live Q&A); use the standalone command when you want to split Q&A files without touching the maintenance queue or layout.

llm-wiki projects --workspace /path/to/search-root lists project roots that already have llm-wiki-kit state or an older llm-wiki/wiki/index.md, and shows the update commands to run. llm-wiki update --workspace /path/to/search-root updates the global runtime once, then reapplies managed templates across every known or discovered project root under that search root. In update output, projects processed means the project roots were inspected by post-update; template changes are reported separately, and project details identifies which directory changed, skipped, or stayed unchanged.

For llm-wiki-kit code releases, source tests are not enough. Build one candidate tarball and verify it in isolated Linux and native Windows environments before commit/publish; after push, rebuild from the exact clean SHA and repeat those gates. Publish only that verified artifact with explicit external authority, then verify registry integrity and actual installed CLI, hooks, provider skill roots, templates, version, status, doctor, update, lint, and eval/memory health before calling the release complete. Use npm tokens only through protected environment variables; do not write them to repository .npmrc, wiki files, logs, generated exports, or commits.

Native Windows changes require a real Windows prepublish smoke against the exact candidate tarball, followed by a post-publish registry-install smoke. Run the packaged Windows tests, filesystem contention/replace checks, isolated install, status, doctor, lint/eval/memory health, and hook/skill/template checks. Simulated unit tests are not enough for the Windows support claim.

For long Windows verification runs, use the packaged file-queue runner in scripts/windows-runner/ instead of keeping a foreground WinRM command open. Install install-scheduled-task.ps1 once on the Windows host; by default it creates an on-demand hidden task with no repeating trigger. Submit JSON jobs into C:\llm-wiki-runner\queue\, run Start-ScheduledTask -TaskName LlmWikiWindowsRunner, and poll logs\<job>.status.json, stdout.log, and stderr.log. Prefer SSH/scp for normal submission, task triggering, and status polling. Keep WinRM only as a bootstrap or emergency recovery fallback.

After a plain npm install -g llm-wiki-kit@latest, existing hooks keep working when they already point at the global npm package path. Routine SessionStart/InstructionsLoaded hooks inspect and report stale managed templates but do not rewrite them. Run llm-wiki post-update --workspace <project> or llm-wiki install --workspace <project> explicitly to refresh generated templates and reconnect stale hooks; user-edited files remain protected.

On Linux/macOS, llm-wiki install creates or keeps a current user-local ~/.local/bin/llm-wiki shim even when an npm/nvm global llm-wiki command already resolves to the current runtime. This keeps Claude/Codex non-login Bash environments working when their PATH includes ~/.local/bin but not an nvm/npm global bin directory. If an unmanaged local command already exists, install leaves it alone when another current runtime command is available. On Windows, the npm-generated llm-wiki.cmd shim is the supported command entrypoint and no local symlink is created.

On PCs that use nvm or user-local npm, prefer the non-sudo global install and make sure the llm-wiki command resolves to that npm package:

npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
which -a llm-wiki
readlink -f "$(command -v llm-wiki)"
llm-wiki version
llm-wiki status

If which -a llm-wiki shows a stale ~/.local/bin/llm-wiki before the nvm/npm global binary, run install once so the kit can replace a managed stale shim or report an unmanaged one:

llm-wiki install --workspace /path/to/project --profile standard
hash -r
llm-wiki version

Real update --check and update require the package to exist in the npm registry. Before publication, use local tarball installs for smoke testing and fake npm in automated tests.

The hook subcommands are internal runtime targets:

llm-wiki hook codex SessionStart
llm-wiki hook claude Stop

Security Defaults

• Full raw transcript capture is disabled by default. An opt-in redacted full Q&A audit log (LLM_WIKI_KIT_FULL_QA=1) records every turn's redacted prompt/assistant/tool bodies under raw/qa/ (local-only, gitignored); see docs/integrations/opencode.md and decision 2026-08-07-full-qa-capture-channel.md.
• PreCompact never reads the transcript file referenced by transcript_path; it builds checkpoints only from bounded hook-captured turn state.
• Tool calls are not blocked only because inputs look sensitive.
• Authentication values such as tokens, passwords, private keys, Basic auth, URL user information, curl -u, and password-bearing CLI/database flags are redacted before durable summaries are written.
• Transient turn, compact, language, continuity, and recovery state requires a stable provider session/conversation identifier and fails closed without one; there is no shared default session artifact. LLM_WIKI_KIT_PROJECT_SCOPED_TRANSIENT=1 is an opt-in for providers that emit no session id: it derives a per-project key so transient features degrade gracefully instead of failing closed. It is off by default and never shares state across projects.
• Generated exports are redacted and must not contain npm tokens, WinRM credentials, private keys, raw .env, or full raw transcripts.
• Hook payloads are stored only as append-only, schema-bounded redacted event envelopes without cwd, transcript path, prompt/tool body, or provider session ID.
• Phone numbers, emails, dates, and business identifiers are preserved by default so the wiki remains useful for local work.

Development Notes

Source checkout installs are supported for development:

git clone <your-git-url>/llm-wiki-kit.git /path/to/llm-wiki-kit
cd /path/to/llm-wiki-kit
npm install
./install.sh --workspace /path/to/project --profile standard
node --test

llm-wiki update intentionally refuses to self-update from a source checkout. Install the npm package or a tarball first when testing update behavior.

Design Sources

• Kochim LLM Wiki implementation guide: https://kochim.com/boards/posts/1779116400000_llm-wiki-implementation-guide-2026/
• Local research baseline: docs/research/baseline.md
• Codex hooks and AGENTS.md
• Claude Code hooks and CLAUDE.md