Wikifier

A zero-dependency codebase wiki for AI agents — token-efficient maps so LLMs look things up instead of re-reading full sources.

Wikifier is an agent-to-agent tool: it builds a living map of a project (health matrix, dependency graph, short file summaries) and agents keep that map current as they work. Humans can peek via a small dashboard; the product is the agent loop, not a general docs site or IDE.

Works from small scripts to large monorepos. Deep import/include maps (zero-dep regex parsers):

Health/journal still work for any monitored path. Parsers are pragmatic regex (not full cargo/go.mod/classpath/-I resolution). On huge monorepos, split scope deliberately:

Or pass --directory=pkg/ / --max-files=N per run. Raise dirty cap with WIKIFIER_CHECK_CHANGES_MAX (default 2000) only when needed. Never set project_root to a multi-repo parent of clones.

Why

Context windows are finite. Re-reading a large file to answer “what is this and who depends on it?” wastes tokens.

Map first, wiki depth second: update-maps builds the structural map automatically. Rich per-file wiki text is filled by agents as they work — not a free full-repo “understand everything” pass on init.

First run (bootstrap the map)

pip install wikifier            # pure Python stdlib core — no runtime deps
pip install wikifier[mcp]       # optional Model Context Protocol (MCP) server

cd /path/to/your/project
wikifier init                   # seeds index.html + lean path-list templates
# Edit monitored_paths.txt + map_paths.txt to package roots (not bare ".") on real trees
wikifier update-maps            # full structural map → library.md + import cache
wikifier health --summary       # matrix counts
wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only

Always set an explicit root for external trees: WIKIFIER_PROJECT_ROOT=/abs/path wikifier …

MCP session_bootstrap → readiness: blocked? That means lean scope and/or the map are missing (often bare . monitor + never ran update-maps) — not a broken install. Fix: write lean monitored_paths.txt / map_paths.txt, then update-maps. Agent contract: skills/run.md § Readiness blocked; dogfood: Findings/readiness-blocked-bare-monitor-2026-07.md.

Steady state (only touch what needs it)

Full protocol: skills/run.md (Agent Protocol v0.6 — package 4.6.x).

wikifier session-bootstrap      # one-shot: root, health, attention, actions[]
wikifier check-changes          # content-honest dirty; red ghosts (missing paths)
# prioritize 🔴 then *actionable* 🟡 — do NOT re-wiki 🟢 Green files
wikifier prepare-edit path/file.py   # wiki + status + deps/dependents preflight
# ... edit only those sources ...
wikifier record-change "path/file.py" "why this changed"   # required
# ... refresh that file’s wiki summary only ...
wikifier mark-green "path/file.py"
wikifier update-maps            # only if imports/structure changed (warm 0-dirty is cheap)
# removals:
wikifier record-deletion "path/gone.py" "why removed"

Core 6 (prefer every session — MCP or library/CLI):
session_bootstrap → check_changes → prepare_edit → suggest_next_actions (json actions[]) → record_change → mark_green.

Advanced intel as needed: get_dependencies, get_dependents, get_cycles, barrels/diagnostics. Always pass project_root= / WIKIFIER_PROJECT_ROOT for external trees. Never point project_root at a multi-repo parent folder (e.g. a directory of clones).

What you get

• Import analysis — Python, JS/TS (ESM/CJS, barrels), Rust (use/mod + best-effort crate:: paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
• Incremental pipeline — pure-Python update-maps: dirty parse → import cache → reverse deps → cycles → library.md
• Warm agent maps (4.6.3–4.6.7) — zero-dirty + index-first candidates (re-list only when fingerprint / map-scoped index / live count disagree); MapScope keeps collect, live count, index filter, and prune aligned; stdlib SQLite; content-hash dirty
• Two path lists — map_paths.txt = map package roots; monitored_paths.txt = wiki/health watch (independent — wiki file lists never collapse the map)
• Partial-map honesty — map_coverage on update_maps / bootstrap / suggest_next; update_maps_until_complete when incomplete
• Cache ops — wikifier cache-status; JSON dual-write deprecated default-off (WIKIFIER_CACHE_JSON=1 opt-in); dual-read for migrate
• Selective agent work — health + suggest bias to 🔴/actionable 🟡 only; ACS v1.3 reason_code / agent_signal; prefer actionable_low_conf_edges + reason codes — never raw low_conf_edges averages alone
• Scale — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
• MCP tools — optional server for Claude, Cursor, Cline, and other MCP clients
• Zero core dependencies — stdlib only; forks can add their own stack on top
• Agent navigability — short AGENT MAP docstrings on core modules; self-tests under tests/ (not buried in parsers)

Performance (measured)

Full / heavy runs (historical order-of-magnitude):

Warm 0-dirty re-runs after 4.6.7 (same machine class; scoped; candidates reused — agent session path):

Residual floor on large scopes is mtime/stat + live count under MapScope (not full JSON re-walk). Sub-100ms is not a hard SLA on every 1k+ tree.

Tests: python -m unittest discover tests (stdlib only; 125 cases including MapScope / index-first / dual-write).

Commands

Library: from wikifier import session_bootstrap, prepare_edit, check_changes, record_change, mark_green, suggest_next_actions, update_maps, health, list_core_tools.

MCP

WIKIFIER_PROJECT_ROOT=/abs/path/to/project wikifier-mcp
# or: python3 -m wikifier.mcp.server

Setup and tool list: wikifier/mcp/README.md.

Human dashboard (secondary)

wikifier init drops a single index.html. Prefer wikifier serve (e.g. http://localhost:8787/index.html) — file:// can’t load project files. The markdown artifacts and CLI/MCP tools stay the source of truth; the UI is a read-only window.

Scope

In: agent-maintained codebase wiki, dependency intelligence, token-saving lookup for LLMs and coding agents.
Out: general human documentation systems, IDE plugins, “docs for everyone” product growth.

Agent navigability: Prefer protocol (skills/run.md) + MCP Core 6 over reading 20k LOC of parsers/cache. Production modules carry a short AGENT MAP docstring; self-tests live under tests/ and tests/selftest/, not inline at the bottom of parsers.

Links

• PyPI · GitHub
• Agent protocol: skills/run.md
• Changelog: CHANGELOG.md
• Dogfood notes: Findings/