llm-wiki-kit

llm-wiki-kit is a hook-first living wiki runtime for Claude Code and Codex.

The goal is not to make users run ingest or record commands. After install, normal Claude Code/Codex work should naturally become a project-local Markdown wiki under llm-wiki/.

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 such as 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 Claude Code and Codex sessions after installation.

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 server smoke tests, install from a local tarball instead:

npm pack --pack-destination /tmp
npm install -g /tmp/llm-wiki-kit-<version>.tgz
llm-wiki install --workspace /apps --profile standard

What Gets Created

Each project gets a local wiki:

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

raw/ is the immutable or redacted evidence layer. 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 filenames and content stay composed.

Normal Use

Use Claude Code or Codex normally.

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.
• remove Codex-facing legacy oh-my-codex:wiki/omx_wiki surfaces at session start so llm-wiki/ remains the active wiki implementation
• 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 redacted checkpoint only for explicit durable requests, structured durable conclusions with required evidence, or durable wiki/procedure updates; generic tool-heavy work gets a context note only
• after compaction, store the redacted compact summary only; 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
• automatically refresh managed rules/templates for older projects when the current runtime starts a session

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 default capture mode is LLM_WIKI_KIT_CAPTURE_MODE=answer-first; the old eager query/decision capture path remains only as deprecated compatibility mode via LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager. 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 reads only a bounded transcript tail controlled by LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES; the raw transcript path and authentication values are redacted before any checkpoint or recovery packet is written.

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
• Diagnostics: llm-wiki doctor, llm-wiki status, llm-wiki version
• Manual: llm-wiki manual
• Agent maintenance helpers: 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]
• 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 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 the installed runtime already satisfies the registry target, it prints an already-current result, skips npm install -g, and still runs post-update maintenance. 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 and safe managed template updates without running npm install -g. Use post-update --all --workspace <search-root> to reapply templates across discovered project roots.

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, snippets, memory, index, expansion behavior, context budget metadata, rankReason, matchedFields, scoreBreakdown, visibilityReason, and evidenceRefs. The text formatter adds a short why selected line for each hit; hook compact context deliberately omits that extra detail. Use --budget-chars <n> for reviewable context packs and --show-hidden-reason to inspect pages excluded by visibility policy. Daily use should rely on hook injection. By default, episodic wiki/queries/, wiki/context/, and session-log pages are excluded from search unless they were promoted with memory_type: semantic or procedural and importance >= 4; 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.

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. It validates optional evidence_refs entries with the prefixes file:, cmd:, raw:, and url:; unsafe paths, unsupported prefixes, credential-bearing URLs, command secrets, and secret-like values are reported as errors, while missing local evidence targets are warnings. It also warns when memory.md is near budget, wiki page count nears the search cap, hidden episodic/context pages accumulate, or stale/archived pages lack supersession/link discoverability. Agents may use it before/after meaningful wiki maintenance.

llm-wiki consolidate refreshes only generated marker blocks in wiki/memory.md and wiki/index.md. Generated maps keep durable non-archived pages, hide default episodic records, skip stale/archived/superseded pages, and report those counts in dry-run output. It is an agent maintenance helper, not a command users should run after every turn.

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 automatic queue hygiene; without --dry-run, candidates remain pending for batch review, old low-signal candidates may be skipped, and old reviewed items move to outputs/maintenance/archive/. Hooks apply that lifecycle only on SessionStart/InstructionsLoaded; UserPromptSubmit only reminds for explicit documentation, recovered state, maintenance prompts, or batch thresholds. Approved items are shown before pending items in hook reminders. Periodic maintenance is a soft agent-side reminder, not a user command loop.

llm-wiki eval --workspace <project> [--fixture <path>] [--limit 5] [--json] runs retrieval fixtures from llm-wiki/evals/retrieval.json by default. If the fixture is absent, it exits successfully with no fixture found. 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.

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.

llm-wiki projects --workspace /apps 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 /apps updates the global runtime once, then reapplies managed templates across every known or discovered project root under /apps.

For llm-wiki-kit code releases, source tests are not enough. After code changes, publish the package, install the newly published version, and verify the installed CLI and hooks with version, status, doctor, update, lint, and hook smoke checks before calling the release complete.

Native Windows changes require a real Windows smoke before release. The release gate is: install the packed candidate or published package on a Windows host, run llm-wiki install, llm-wiki status, and llm-wiki doctor against a temporary Windows project, inspect %USERPROFILE%\.codex\hooks.json and %USERPROFILE%\.claude\settings.json, then repeat the minimal smoke after npm install -g llm-wiki-kit@latest once published. 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. The next SessionStart/InstructionsLoaded hook automatically reapplies safe managed template updates for the active project root. Clearly generated older llm-wiki/AGENTS.md and procedure files are refreshed even when old state is missing; user-edited files are not overwritten and are surfaced to the active agent as cleanup work. If hooks point at a source checkout or stale shim, run llm-wiki post-update --workspace <project> or llm-wiki install --workspace <project> once to reconnect them.

On Linux/macOS, llm-wiki install no longer creates a user-local ~/.local/bin/llm-wiki shim when an npm/nvm global llm-wiki command already resolves to the current runtime. If an older kit-managed local shim is shadowing that npm command, install backs it up and removes it. 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 remove a managed shadowing 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.
• PreCompact may read a small bounded transcript tail to create a redacted checkpoint, but it does not store the full transcript or raw transcript_path.
• Tool calls are not blocked only because inputs look sensitive.
• Authentication values such as tokens, passwords, and private keys are redacted before durable summaries are written.
• 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 redacted event envelopes.
• 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 /apps/llm-wiki-kit
cd /apps/llm-wiki-kit
npm install
./install.sh --workspace /apps --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