llm-wiki-installer

llm-wiki-installer generates a Git-auditable, agent-friendly Obsidian Markdown knowledge vault from one command.

It turns an empty folder into a durable Markdown knowledge system with clear evidence boundaries, agent policy, helper scripts, and selected upstream Skills. The generated vault is designed for a simple loop: collect approved sources, compile them into wiki/, retrieve from the wiki first, and review every change through Git.

It is not itself an initialized vault. This repository builds the generator; the generated vault lives in a separate target repository.

Quick Start

From the empty directory you want to turn into an llm-wiki vault, run:

curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | /bin/bash

The default flow is interactive. It shows selectors for dependency tools and upstream Skills, with all options selected by default. When no target path is provided, the installer writes the vault into the current directory.

If you use uv, the package is also published on PyPI as llm-wiki-installer:

uvx llm-wiki-installer

For pinned automation, include the package version you want to reproduce:

uvx llm-wiki-installer==<version> --no-interactive /path/to/knowledge-vault

Why This Exists

Most AI note workflows stop at chat answers or ad hoc generated notes. This project sets up a stricter vault contract:

• raw/ keeps user-approved source evidence.
• wiki/ keeps compiled long-term Markdown knowledge.
• wiki/index.md and wiki/maps/ provide stable retrieval entry points.
• wiki/tags.md keeps the flat kebab-case tag registry.
• wiki/log.jsonl, Git diff, and generated scripts make changes auditable.
• Upstream Skills are copied as third-party artifacts from pinned sources.

Features

• One-command local or streamed installer.
• Python installer package with no runtime third-party dependencies.
• Interactive default-all selectors for dependency tools and upstream Skill sources.
• Generated AGENTS policy, README, scripts, Codex config, index, log, and stable Obsidian settings.
• Generated stable Obsidian settings with bundled Things theme and obsidian-git plugin assets.
• Pinned upstream Skill commits for reproducible generated vaults.
• Safety checks that refuse to generate into this generator repository.
• Unit, shell integration, type, lint, coverage, and package checks.

What It Generates

llm-wiki-installer turns an empty target repository into a working vault contract:

knowledge-vault/
+-- raw/                 # user-approved source evidence
+-- attachments/         # Obsidian default attachment folder
+-- wiki/                # durable compiled knowledge
|   +-- index.md         # retrieval entry point
|   +-- tags.md          # flat kebab-case tag registry
|   +-- log.jsonl        # JSONL change log
|   +-- maps/            # topic maps for navigation
+-- outputs/             # generated reports and exports
+-- inbox/               # incoming material awaiting review
+-- archives/             # retired material
+-- schema/              # schema and policy documents
+-- AGENTS.md            # runtime policy for agents
+-- .agents/
|   +-- skills/          # flattened pinned third-party Skill artifacts
+-- .codex/
|   +-- config.toml      # Codex project config
|   +-- hooks.json       # Codex project hook config
+-- .scripts/            # verification helpers
+-- .obsidian/           # stable Obsidian settings, theme, and pinned plugin assets

The operating model is intentionally file-first:

approved sources -> raw/ -> wiki pages -> wiki/index.md + wiki/maps/
                         \-> wiki/log.jsonl -> Git diff review

agents read AGENTS.md -> retrieve with rg/fzf -> verify against raw/

Generate A Vault

Install with the published PyPI package:

uvx llm-wiki-installer /path/to/knowledge-vault

Pin the package version for repeatable automation:

uvx llm-wiki-installer==<version> /path/to/knowledge-vault

Install into the current directory with the streamed shell bootstrap:

curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | /bin/bash

Pass installer options through the same pattern:

curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | /bin/bash -s -- --force

The streamed launcher resolves GitHub Releases latest internally when LLM_WIKI_INSTALLER_REF is not set. Set LLM_WIKI_INSTALLER_REF only when intentionally testing or pinning another ref:

curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | LLM_WIKI_INSTALLER_REF=<tag-or-commit> /bin/bash

The uvx entry point uses the PyPI package and runs the same installer CLI as llm-wiki-install. It is the preferred path for automation because JSON output comes directly from the Python CLI. The streamed one-line command remains useful on machines that do not already use uv.

Install from a local checkout into the current directory:

bash /path/to/llm-wiki-installer/install.sh

Install into a specific directory:

bash install.sh /path/to/knowledge-vault

Use --force with a specific directory only when you intentionally want to overwrite generated files in the target vault:

bash install.sh --force /path/to/knowledge-vault

Preview an install plan:

bash install.sh --dry-run /path/to/knowledge-vault
bash install.sh --dry-run --json /path/to/knowledge-vault

Select tools and upstream Skills explicitly:

bash install.sh --tools rg --skills kepano /path/to/knowledge-vault
bash install.sh --tools none --skills none /path/to/knowledge-vault

Run without network bootstrap operations:

bash install.sh --offline --tools rg --skills none /path/to/knowledge-vault

Run without automatically installing missing selectable tools:

bash install.sh --no-install-tools --tools rg /path/to/knowledge-vault

When run from an interactive terminal, the installer shows two onboarding selectors before generating files:

• dependency tools: rg and fzf
• upstream Skill sources: Ar9av/obsidian-wiki and kepano/obsidian-skills

Both selectors default to all options selected. Use Up/Down to move, Space to toggle an option, and Enter to continue. Non-interactive runs, including scripted installs with redirected output, use the all-selected default. To force that behavior from a terminal, pass:

bash install.sh --no-interactive /path/to/knowledge-vault

The installer refuses to use a checked-out generator repository, or any path inside one, as the target. If you run bash install.sh from this repository, it exits instead of writing vault files here.

Generated Target Layout

The target vault receives:

inbox/
raw/
attachments/
wiki/
outputs/
archives/
AGENTS.md
README.md
.agents/skills/
.codex/config.toml
.codex/hooks.json
.scripts/postrun.sh
.scripts/check-index-log.sh
.obsidian/
.gitignore

Selected upstream Skills are installed into .agents/skills/, flattened by skill directory name. Stable Obsidian settings, the Things theme, and pinned obsidian-git plugin assets are generated under .obsidian/; volatile workspace state is not generated.

Requirements

• Python 3.13+
• Git
• rg when selected
• fzf when selected
• Network access to PyPI for uvx, GitHub for streamed installs and upstream Skills

Pass --no-install-tools to require preinstalled tools instead. Pass --offline to disable upstream Skill cloning; when --offline is used without --skills, upstream Skills default to none.

CLI Options

--force              overwrite generated files in the target vault
--no-interactive     use default all-selected prompts without asking
--yes                alias for --no-interactive
--tools LIST         rg,fzf, all, or none
--skills LIST        Ar9av,kepano, all, or none
--no-install-tools   fail if a selected missing tool would need installation
--offline            do not run network bootstrap operations
--dry-run            print the install plan without writing files
--json               print dry-run or final install summaries as JSON

Failure Handling

Installer failures are intended to be actionable. Common fixes:

• Missing Python: install Python 3.13+ or use uvx --python 3.13.
• Missing Git: install Git and rerun the same command.
• Missing rg or fzf: install the selected tool or rerun with --tools excluding it.
• Network unavailable: use --offline --skills none; selected upstream Skills require GitHub access.

Privacy And Network Boundaries

The installer does not include telemetry. It writes only under the target vault root after rejecting the generator repository itself and child paths. Network access is limited to documented bootstrap operations: fetching the published package from PyPI when using uvx, cloning this installer for streamed installs, and cloning selected pinned upstream Skill sources. Use --dry-run to inspect the plan first, and --offline to disable installer-managed network bootstrap operations after the package or launcher has already started.

Develop

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pip install --no-build-isolation --no-deps -e .

Useful development checks:

make format        # apply isort and Black to src/ and tests/
make format-check  # verify isort and Black without changing files
make lint          # run format checks and Pylint
make typecheck     # run mypy
make test          # run pytest
make coverage      # run pytest with coverage
make shell-test    # run the stubbed shell integration harness
make package-check # build sdist/wheel and run twine check
make verify        # run the full local verification stack

Optional local Git hook setup:

.venv/bin/pre-commit install

Project Map

• install.sh is the small compatibility launcher.
• src/llm_wiki_installer/ contains the Python installer package.
• src/llm_wiki_installer/templates/ contains generated vault file bodies.
• docs/technical-design.md is the architecture source of truth.
• docs/llm-wiki-generation-guide.md is the generation contract.
• docs/security-model.md describes trust boundaries, network access, command execution, and supply-chain controls.
• tests/test_installer.py covers installer behavior and generated contracts.
• tests/install_test.sh is the shell integration harness with stubbed tools.

Contributing And Security

Contributions should keep the generator and generated vault contracts aligned: when generated behavior changes, update the relevant template, docs, and tests in the same patch. See CONTRIBUTING.md for the local workflow, docs/security-model.md for the security model, and SECURITY.md for vulnerability reporting.

Credits

This project is inspired by Andrej Karpathy's LLM Wiki methodology: compile approved source material into a long-lived Markdown wiki, retrieve from the wiki first, and keep changes reviewable through files and Git.

The installer can copy upstream Skills from these projects as third-party artifacts:

• Ar9av/obsidian-wiki
• kepano/obsidian-skills

Thanks to the authors and maintainers of the tools and ecosystems this project builds on:

• Obsidian for the local-first Markdown knowledge base model this installer targets.
• ripgrep and fzf for fast local search and selection.
• Git, Python, and related tooling for the portable installer and verification toolchain.

These acknowledgements do not imply endorsement by those projects. They are included to make the dependencies and inspiration behind llm-wiki-installer clear.

License

MIT. See LICENSE.