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). Prefer lean monitored_paths.txt on huge monorepos; raise dirty cap with WIKIFIER_CHECK_CHANGES_MAX (default 2000) only when needed.

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 + human index.html
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 …

Steady state (only touch what needs it)

Full protocol: skills/run.md.

wikifier check-changes          # yellow dirty files; red ghosts (missing paths)
# prioritize 🔴 then 🟡 — do NOT re-wiki 🟢 Green files
# ... 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
# removals:
wikifier record-deletion "path/gone.py" "why removed"

MCP Core 6 (start every session): get_project_status, check_changes, get_files_needing_attention, get_file_wiki, suggest_next_actions, record_change / mark_green. Intel as needed: get_dependencies, get_dependents, get_cycles. Always pass project_root= for external trees.

What you get

• Import analysis — Python, JS/TS (ESM/CJS, barrels), Rust, Go, C/C++ includes, C# usings; per-edge confidence; name-routed barrel expansion for TS/JS
• Incremental pipeline — pure-Python update-maps: dirty parse → import cache → reverse deps → cycles → library.md
• Selective agent work — health + suggest bias to 🔴/🟡 only; ACS actionable low-conf excludes stdlib/external noise
• 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)

Tests: python -m unittest discover tests (stdlib only).

Commands

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

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/