📖 pi-codebase-wiki

Keeps a wiki for your code that updates itself — reads your git history and docs so you can ask questions about your codebase.

The Idea

Instead of RAG retrieval that starts fresh on every query, you build a persistent, compounding wiki from your git history and code. Knowledge compiled once and kept current beats knowledge re-derived on every question.

pi-codebase-wiki reads your commits and docs, incrementally builds a structured wiki, and keeps it current as code changes. Works as a pi extension, a standalone CLI, or a programmatic library.

Three Ways to Use

1. As a pi Extension

For agents running inside pi — automatic context injection, tool calls, and commands.

pi install @0xkobold/pi-codebase-wiki

Then use tools like wiki_ingest, wiki_query, wiki_lint and commands like /wiki, /wiki-init, /wiki-ingest all.

2. As a CLI 🐹

Powered by kapy — agent-first, works in any terminal. No pi required.

Note: For string flags, use --flag=value syntax (e.g. --summary="My summary") to avoid parsing ambiguity with kapy's global arg scanner.

# Install globally
bun install -g @0xkobold/pi-codebase-wiki

# Initialize wiki in current project
wiki wiki-init

# Ingest sources
wiki ingest all

# Search the wiki
wiki query "Why did we switch from LevelDB to SQLite?"

# Health check
wiki lint

# Show stats
wiki status

# Create an entity page
wiki entity auth-module --summary="Handles user authentication" --type=module

# Create an ADR
wiki decision "Use SQLite over LevelDB" --context="Need reliable persistence" --choice="SQLite for durability"

# Generate changelog
wiki changelog --since="2 weeks ago"

# Trace feature evolution
wiki evolve auth

# Launch local web UI with graph visualization
wiki serve --port=3000 --open

# All commands support --json for machine-readable output
wiki status --json
wiki query "how does hot-reload work?" --json

Every command supports --json (structured output) and --no-input (non-interactive) — designed for agents and automation.

3. As a Library

Import the pure operations directly — no pi, no CLI, just functions.

import {
  initWiki,
  ingestCommits,
  ingestFileTree,
  searchWiki,
  lintWiki,
  WikiStore,
  getRecentCommits,
} from "@0xkobold/pi-codebase-wiki/core";

// Initialize
const store = new WikiStore(".codebase-wiki/meta/wiki.db");
await store.init();

// Ingest
const result = await ingestCommits(process.cwd(), config, store, "1 week ago");

// Query
const matches = searchWiki("how does auth work", wikiPath, store, 10);

// Lint
const issues = lintWiki(wikiPath, store);

Three-Layer Architecture

┌─────────────────────────────────────┐
│  Layer 1: Raw Sources (IMMUTABLE)  │  git log, source files, configs
├─────────────────────────────────────┤
│  Layer 2: The Wiki (LLM-OWNED)      │  .codebase-wiki/ — markdown pages
├─────────────────────────────────────┤
│  Layer 3: Schema (CO-EVOLVING)      │  .codebase-wiki/SCHEMA.md
└─────────────────────────────────────┘

Quick Start

# As a pi extension
pi install @0xkobold/pi-codebase-wiki
/wiki-init
/wiki-ingest all

# As a standalone CLI
bun install -g @0xkobold/pi-codebase-wiki
wiki wiki-init
wiki ingest all

CLI Commands

| Command | Description | |---------|-------------| | wiki wiki-init | Initialize .codebase-wiki/ for current project | | wiki ingest [source] | Ingest commits, tree, smart, llm, or all | | wiki query <question> | Search the wiki | | wiki lint | Health check: orphans, stale pages, broken links | | wiki status | Show page counts, staleness, last ingest | | wiki entity <name> | Create or update an entity page | | wiki decision <title> | Create an Architecture Decision Record | | wiki concept <name> | Create or update a concept page | | wiki changelog | Generate changelog from recent commits | | wiki evolve <feature> | Trace feature evolution over time | | wiki reindex | Rebuild the wiki index | | wiki serve | Start local web UI with graph visualization |

pi Tools

| Tool | What It Does | |------|-------------| | wiki_ingest | Ingest commits, files, or docs into the wiki | | wiki_query | Search the wiki and synthesize answers | | wiki_lint | Health check: orphans, stale pages, broken links | | wiki_status | Show wiki stats, staleness, coverage | | wiki_entity | Create or update an entity page | | wiki_decision | Create an Architecture Decision Record (ADR) | | wiki_concept | Create or update a concept page | | wiki_changelog | Generate changelog from recent commits | | wiki_evolve | Trace how a feature changed over time |

pi Commands

| Command | Description | |---------|-------------| | /wiki | Show wiki status and INDEX.md | | /wiki-init | Initialize the wiki for the current project | | /wiki-ingest [source] | Ingest commits, tree, docs, or all | | /wiki-query <question> | Ask a question against the wiki | | /wiki-lint | Run health checks | | /wiki-reindex | Rebuild the wiki index |

Wiki Structure

.codebase-wiki/
├── SCHEMA.md            # The constitution (how the LLM maintains the wiki)
├── INDEX.md             # Master index with links to all pages
├── CHANGELOG.md         # Auto-generated from commits
├── entities/            # Code entity pages
│   ├── auth-module.md
│   └── event-bus.md
├── concepts/            # Cross-cutting concept pages
│   └── hot-reload-pattern.md
├── decisions/           # Architecture Decision Records
│   └── 001-sqlite-over-leveldb.md
├── evolution/           # How things changed over time
│   └── auth-evolution.md
├── comparisons/         # Side-by-side analysis
│   └── pi-learn-vs-generative-agents.md
├── templates/           # Page templates
│   ├── entity.md
│   ├── concept.md
│   ├── decision.md
│   └── evolution.md
└── meta/
    ├── LOG.md           # Ingest log
    ├── STATS.md         # Wiki health stats
    └── wiki.db          # SQLite metadata (sql.js)

How It Works

1. Ingest: You add a source (commits, file tree, docs). The LLM reads it, extracts key information, and integrates it into the wiki — creating pages, updating cross-references, appending to the log. A single commit might touch 5-10 wiki pages.

2. Query: You ask a question. The LLM searches the wiki (not the raw source), reads relevant pages, and synthesizes an answer. Good answers get filed back as new pages. Knowledge compounds.

3. Lint: Periodic health checks find contradictions, orphans, stale pages, broken links, and missing concepts. Think of it as eslint for knowledge.

Key Principle

The LLM writes. You read. You curate sources and ask questions. The LLM does the bookkeeping.

Web UI

wiki serve launches a local web interface with:

• Page browser — sidebar with all pages, type-coded dots (entity, concept, decision, etc.)
• Content viewer — rendered markdown with clickable [[wikilinks]] and metadata
• Full-text search — search across all pages with relevance scoring
• Interactive graph — force-directed node graph showing how pages connect, drag nodes, zoom, double-click to navigate
• Dark mode — because we live in terminals

wiki serve              # Start on port 3000
wiki serve --port=8080 # Custom port
wiki serve --open      # Auto-open browser

All data comes from the API (/api/pages, /api/graph, /api/search). The UI is a single HTML page — no build tools, no external deps.

License

MIT