LLM Wiki CLI

LLM Wiki CLI builds and maintains a repo-local architectural wiki for coding agents. It scans source code into a compact structural inventory, generates Markdown pages under a wiki directory, validates those pages against the live codebase, and prepares or triggers wiki-sync prompts after commits.

The PyPI distribution is agent-wiki-cli. The installed console command remains llm-wiki, and the Python import package remains llm_wiki_cli.

What It Creates

The default wiki lives at docs/llm_wiki/. Its page taxonomy is defined by the canonical wiki surface registry:

The wiki also contains .llm-wiki-manifest.json, the source hash manifest used by incremental sync and strict linting, and .llm-wiki-surface.json, a deterministic machine-readable index of canonical pages, source mappings, surface counts, flow metadata, dependency-page presence, and internal wiki links. Generated Mermaid diagrams, including bounded call-sequence, data-flow, dependency, and relationship diagrams when present, plus generated tables, links, headings, canonical filenames, and machine-readable artifacts are CLI-owned and may be regenerated by sync. Agents should edit semantic prose instead: descriptions, workflow notes, guide prose, flows/* ## Behavior sections, architecture-page ## Notes sections, custom index.md notes, and concise log.md summaries. Full bootstrap renders entity ## Relationships sections with bounded Mermaid diagrams and compact reference tables when relationship metadata exists. When dependency analysis is enabled, module pages also get a generated ## Local dependency map section with a bounded Mermaid mini-map, neighbor tables, cycle highlighting, external package counts, and concise empty-state notes instead of blank diagram fences. Haskell declaration entity relationship summaries use Module | Declaration kind instead of Python-oriented methods and attributes columns.

Registry-backed surfaces are distributed through the available query and mirror interfaces. The MCP server exposes read-only resources, search, and status counts for the same surface kinds. The supported Python API exposes source inventory, context payloads, registry-backed page metadata, and graph queries through extract_source(...), build_context(...), list_wiki_pages(...), and the documentation query wrappers. llm-wiki obsidian export mirrors the canonical Markdown wiki for Obsidian, and llm-wiki site export|check mirrors and validates plain, MkDocs-compatible, or Docusaurus-compatible Markdown output without invoking external builders. Static-site output is a derived artifact; it must not become a second editable source of truth.

The package has a small required Python runtime footprint. PyYAML>=6 parses user-supplied OpenAPI YAML, and Python versions older than 3.11 use tomli for TOML. FastAPI, Pydantic, and the target application are not runtime dependencies and are never imported for contract extraction. Optional language features use external tools when they are available on PATH.

Supported Inputs

TypeScript/JavaScript, Go, Rust, and Haskell helper setup is explicit; prepare helper dependencies and binaries with llm-wiki prepare-extractors. Lint, CI, and extract never run npm install, go build, go run, cargo build, cargo run, or ghc automatically.

Source discovery honors .gitignore before extractors run. Unescaped trailing ASCII spaces in ignore entries are ignored, while \ preserves a literal final space. A root, unanchored lib/ rule is treated as a generic build-output pattern for TypeScript projects, so .ts, .tsx, .js, and .jsx files under src/lib/ remain first-party source; top-level lib/, excluded dependency/build directories, and explicit nested .gitignore rules still stay excluded. Generated agent worktree copies such as .claude/worktrees/** are excluded from default snapshots; pass an exact --paths entry if you intentionally want to inspect one file there.

Haskell .hs and .lhs files are discovered as supported built-in source files. Normal CLI extraction invokes the prepared Haskell helper to emit syntax-only inventory for matching files. The helper does not typecheck the target project or start Haskell Language Server. Haskell dependency reconciliation is static: Cabal manifests are parsed without running Cabal, Stack extra-deps and Nix package hints are advisory optional metadata, and unknown imports are ignored rather than guessed. Haskell internal dependency edges resolve through declared module names, so nested package roots can link imports such as HLSAnalysis.API to the matching source entry. Generated Haskell module pages display declared module names, import qualification and aliases, top-level signatures and values, and type-oriented declarations such as data, newtype, type alias, type class, and instance entries. GHC 9.6.x is the supported Haskell helper toolchain for this release. Newer GHC 9.x releases are best-effort, and helper preparation fails clearly when GHC version output is malformed or older than 9.6.

Agent Support

Installed hooks generate a reviewed prompt file for all agents. The explicit trigger-agent command can still delegate to a CLI agent; for Claude, this uses claude -p and leaves permission decisions to Claude's normal permission model. Run manual CLI triggers only in repositories and execution environments you trust.

The package also bundles agent skills — reusable SKILL.md workflow directories (Claude Code-compatible) that encode the documentation and analysis loops this tool is designed around. See skills in the command reference.

For autonomous agents

Agents that do not have a dedicated schema target can use the generic instruction surface:

llm-wiki init --agent generic
llm-wiki skills export --dest exported-skills

init --agent generic writes AGENTS.md with the docs workflow order and hard rules. skills export --dest writes the bundled skill directories into a location any shell-capable autonomous agent can read, including usage-examples for attaching validated screenshots or recordings.

Installation

From PyPI:

pip install agent-wiki-cli

With MCP server support:

pip install "agent-wiki-cli[mcp]"

From source:

git clone https://github.com/Denissvgn/python-wiki-llm.git
cd python-wiki-llm
.venv/bin/pip install -e ".[dev]"

The following extras are accepted for compatibility with documented workflows, but they do not install external TypeScript/JavaScript, Go, Rust, or Haskell toolchains:

pip install "agent-wiki-cli[typescript,go,rust]"

Uninstall the Python package with:

pip uninstall agent-wiki-cli

Quick Start

Initialize the wiki structure and the agent instruction file:

llm-wiki init --agent claude

Generate the initial wiki from an existing codebase:

llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki

Validate the wiki:

llm-wiki lint --wiki-dir docs/llm_wiki --src-dir .

Install a post-commit hook:

llm-wiki install-hook

init writes the selected agent and instruction preferences to .git/.llm-wiki-agent when the project is a Git repo. Outside Git, it falls back to <wiki-dir>/.llm-wiki-agent. Tool-issue reporting guidance is omitted by default; opt in when you want agents to create local bug-report files:

llm-wiki init --agent claude --issue-reporting

This only adds guidance to the generated agent instruction block. It does not upload reports, submit issues, or enable telemetry.

Automation

llm-wiki install-hook installs a post-commit hook that generates .git/llm-wiki-prompt.txt with llm-wiki generate-prompt and prints a reminder to paste that prompt into your agent chat. Generated hooks never launch CLI agents automatically.

For advanced trusted workflows, trigger-agent remains available as an explicit manual command:

llm-wiki trigger-agent --agent <agent>

The trigger command:

• takes git diff HEAD~1..HEAD;
• skips empty diffs and oversized diffs unless --force is used;
• uses a lock file to prevent concurrent syncs;
• opens a circuit breaker after repeated failures;
• builds deep source inventory and call-graph context;
• writes .git/llm-wiki-prompt.txt with owner-only permissions where supported;
• invokes the selected agent with a prompt that asks it to update, lint, and commit wiki changes.

Useful trigger options:

llm-wiki trigger-agent --agent claude --timeout 600 --max-diff-lines 2000
llm-wiki trigger-agent --agent claude --max-prompt-bytes 2000000
llm-wiki trigger-agent --agent claude --force
llm-wiki trigger-agent --reset-breaker

Optional strict pre-commit validation:

llm-wiki install-hook --enable-validation

Use --force when you intentionally want to replace an existing unrelated hook:

llm-wiki install-hook --force

Command Reference

init

Scaffold the wiki structure and agent constraint file.

llm-wiki init --agent claude
llm-wiki init --agent copilot --wiki-dir .wiki
llm-wiki init --agent cursor --no-quality-hints
llm-wiki init --agent generic --issue-reporting

Supported agents are claude, aider, opencode, copilot, cursor, and generic. --issue-reporting includes instructions that ask agents to record llm-wiki tool failures under the local llm-wiki-issues/ directory. The instructions are off by default; use --no-issue-reporting to explicitly omit them when refreshing an existing initialization. On a refresh, omitting --agent reuses the stored agent; a project with no stored selection defaults to generic.

bootstrap

Generate a full wiki for an existing project.

llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
llm-wiki bootstrap --overwrite
llm-wiki bootstrap --depth shallow
llm-wiki bootstrap --skip-workflows
llm-wiki bootstrap --skip-flows
llm-wiki bootstrap --skip-data-flow
llm-wiki bootstrap --skip-dependencies
llm-wiki bootstrap --api-contracts
llm-wiki bootstrap --api-contracts --openapi-file openapi.yaml
llm-wiki bootstrap --include-tests go
llm-wiki bootstrap --helper-cache-dir .cache/llm-wiki-helpers
llm-wiki bootstrap --format json --source-adapter

bootstrap writes entity, module, workflow, flow, infrastructure, index, log, dependency architecture, and manifest files. User-flow pages under flows/ are generated from detected entry points with a call sequence, generated static ## Data flow section, boundary-effects table, and editable ## Behavior; use --skip-flows to omit them or --skip-data-flow to keep flow pages without the generated data-flow section. Large generated call-sequence diagrams are capped to the first 30 interactions and include an omitted-interaction note so Mermaid output stays readable on large repositories. Dependency architecture pages are generated as dependencies.md and load-order.md; use --skip-dependencies for projects that do not want those pages or lint diagnostics. Generated index.md is a registry-backed landing page with a surface overview table, per-surface counts, grouped user-flow entries, optional dependency architecture links, and a direct log link. --api-contracts adds the optional api-contracts.md production HTTP inventory and generated API-contract sections on matching HTTP flow pages. Passing --openapi-file implies --api-contracts; the supplied OpenAPI 3.0 or 3.1 JSON/YAML document is authoritative for wire fields, while syntax-only source analysis contributes handler, module, entity, and flow links. The target application is never imported or executed. --depth full is the default and includes docstrings, imports, attributes, method signatures, generated relationship sections, bounded per-module dependency mini-map summaries, and diagram data where extractors provide it. Haskell module pages render declared module names, qualified imports, aliases, signatures, values, and type declarations using the same generated module/entity surfaces as other languages. Haskell declaration entity relationship summaries show the declaration kind rather than methods and attributes columns. Generated Mermaid diagrams and generated structure are refreshed by the CLI; edit the semantic sections instead. Use --source-adapter when callers need bootstrap to write only under --wiki-dir; this skips agent constraint-file updates outside the generated wiki directory. Use --format json to emit a machine-readable summary with created, updated, and skipped files plus source counts and the manifest path. Go _test.go files are excluded by default; pass --include-tests go when behavior-spec or integration-test modules should be documented. Use --helper-cache-dir PATH when prepared Go/Rust/Haskell helpers live in a separate cache from the source repository.

sync

Incrementally regenerate only pages whose source files changed since the last manifest.

llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
llm-wiki sync --initialize-surfaces api-contracts --openapi-file openapi.yaml --dry-run
llm-wiki sync --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src

If an older wiki has index.md but no manifest, sync seeds .llm-wiki-manifest.json without modifying pages. If neither a manifest nor an existing wiki is present, run bootstrap first. Sync uses the same safe persistent inventory cache as lint when a git directory is available. Use --no-cache, --rebuild-cache, --cache-dir PATH, and --cache-stats to control or inspect inventory cache behavior. Use --helper-cache-dir PATH to point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use --jobs N or --jobs auto to opt into parallel extraction for built-in languages and plugin extractors whose manifests set "parallel_safe": true. Sync repairs manifests with invalid source hashes without touching pages, and stops unusually broad diffs unless --force is used. --initialize-surfaces enters a surface-only backfill mode for flows, dependencies, and/or api-contracts: ordinary entity/module source changes are reported but deferred. --flow-category is repeatable, --exclude-tests uses a cross-platform test-path classifier for the selected flow/dependency analysis, and --dry-run previews exact page counts and safety-guard results without writing the wiki, manifest, log, index, surface index, or cache. Selected flow categories and test filtering are persisted in manifest v4 so a later ordinary sync cannot silently expand an HTTP-only backfill to every flow. Pass --include-tests go to include Go _test.go files in the synced inventory and generated module pages; the default remains production Go source only. For trusted source trees outside the runner workspace, pass --allow-external-src; --wiki-dir remains constrained to the current project root.

sync is deterministic: it updates AST/docstring-based page skeletons and does not call an LLM. In agent workflows, treat sync as the first step, then inspect created or updated pages and replace generic _Auto-generated from ..._, copied-docstring-only, or knowable — placeholders with project-specific semantic explanations.

For entity and module pages, sync also keeps generated ## Relationships and ## Local dependency map sections current when another changed source file alters relationship or dependency data, including Haskell imports resolved by declared module name. Those generated sections are replaced without rewriting human-authored semantic descriptions or table descriptions. Older module pages that do not already have a local dependency map are left in their existing shape.

When dependencies.md or load-order.md already exists, sync also regenerates those architecture pages from the current dependency inventory and keeps their human-authored ## Notes sections unless --no-preserve-semantic is set. Those notes are the agent's responsibility: document intentional cycles, dynamic imports, side effects, and notable dependency rationale. Projects bootstrapped with --skip-dependencies, or older wikis without those pages, stay untouched.

When flow pages already exist, sync also refreshes generated call-sequence and ## Data flow content from the current inventory while preserving the human-authored ## Behavior section by default.

When api-contracts.md exists, sync refreshes its generated operation inventory and matching flow-page contract sections while preserving ## Notes and ## Behavior. A bootstrap/sync OpenAPI input is stored as a source-relative path and hash; a specification-only change refreshes contracts even when source files are unchanged. Use --clear-openapi-file to return deliberately to static contract authority.

When sync rebuilds index.md, the generated landing-page overview and per-surface link sections are replaced from the live registry and inventory. With semantic preservation enabled, old custom top-level index sections are kept at the end, and old free-form intro text is migrated under ## Notes. Use --no-preserve-semantic to regenerate a clean index without those custom sections.

extract

Print source inventory as JSON. All registered extractors run; missing optional prepared helpers are skipped when there are no matching source files.

llm-wiki extract --src-dir .
llm-wiki extract --src-dir . --changed
llm-wiki extract --src-dir . --summary
llm-wiki extract --src-dir . --deep
llm-wiki extract --src-dir . --deep --openapi-file openapi.json
llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
llm-wiki extract --src-dir . --package llm_wiki_cli
llm-wiki extract --src-dir . --include-empty
llm-wiki extract --src-dir . --include-tests go
llm-wiki extract --src-dir . --summary --output sources/code.json --read-only
llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary

The JSON output includes schema_version: "llm-wiki-extract/v1" plus inventory and optional docker and unsupported_sources objects. Go _test.go files are omitted unless --include-tests go is supplied; Python test files remain part of normal Python extraction. JavaScript .js and .jsx files are handled by the TypeScript extractor family and use language: "javascript" in inventory output. Prepare the same helper with llm-wiki prepare-extractors --language typescript. Plain .js files include named top-level function declarations in the functions list even when they are local CommonJS helpers. Those functions are rendered on module pages; JavaScript function declarations do not create entity pages, which remain class/type/declaration oriented. Raw Node http.createServer and https.createServer calls in JavaScript create HTTP entry points for extract --deep, flow pages, and data-flow summaries. Named handler arguments resolve to the handler symbol when available; inline callbacks fall back to the assigned server variable such as server. Lint and CI keep the non-blocking javascript_flow_unsupported diagnostic only for createServer patterns outside the supported raw Node http/https shape. unsupported_sources reports known source extensions that are visible in the tree but not handled by an active extractor. Haskell is registered as a built-in language, so .hs and .lhs files no longer appear in this advisory block. When Haskell files are present, extraction requires a prepared helper and reports a clear prepare-extractors --language haskell message if it is missing. Haskell internal dependency edges resolve through declared module names from inventory entries rather than filepath stems. Haskell file entries are additive under llm-wiki-extract/v1. A Haskell entry uses language: "haskell", imports, classes, and functions, with module present when the source declares one. Import records use module, qualified, alias, and line. The classes bucket stores type-oriented declarations with kind values such as data, newtype, type, class, and instance. The functions bucket stores top-level signatures, functions, and values with kind values such as signature, function, and value; signature entries may include signature. Haskell-specific fields such as language_pragmas, exports, and deriving are optional best-effort metadata and consumers must tolerate their absence. The Haskell helper emits syntax-only inventory without typechecking the target project and does not start Haskell Language Server. Haskell dependency reconciliation reads *.cabal build-depends statically, scopes nested Cabal packages by nearest manifest directory, treats library/executable/common dependencies as required, and treats test-suite, benchmark, setup, Stack extra-deps, and Nix hints as optional. With --deep, Python function entries may carry optional data_effects blocks (inputs, selected global/attribute reads, writes, returns, and boundary effects such as filesystem, environment, process, network, output, and logging calls) and optional calls lists (in-body call targets, optionally with compact args and kwargs expression summaries). Function params include reconstructable parameter kinds for positional-only, positional-or-keyword, variadic, keyword-only, and variadic-keyword declarations. Python model/type inventory also carries optional required/nullable/default/factory, alias, constraint, description/example, Annotated, validator/config, enum-member, literal, and type-alias metadata without importing Pydantic or application modules. The payload also gains an optional top-level entrypoints array (detected user-reachable entry points: {id, category, file, symbol, label}), a data_flows list for detected user flows, plus a top-level dependencies object with internal edges, cycles, per-language external dependency reconciliation, optional resolved-version metadata, and load_order. Version metadata is best-effort and appears only when a supported lockfile or exact pin is available: Go go.sum, Rust Cargo.lock, Python poetry.lock and exact requirements*.txt pins, npm package-lock.json, and narrowly supported pnpm-lock.yaml package entries. Haskell lockfile pinning is intentionally out of scope for this metadata. When --deep is combined with --changed, --paths, --package, or --summary, data_flows and dependencies describe the emitted inventory before summary collapse. Inventory keys are POSIX paths relative to --src-dir, never absolute paths. The v1 contract permits additive fields; incompatible shape changes require a new schema version. The M3 data-flow fields are therefore optional additions under llm-wiki-extract/v1, not a schema bump. Deep Python extraction also emits optional per-file frameworks.fastapi declarations and a top-level api_contracts object. Static uncertainty is reported through unknowns and diagnostics; test-source and include_in_schema=False operations are excluded from the production operation inventory by default. With --openapi-file, OpenAPI defines the operation set and wire contract, external references are never fetched, and unmatched or conflicting static declarations remain visible as diagnostics. Installed entrypoint_detector plugin hooks also contribute to the same entrypoints array in deep output. Detector failures are isolated: built-in entry-point detection still runs, extract prints a warning to stderr, and the JSON payload includes top-level warnings only when such diagnostics exist.

prepare-extractors

Prepare TypeScript/JavaScript dependencies and cached Go/Rust/Haskell helper binaries outside the lint/extract hot path.

llm-wiki prepare-extractors --src-dir .
llm-wiki prepare-extractors --language typescript --language go --language haskell
llm-wiki prepare-extractors --cache-dir .cache/llm-wiki-helpers

When --language is omitted, only helper languages detected in --src-dir are prepared. Helper cache resolution follows --cache-dir, then LLM_WIKI_CACHE_DIR, then .git/llm-wiki-extractors/. If Go is installed in a nonstandard location or the go on PATH cannot run, set LLM_WIKI_GO=/path/to/go before running prepare-extractors. If GHC is installed in a nonstandard location, set LLM_WIKI_GHC=/path/to/ghc before preparing Haskell helpers. GHC 9.6.x is the supported Haskell helper toolchain; newer GHC 9.x releases are best-effort, and older or malformed GHC version output fails during helper preparation. Commands that consume prepared Go/Rust/Haskell helpers accept --helper-cache-dir PATH. This is separate from inventory-command --cache-dir PATH, which only controls where llm-wiki-inventory-cache.json is read and written.

lint and ci-check

Validate wiki links, orphan pages, entities, modules, workflows, infrastructure, plugin lint rules, and team policy.

llm-wiki lint --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --strict --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src

Strict mode also requires the core wiki structure and a fresh sync manifest. --profile suppresses the human-readable lint text and prints one JSON object to stdout containing the normal lint report, diagnostics, and phase timings. The JSON contract is preserved for extractor failures as well; lint still exits nonzero, but stdout remains machine-readable. Lint uses a persistent deep-inventory cache by default when a git directory is available, storing .git/llm-wiki-inventory-cache.json. Override the cache directory with LLM_WIKI_CACHE_DIR or --cache-dir PATH; the CLI flag wins for inventory caching. Use --helper-cache-dir PATH when prepared Go/Rust/Haskell helpers live somewhere else. Use --no-cache to disable load/save, --rebuild-cache to ignore and rewrite the cache, and --cache-stats to include cache diagnostics. Cache corruption or invalid fingerprints fall back to a full extraction without reducing lint coverage. With --profile --cache-stats, the JSON payload includes a top-level cache object. Use --jobs N or --jobs auto to opt into parallel extraction for built-in languages and plugin extractors whose manifests set "parallel_safe": true; the default is --jobs 1. Plugin extractors without that opt-in remain sequential. Use --include-tests go when a wiki intentionally documents Go _test.go files; omit it to lint against the default production-source inventory. For trusted source trees outside the runner workspace, pass --allow-external-src; --wiki-dir remains constrained to the current project root.

When dependency architecture pages exist, lint reruns dependency analysis and surfaces import cycles, undeclared dependencies, and unused declared dependencies as warning diagnostics. These warnings are visible in human output and profile JSON but do not make lint, lint --strict, or ci-check fail by themselves. Stale architecture pages with no current source modules remain hard issues. Python dependency reconciliation reads pyproject.toml and requirements*.txt manifests, including nested manifests scoped to their directory. TypeScript and JavaScript reconciliation reads the nearest scoped package.json and resolves first-party imports through the nearest tsconfig.json baseUrl/paths aliases before reporting undeclared external packages. Generic internal import matching is scoped by the importer's language before external dependency reconciliation, so same-stem files in other languages do not consume external imports. Dependency manifests inside generated agent worktree copies, gitignored directories, and other paths outside the default source snapshot boundary are ignored during reconciliation. Go // indirect requirements are treated as optional transitive dependencies, so they do not produce unused-dependency warnings by themselves. Haskell reconciliation reads Cabal build-depends statically, records Stack extra-deps and Nix package hints as optional only, scopes nested Cabal packages by nearest manifest directory, and reports only explicit known module-prefix mappings such as Data.Text -> text. When supported lockfiles are present, reconciliation also exposes optional resolved-version metadata under each language's versions mapping. Missing or unparseable lockfiles fail open by omitting version records; they do not affect lint pass/fail behavior or undeclared/unused package diagnostics. When generated entity/module diagram sections exist, lint validates Mermaid click links as hard broken-link issues and reports over-large generated diagrams as warning diagnostics with page and section targets. When guide or other semantic pages embed local media, lint treats image and video targets separately from Markdown page links. It recognizes inline Markdown images and media links, same-page reference-style images, and raw <img>, <video>, and <source> tags, including local srcset candidates. Fenced code blocks are ignored by the media pass so examples do not create media diagnostics; the general page-link check is unchanged. Missing local media files are hard media_link_broken issues. Missing image alt text, media files over the default 2 MB warning threshold, unreferenced media files under assets/, media stored outside the preferred assets/ convention, unrecognized non-hidden files under assets/, and symlinked media that resolves outside the wiki root are warning diagnostics (media_missing_alt_text, media_oversize, media_orphan, media_outside_assets, asset_unrecognized_type, and media_symlink_escape). Use --media-size-warn-bytes to tune the size warning for a project. When flow pages exist, lint also reports generated data-flow gaps, such as unresolved calls that static analysis cannot classify, as warning diagnostics. Known but unsupported source files are reported as informational diagnostics and do not make lint, lint --strict, or ci-check fail. Haskell .hs and .lhs files are now registered as built-in source files. The prepared helper parses syntax-only inventory during normal extraction; if the helper is missing, commands report the Haskell preparation command instead of treating those files as unsupported sources.

For CI:

llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
llm-wiki ci-check --format json --report .git/llm-wiki-ci-report.md
llm-wiki ci-check --format markdown

ci-check always runs strict validation, writes a Markdown report, records a local metrics event, uses the same safe inventory cache when available, and exits nonzero on validation failure. JSON output includes non-blocking diagnostics so CI logs can show unsupported-source coverage without failing. For trusted source trees outside the runner workspace, pass --allow-external-src; --wiki-dir remains constrained to the current project root. --report is an output path, so explicit absolute paths and relative artifact paths outside the project root are allowed.

context

Build a token-budgeted source snapshot for agents.

llm-wiki context --budget 8000 --src-dir . --format json
llm-wiki context --budget 8000 --src-dir . --format markdown
llm-wiki context --budget 8000 --focus changed
llm-wiki context --budget 8000 --focus all
llm-wiki context --budget 12000 --format json --focus all --output context.json --read-only

--focus changed is the default. Changed files get full detail, one-hop import neighbors get slim detail, and remaining files get names only.

External tools can use the llm-wiki-context/v1 JSON request protocol:

llm-wiki context --request request.json --src-dir .
cat request.json | llm-wiki context --request - --src-dir .
llm-wiki context --request request.json --src-dir . --wiki-dir docs/llm_wiki

Example request:

{
  "protocol": "llm-wiki-context/v1",
  "budget_tokens": 8000,
  "focus": ["changed", "neighbors"],
  "format": "json",
  "filters": {
    "language": "python",
    "symbol": "build_context",
    "entrypoint": "llm-wiki-context",
    "surface": "flows"
  }
}

filters.language and filters.module scope the budgeted files payload. filters.symbol, filters.entrypoint, and filters.surface add bounded graphs and surface sections without changing the file-priority budget. --wiki-dir selects the wiki surface metadata used for graph page references.

--output PATH writes the generated JSON or Markdown directly instead of printing it to stdout. --read-only documents source-adapter intent: the command does not write wiki files, hooks, manifests, local config, or helper/cache state, except for an explicit --output artifact.

Codebase source integration

For research or indexing systems that need codebase evidence without adopting the maintained wiki format, prefer the read-only source-adapter commands:

llm-wiki extract --src-dir <repo> --summary --read-only
llm-wiki context --src-dir <repo> --budget 12000 --format json --focus all --read-only
llm-wiki bootstrap --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --format json --source-adapter
llm-wiki sync --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --allow-external-src
llm-wiki lint --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --allow-external-src
llm-wiki ci-check --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --allow-external-src --report ci-report.md

By default, --src-dir must resolve inside the current working directory. For a trusted source tree outside cwd, pass --allow-external-src; explicit --paths are still constrained to the chosen source root and can opt into an otherwise excluded generated worktree file. sync, lint, and ci-check use the same opt-in to continue a source-adapter wiki generated by bootstrap, while --wiki-dir remains constrained to the runner project. Explicit output paths such as --output and --report may be absolute or outside the project root because they are caller-selected artifacts.

Example extract --summary payload:

{
  "schema_version": "llm-wiki-extract/v1",
  "inventory": {
    "models.py": {
      "language": "python",
      "package": "sample",
      "classes": ["User"],
      "functions": ["load_user"]
    }
  }
}

Example context --format json payload:

{
  "budget": 12000,
  "used": 320,
  "truncated": false,
  "omitted_files": [],
  "downgraded_files": {},
  "files": {
    "models.py": {
      "priority": "high",
      "detail": "deep",
      "classes": [{"name": "User"}],
      "functions": []
    }
  }
}

Example bootstrap --format json --source-adapter summary:

{
  "schema_version": "llm-wiki-bootstrap-summary/v1",
  "src_dir": "/path/to/repo",
  "generated_wiki_path": "sources/code_wikis/repo",
  "depth": "full",
  "source_files": 12,
  "classes": 8,
  "functions": 31,
  "docker_files": 1,
  "infrastructure_files": 3,
  "github_actions_files": 0,
  "kubernetes_files": 0,
  "runtime_config_files": 2,
  "runtime_config_by_type": {
    "prometheus": 1,
    "prometheus_rules": 1
  },
  "workflows": 2,
  "cross_references": 14,
  "created_files": ["sources/code_wikis/repo/index.md"],
  "updated_files": [],
  "skipped_files": [],
  "manifest_path": "sources/code_wikis/repo/.llm-wiki-manifest.json"
}

generate-prompt

Build a sync prompt for IDE agents or for manual review.

llm-wiki generate-prompt
llm-wiki generate-prompt --print
llm-wiki generate-prompt --change-type feature
llm-wiki generate-prompt --template compact

The generated prompt includes change-type guidance. Installed prompt templates can override the default prompt body. The default prompt asks agents to run sync first, then perform a semantic pass on affected pages before accepting a lint-clean wiki as complete.

mcp

Run a local MCP server exposing read-only wiki tools and resources.

llm-wiki mcp --wiki-dir docs/llm_wiki --src-dir .
llm-wiki mcp --transport http --host 127.0.0.1 --port 8765

The MCP server exposes registry-backed wiki resources and search across index, log, entities, modules, workflows, guides, flows, infrastructure, dependencies, and load order. It also exposes direct page tools including get_flow(flow_id) and get_architecture_page(page), where page is dependencies or load-order. Use query_graph({"type": "callers", "value": "run", "limit": 20}) for bounded graph queries; supported types are flow_for_entrypoint, data_flow_for_entrypoint, callers, callees, dependency_neighborhood, and pages_for_symbol. Context payloads, lint summaries, and status information report the same canonical surfaces. HTTP mode is intended for local use and defaults to loopback.

install and plugins

Install and manage local plugins.

llm-wiki install ./vendor/my-plugin --yes
llm-wiki install my-catalog-plugin --dry-run
llm-wiki plugins list
llm-wiki plugins validate ./vendor/my-plugin
llm-wiki plugins remove my-plugin

Plugin manifests can register extractors, entry-point detectors, diagram styles, prompt templates, lint rules, and agent skill blocks. Plugin references are resolved from project-local paths or .llm-wiki/catalog.json. Extractor, lint-rule, entry-point detector, and diagram-style entry points must resolve to Python files inside the plugin directory; installed entry points are checked again before runtime import. Extractor components may set "parallel_safe": true to opt into --jobs parallel execution; omit it unless the extractor is safe to run concurrently in a fresh instance.

A tested M4 sample plugin lives at examples/plugins/m4-documentation-hooks in source checkouts. It can be inspected or installed like any other local plugin:

llm-wiki plugins validate examples/plugins/m4-documentation-hooks
llm-wiki install examples/plugins/m4-documentation-hooks --yes

Installed packages can export the same bundled sample before installing it:

llm-wiki plugins samples list
llm-wiki plugins samples export m4-documentation-hooks --dest vendor/m4-documentation-hooks
llm-wiki plugins validate vendor/m4-documentation-hooks
llm-wiki install vendor/m4-documentation-hooks --yes

The sample manifest declares m4-documentation-hooks/worker-tasks (detectors:detect_worker_tasks) and m4-documentation-hooks/brand-flowcharts (styles:style_flowcharts). The detector only reads the plain inventory it receives and returns task handler records; the style hook only returns normalized direction, class, and color hints for generated flowcharts.

An entrypoint_detector hook is called with the plain extracted inventory and returns entry-point records shaped as {category, file, symbol, label}. file may be null or a relative POSIX inventory path, label is optional, and any plugin-supplied id is ignored so core deduplication and stable id assignment remain authoritative. Detector exceptions or invalid records become warnings in extract --deep, bootstrap, and sync; built-in detectors still run.

A diagram_style hook is called with a plain context object such as {"surface": "relationships"} or {"surface": "data_flow"} and may return only bounded style hints: direction (TB, TD, BT, RL, or LR), node_classes mapping exact generated node labels to safe Mermaid class names, and category_colors mapping safe class names to #RGB or #RRGGBB colors. LLM Wiki ignores invalid values and unknown keys, so plugins cannot inject Markdown, labels, hrefs, or raw Mermaid lines. Labels and click hrefs remain sanitized by the core diagram renderers.

These hooks are deterministic local extension contracts over explicit inputs; they do not perform network discovery and they do not mutate Markdown directly. They are not a sandbox, though: installing a plugin runs trusted project-local Python code, so use plugins only from paths you control.

team

Manage shared team policy for prompt defaults, required plugin components, and generated-wiki conflict handling.

llm-wiki team init --wiki-dir docs/llm_wiki
llm-wiki team check --src-dir . --wiki-dir docs/llm_wiki
llm-wiki team resolve-conflicts --wiki-dir docs/llm_wiki
llm-wiki team resolve-conflicts --write --wiki-dir docs/llm_wiki

resolve-conflicts only applies conservative resolutions for generated pages. Manual workflow conflicts are left for humans to resolve.

obsidian

Export and validate an Obsidian-friendly mirror of the canonical wiki.

llm-wiki obsidian export --wiki-dir docs/llm_wiki --vault-dir ~/Vaults/project
llm-wiki obsidian check --wiki-dir docs/llm_wiki --vault-dir ~/Vaults/project
llm-wiki obsidian install-plugin --vault-dir ~/Vaults/project

The mirror adds frontmatter, wikilinks, related links, and sidecar human notes. Page discovery follows the canonical surface registry, so guides, flows, and optional architecture pages are mirrored when present. The canonical source of truth remains docs/llm_wiki/; generated mirror output is not edited as an independent documentation source.

site

Export and validate a static-site-friendly mirror of the canonical wiki.

llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --profile reference
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --profile user --site-name "Project Docs"
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --profile user --site-name "Project Docs" --file-friendly
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --dry-run --output-format json
llm-wiki site export --wiki-root sources/code_wikis --out-dir site --format docusaurus
llm-wiki site export --wiki sources/code_wikis/api --wiki sources/code_wikis/web --out-dir site
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site --profile user --site-name "Project Docs"
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site --built-site-dir _site --link-mode http
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site --built-site-dir _site --link-mode file --profile user --site-name "Project Docs"
llm-wiki site check --wiki-root sources/code_wikis --out-dir site
llm-wiki site check --out-dir site --output-format json

--format supports plain, mkdocs, and docusaurus; --output-format controls text versus JSON reports. --wiki-dir exports or checks one canonical wiki. --wiki-root discovers source wikis from immediate child directories, and repeated --wiki flags select explicit source wiki directories; both hub modes write each wiki under <out-dir>/<source_id>/ and generate a top-level hub index.md. MkDocs hub exports group navigation by source ID. Docusaurus hub exports namespace document IDs by source ID to avoid collisions. MkDocs exports include safe llm_wiki front matter and a generated mkdocs.yml with registry-ordered navigation. --profile reference is the default agent/reference mirror. --profile user --site-name ... writes a concise human landing page, expects guide pages, and moves the exhaustive generated inventory to generated-reference.md; its check adds quality gates for default site names, missing guides, bloated landing pages, and placeholder text in primary human docs. Docusaurus exports include Docusaurus front matter and generated sidebars.json metadata. When multiple exported pages share the same Markdown heading, generated MkDocs and Docusaurus labels include page-id context such as agent / ArtifactStore so static-site navigation remains unambiguous. Plain exports can add llm_wiki front matter with --front-matter.

MkDocs defaults target HTTP hosting. --file-friendly is an opt-in MkDocs mode for direct disk handoffs: it writes use_directory_urls: false, a small MkDocs theme override for file-safe home links, and reports distribution_mode: "file". After building a site, site check --built-site-dir _site --link-mode http|file validates generated HTML links. http mode accepts MkDocs directory URLs that resolve to index.html; file mode requires concrete .html targets and reports directory-style links as hard issues.

Agent-owned usage media should live under the semantic assets/ surface, using the mirrored path convention assets/<surface>/<page-stem>/<name>.<ext>. Markdown image embeds and media links, same-page reference-style images, and raw <img>, <video>, and <source> tags are recognized for .png, .jpg, .jpeg, .webp, .gif, .svg, .mp4, and .webm files; local srcset candidates are validated and mirrored too. site export copies every referenced media file that resolves inside the wiki root, including media kept beside a page outside assets/, and reports asset operations separately from page operations. Symlinked media that resolves outside the wiki root is warning-visible and is not mirrored. site check --built-site-dir validates built HTML media targets and local srcset candidates in both http and file link modes.

The service layer also exposes the same pure mirror builder for integrations:

from llm_wiki_cli.services.site_export import export_site_hub, export_site_mirror

report = export_site_mirror(
    wiki_dir="docs/llm_wiki",
    out_dir="site",
    format="mkdocs",
)

hub = export_site_hub(
    wiki_root="sources/code_wikis",
    out_dir="site",
    format="docusaurus",
)

The builder copies registry-backed wiki pages in canonical order, preserves Mermaid fences, rewrites resolvable internal Markdown links to remain local to the mirror, writes MkDocs config comments that point users at a Mermaid plugin when diagram rendering is desired, and refuses source/output overlap unless explicitly allowed. Docusaurus exports also escape MDX-sensitive text outside code fences and inline code spans while preserving fenced Mermaid diagrams. site check validates the generated mirror without external builders: missing pages, broken or unsafe local Markdown links, malformed generated front matter, metadata mismatches, duplicate Docusaurus document ids, and output paths outside the mirror are hard issues; mixed mirrors that omit front matter on some pages emit non-failing warnings in JSON and text reports.

skills

List, export, and install the agent skills bundled with the package. Each skill is a directory holding a SKILL.md workflow definition (Claude Code-compatible frontmatter plus instructions) and optional supporting files. Thirteen skills are bundled:

• attack-surface: defensive security-review preparation — prepare extractor helpers, run extract --deep --read-only, seed required coverage from SECURITY.md, treat data-flow gaps as unknown surface, supplement with a source-level sink scan, and write a prioritized AS-NNN exposure report that hands suspicious paths to deeper review (reconnaissance, not a SAST replacement).
• dep-audit: dependency diagnostics triage — consume existing lint, ci-check, review JSON, and wiki dependency outputs; classify dependency-cycle, undeclared-dependency, and unused-dependency findings; verify source evidence before source, manifest, or wiki edits; and report deferred items explicitly.
• dep-vuln-triage: vulnerable-dependency exposure triage — build a per-language dependency inventory with lockfile-resolved versions from the deep extract, look up advisories per package, rank hits by import-site reachability, and write a severity × reachability DVT-NNN report with proposed bumps or mitigations; packages without resolved versions are reported as unknowns, never safe paths.
• doc-hub: multi-repo documentation hub aggregation — keep each source wiki current, export/check a multi-wiki static-site hub with site export --wiki-root/site check, and write one LLM-owned hub overview page only when the source repositories are genuinely related (never fabricate a cross-repo relationship that isn't real).
• doc-review: documentation review follow-through — start from review JSON, branch diffs, patch findings, lint, or sync diagnostics; validate each finding against source truth; update semantic wiki/source-doc surfaces; run lint/ci-check; and preserve unresolved findings with rationale.
• impact-analysis: change blast-radius tracing — run bounded callers/callees/dependency_neighborhood/flow_for_entrypoint graph queries via context --request or MCP, map hits to the wiki pages that describe them, and emit a docs-to-update checklist in the same classification vocabulary doc-review uses so its output feeds directly into that skill.
• infra-review: deployment-surface review — enumerate generated Dockerfile/Compose/Kubernetes/GitHub-Actions infrastructure/ pages, apply a checklist for privileged containers, host mounts, exposed ports, plaintext secrets, and over-broad Actions permissions, reading raw source for the fields (K8s security context, Actions permissions) the generated pages don't capture.
• onboarding-guide: persona-scoped "start here" narratives — verify the wiki is current, rank the flows a newcomer actually hits, write one guided-tour page per persona into the agent-owned guides/ surface with links into existing wiki pages, record deferred personas as an explicit remainder, and validate with lint --strict and a sync re-link pass.
• publish-docs: wire static-site export into an actually publishable site — export (single-wiki or hub), validate with site check, run the real mkdocs/docusaurus builder when installed, and hand off (never perform) the deploy step.
• usage-examples: capture evidence-linked examples for user docs — run documented flows in a disposable environment, attach screenshots or recordings under assets/<surface>/<page-stem>/, validate media links and built-site media targets, and defer honestly when capture tooling or runtime access is unavailable.
• user-docs-author: full user documentation authoring pass — run deterministic sync/lint/site export --profile user/site check evidence first, write only evidence-linked semantic wiki prose such as guides/*.md, and loop on validation-backed user-site issues without editing generated blocks or static-site output directly.
• wiki-bootstrap: the first-adoption workflow for an existing codebase — prepare extractor helpers, run deterministic bootstrap --format json, do a centrality-ranked semantic pass on the most central pages, write an explicit remainder backlog for deferred pages, validate with lint --strict/ci-check, and commit the wiki.
• wiki-sync: the post-change documentation loop — deterministic sync, a semantic-only prose pass, a lint --strict validation loop, and a separate docs(wiki): commit.

llm-wiki skills list
llm-wiki skills install                          # into ./.claude/skills/
llm-wiki skills install --skill wiki-sync --force
llm-wiki skills export --dest ~/.claude/skills   # personal skills directory
llm-wiki skills export --dest exported --format json

install writes into the current project (default .claude/skills/, must stay inside the project root); export accepts any destination directory. Both are idempotent: identical existing files are kept, and files that were edited locally are never overwritten without --force — the run reports existing_file_differs and exits non-zero instead, so local skill customizations survive package upgrades by default.

metrics

Show local quality and automation metrics.

llm-wiki metrics --last 30d
llm-wiki metrics --format json

Metrics are stored locally under .git/llm-wiki-metrics.jsonl when available.

review

Run a static wiki-aware review of proposed code changes.

llm-wiki review --base main --head HEAD
llm-wiki review --patch change.patch --format json

The review command compares code changes with full-surface wiki coverage and reports stale or missing documentation risks. Module/entity pages, source-linked user-flow pages, workflow pages, infrastructure notes, and dependency/load-order architecture pages all count as relevant review coverage when they describe the changed code or dependency relationship.

upgrade

Refresh framework-managed artifacts in place.

llm-wiki upgrade
llm-wiki upgrade --agent copilot
llm-wiki upgrade --wiki-dir .wiki
llm-wiki upgrade --force
llm-wiki upgrade --no-quality-hints
llm-wiki upgrade --issue-reporting
llm-wiki upgrade --no-issue-reporting

upgrade refreshes agent instruction blocks, wiki directories, hooks, plugin skill blocks, and persisted local config. The issue-reporting pair explicitly enables or disables the local agent guidance; without either flag, upgrade preserves the stored preference. Configurations created before this preference existed default to disabled. For older wiki layouts, upgrade idempotently adds registry-standard directories such as flows/ and missing .gitkeep files without rewriting existing index, log, semantic pages, or optional dependencies.md / load-order.md pages. Run bootstrap or sync to generate user-flow and dependency architecture pages; after upgrading, site export and MCP automatically see any flows/*.md pages that exist.

migrate

Reconcile older wiki layouts with current canonical names.

llm-wiki migrate --dry-run
llm-wiki migrate --chunk-size 50 --plan-chunks
llm-wiki migrate --chunk-size 50 --chunk 1

status, release, bump, and uninstall

llm-wiki status
llm-wiki release --stage
llm-wiki bump --patch --stage
llm-wiki uninstall --dry-run
llm-wiki uninstall --remove-wiki

uninstall removes project integration artifacts. It does not uninstall the CLI itself. To remove the Python package, run pip uninstall agent-wiki-cli.

Security Model

LLM Wiki is a local automation tool. It can generate prompt files containing diffs, source structure, and architectural context. Prompt files are written inside .git/ by default and use owner-only permissions where the platform supports that mode.

Manual CLI triggers can edit files and run commands according to the selected agent's own permission model. Review generated prompt files and wiki diffs before trusting agent-produced changes in a shared repository.

The repository includes community health files:

• CODE_OF_CONDUCT.md
• SECURITY.md
• GitHub issue templates

Development

Run tests from the repository root:

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -v

Run the MCP tests with the optional dependency installed:

.venv/bin/pip install -e ".[dev,mcp]"
.venv/bin/pytest tests/test_mcp.py

Before release, check metadata and docs:

.venv/bin/pytest tests/test_package_metadata.py tests/test_release.py -q
.venv/bin/python -m build
git diff --check

Release notes and package metadata record the surface, distribution, compatibility, and local verification gates for documentation-surface work. Use llm-wiki release separately when stamping a real version.

The M4 dogfood smoke exercises this repository's own documentation surface by copying the checkout to a temp project, bootstrapping a full wiki, running sync, exporting a MkDocs mirror, and checking the mirror:

.venv/bin/pytest tests/test_bootstrap.py::TestGenerateFlowMd tests/test_m4_dogfood.py -q
.venv/bin/pytest -q

Contribution Policy

This project does not maintain a formal contribution process. You are welcome to freely fork it, adapt it to your workflow, and publish your own changes under the license terms.