llm-wiki-tools 0.4.0

CLI tools to read and manage LLM Wiki projects on GitHub

llm-wiki-tools

CLI tools to implement an Agentic LLM Wiki. Manage project knowledge as a "compiled codebase" that AI agents can read, write, and patch surgically.

No MCP server. No heavy infrastructure. Just Python, Markdown, and Git.

---

The Concept: Knowledge as Code

Inspired by Andrej Karpathy's vision, this tool treats documentation like software:

1. Raw Sources (raw/): Immutable "source code" (PDFs, docs, transcripts).
2. The Wiki (wiki/): "Compiled binary" (Markdown) optimized for LLM consumption.
3. The Agent (Claude Code): The "compiler" that ingests sources and patches the wiki.

---

How it works

local disk (Wiki Repo)             GitHub (Source of Truth)
──────────────────────────────    ──────────────────────────
wiki-my-project/
  raw/       ── generate ──┐
  updates/   ── update   ──┤
                           ▼
  wiki/ (Local Markdown) ──┴──► [git push] ──► GitHub Repo
                                                  │
                                                  │
  wiki-read (Local First) ◄───────────────────────┘
  (Used by Claude in any repo)

• wiki-manage: Operates on your local disk. It converts sources and writes Markdown files directly to your wiki/ folder. You review and git push manually.
• wiki-read: Used by agents to consult knowledge. It checks the local wiki/ folder first (for uncommitted changes) and falls back to the GitHub API.

---

Install

pip install llm-wiki-tools

For image vision support (OCR for PDFs/Images via Claude Sonnet):

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

---

Requirements

• Python 3.10+
• GitHub Token: Exported as GITHUB_TOKEN. Required for wiki-read and identifying the repo.
• Anthropic API Key (Optional): Exported as ANTHROPIC_API_KEY. Enables OCR for images/PDFs.

---

Configuration (.project)

Place a .project file at the root of your project.

In the Wiki Repo (Full Access)

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

In a Project Repo (Read-Only)

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

---

Commands

wiki-read (Consult Knowledge)

• wiki-read <page>: Print page content.
• wiki-read --list: List all pages.
• wiki-read --search "query": Full-text search across the wiki.

wiki-manage (Maintain Knowledge)

• Status: wiki-manage status (File counts and pending updates).
• Ingestion:
  • wiki-manage generate: Convert raw/ files and emit for agent analysis.
  • wiki-manage update: Convert updates/ files, emit, and move them to raw/.
• Surgical Writing (via STDIN):
  • wiki-manage write <page>: Write/Overwrite a full page.
  • wiki-manage patch <page> "<header>" <action>: Modify a specific section.
• Maintenance:
  • wiki-manage lint: Check for broken links, orphan pages, and missing requirements.
  • wiki-manage delete <page>: Delete a page locally.

---

Surgical Patching

The patch command allows agents to modify specific sections of a page without rewriting the entire document. This saves tokens and prevents hallucinations.

Actions:

• append: Insert content at the end of the section.
• prepend: Insert content immediately after the header.
• replace: Replace the section body.
• delete: Remove the entire section (header included).

Example:

cat << 'EOF' | wiki-manage patch architecture "## Database" replace
The project uses PostgreSQL 16 on AWS RDS.
EOF

---

Agent Guidelines (CLAUDE.md)

Add this to your Wiki Repo's CLAUDE.md to guide the AI:

## Wiki Management Rules
- **Sources**: `raw/` is immutable. Never edit files there.
- **Ingestion**: Use `wiki-manage update` to process new docs.
- **Editing**: Prefer `wiki-manage patch` for surgical updates to existing pages.
- **Writing**: Use `cat << 'EOF' | wiki-manage ...` for all write/patch ops.
- **Changelog**: Always update `wiki/changelog.md` after any modification.
- **Validation**: Run `wiki-manage lint` before finishing a task.
- **Git**: You write to local `wiki/` only. The human will push to GitHub.

---

Required Pages

• index.md: Must contain links to all other pages.
• changelog.md: A reverse-chronological log of updates.

---

Publishing to PyPI

1. Bump version in pyproject.toml.
2. pip install build twine
3. python -m build
4. twine upload dist/*

---