Keeps a wiki for your code that updates itself — reads your git history and docs so you can ask questions about your codebase.
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.
For agents running inside pi — automatic context injection, tool calls, and commands.
pi install @0xkobold/pi-codebase-wikiThen use tools like wiki_ingest, wiki_query, wiki_lint and commands like /wiki, /wiki-init, /wiki-ingest all.
Powered by kapy — agent-first, works in any terminal. No pi required.
Note: For string flags, use
--flag=valuesyntax (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?" --jsonEvery command supports --json (structured output) and --no-input (non-interactive) — designed for agents and automation.
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);┌─────────────────────────────────────┐
│ 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
└─────────────────────────────────────┘
Export wiki pages to Notion databases with zero-config Kanban boards. The wiki is the source of truth — Notion is the readable interface.
- Create a Notion integration at notion.so/my-integrations
- Copy the API token and share a root Notion page with the integration
- Set credentials (either env vars or
~/.env.notion):
# Option A: Environment variables
export NOTION_API_TOKEN="ntn_your_token"
export NOTION_ROOT_PAGE_ID="your-root-page-id"
# Option B: ~/.env.notion (auto-detected)
NOTION_API_TOKEN=ntn_your_token
NOTION_ROOT_PAGE_ID=your-root-page-idwiki_notion_sync # Export all wiki pages to Notion
wiki_notion_sync({"dryRun": true}) # Preview without writing
wiki_notion_status # Show sync status and history
- Per-project databases: Each project gets its own Notion database under the root page
- Automatic Kanban boards: Three board views are created — Page Lifecycle (by Status), ADR Pipeline (by ADR Status), Ingestion Health (by Ingest Status)
- Incremental sync: Only changed pages are updated on subsequent syncs
- Wiki is source of truth: Export direction only (for now) — wiki edits always win
Uses Notion's v5 API with initial_data_source for database creation and data_source_id for page creation. Status properties use select type (not status) for simpler API compatibility while still enabling Kanban board views.
# 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| 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 |
| 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 |
wiki_notion_sync |
Export wiki pages to Notion databases |
wiki_notion_status |
Show Notion sync status and history |
| 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 |
.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-sync.config.json # Notion sync state
└── wiki.db # SQLite metadata (sql.js)
-
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.
-
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.
-
Lint: Periodic health checks find contradictions, orphans, stale pages, broken links, and missing concepts. Think of it as
eslintfor knowledge.
The LLM writes. You read. You curate sources and ask questions. The LLM does the bookkeeping.
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 browserAll data comes from the API (/api/pages, /api/graph, /api/search). The UI is a single HTML page — no build tools, no external deps.
MIT