llm-wiki-tools 0.3.0

CLI tools to read and manage LLM Wiki projects on GitHub

wiki-tools

CLI tools to read and manage LLM Wiki projects on GitHub.

Two commands:

• wiki-read — read wiki pages from GitHub. Used by Claude Code agents during development.
• wiki-manage — generate, update, and lint the wiki. Used in the wiki repo.

No MCP server. No extra infrastructure. Just Python + GitHub API.

---

How it works

local disk                        GitHub
──────────────────────────────    ──────────────────────
wiki-repo/
  raw/       ──── wiki-manage ──► wiki-repo/wiki/
  updates/        generate
                  update
                                  wiki-read ◄─── Claude Code
                                  (any project repo)

• raw/ and updates/ live locally — never pushed to GitHub
• wiki/ lives on GitHub — the permanent, versioned knowledge base
• wiki-read reads from GitHub and is available in any project repo
• wiki-manage reads locally and writes to GitHub, used only in the wiki repo

---

Install

pip install llm-wiki-tools

For image vision support (optional):

pip install "llm-wiki-tools[vision]"

Or directly from GitHub:

pip install git+https://github.com/YOUR_USERNAME/wiki-tools.git

---

Requirements

Python 3.10+

GitHub token — create one at https://github.com/settings/tokens with repo scope, then add it to your shell profile:

# ~/.zshrc or ~/.bashrc
export GITHUB_TOKEN=ghp_yourtoken

---

Repository structure

Wiki repo — where the wiki lives

wiki-my-project/          ← cloned locally
  .project                ← includes wiki_local_path
  raw/                    ← original documents (local only, not on GitHub)
  updates/                ← new documents to ingest (local only, not on GitHub)
  CLAUDE.md

github: username/wiki-my-project
  wiki/                   ← generated markdown pages (GitHub only)

.gitignore in the wiki repo:

raw/
updates/

Project repo — where you write code

my-project/
  .project                ← wiki_repo only, no wiki_local_path needed
  CLAUDE.md
  src/

---

.project format

In the wiki repo — needs both wiki_repo and wiki_local_path:

{
  "project_id": "my-project",
  "wiki_repo": "username/wiki-my-project",
  "wiki_local_path": "/Users/yourname/projects/wiki-my-project"
}

In the project repo — only needs wiki_repo:

{
  "project_id": "my-project",
  "wiki_repo": "username/wiki-my-project"
}

The tools walk up from the current directory to find .project, so they work from any subdirectory.

---

Commands

wiki-read

wiki-read index              # read a page (with or without .md)
wiki-read architecture
wiki-read --list             # list all wiki pages
wiki-read --search "auth"   # full-text search across pages
wiki-read --info             # show current project, repo, and local path

Reads from GitHub. Works in any repo that has a .project file.

wiki-manage

wiki-manage status             # show file counts for raw/ (local), updates/ (local), wiki/ (github)
wiki-manage generate           # read local raw/, generate wiki pages on GitHub
wiki-manage update             # read local updates/, update wiki on GitHub, move files to raw/
wiki-manage delete <page>      # delete a wiki page from GitHub
wiki-manage lint               # check for broken links, orphan pages, missing required pages

Reads from local disk, writes to GitHub. Requires wiki_local_path in .project.

Note on deletions: updating a document in updates/ automatically removes sections that no longer exist — Claude rewrites the affected pages based on the new content. Use wiki-manage delete only when an entire page becomes obsolete.

---

Workflows

Generate wiki from scratch

1. Put your documents in raw/ locally
2. Open Claude Code in the wiki repo
3. Tell Claude: "Generate the wiki from raw/ using wiki-manage generate"

Claude runs wiki-manage generate, reads the raw files, generates wiki pages, and writes them to GitHub.

Ingest new documents

1. Put new documents in updates/ locally
2. Open Claude Code in the wiki repo
3. Tell Claude: "Update the wiki with the new documents in updates/"

Claude runs wiki-manage update, reads the updates, updates the relevant wiki pages on GitHub, updates changelog.md, then moves the files from updates/ to raw/ locally.

Lint

Tell Claude: "Run a lint on the wiki and fix any issues"

Claude runs wiki-manage lint and fixes broken links, orphan pages, and missing required pages.

Read wiki during development

In any project repo, Claude Code agents can read the wiki via bash:

wiki-read index
wiki-read decisions
wiki-read --search "payment"

---

Required wiki pages

Only two pages are always required:

Page	Content
index.md	Entry point — links to every other page
changelog.md	Chronological log of every wiki update

All other pages are dynamic and determined by the project content. index.md is the source of truth for which pages exist.

---

CLAUDE.md

Add this to the CLAUDE.md in every repo to tell Claude which tools are available and how to use them.

Wiki repo:

## Wiki tools

Read the wiki:
  wiki-read <page>
  wiki-read --list
  wiki-read --search <query>

Manage the wiki (requires wiki_local_path in .project):
  wiki-manage status
  wiki-manage generate
  wiki-manage update
  wiki-manage lint

Always start with `wiki-read index` to orient yourself.
After every update, add an entry to changelog.md.

Project repo:

## Wiki tools

Read the project wiki with:
  wiki-read <page>
  wiki-read --list
  wiki-read --search <query>

Always read `wiki-read index` at the start of every session.

---

Publish a new version to PyPI

pip install build twine
python -m build
twine upload dist/*

Bump the version in pyproject.toml before each release.