pi-openwiki-adapter

Pi package exposing generated OpenWiki documentation to Pi Coding Agent as token-efficient codebase navigation tools.

This package is intentionally a thin wrapper around the published openwiki CLI and generated openwiki/ Markdown directory. It does not generate documentation unless the user explicitly runs /openwiki update.

Tested against OpenWiki 0.5.1 (September 2026). It reads the OKF front matter, quickstart.md, per-directory indexes, .last-update.json, .page-manifest.json and .run.json that 0.5 writes, and degrades gracefully for wikis generated by older versions.

Install OpenWiki

OpenWiki needs Node 22 or newer.

npm install -g openwiki

Then initialize docs in a repository:

cd /path/to/repo
openwiki --init

Install this Pi package

pi install npm:pi-openwiki-adapter

# or, from a local checkout
pi install /path/to/pi-openwiki-adapter

Tools

• openwiki_status — CLI availability and version, wiki location, page and Claims counts, the last run (mode, time, model, git head, interrupted or not), drift since then, any run in progress.
• openwiki_outline — the table of contents. Without a focus: the quickstart.md task-routing headings, then one line per concept page (OKF title and description) grouped by directory. Index and log pages are not listed. With a focus, matching pages are expanded to their sections so a section id can be read directly.
• openwiki_search — ranked search where front-matter title, description, tags and path outweigh body mentions; each hit carries a page id, the best-matching section id, and the page description as its snippet.
• openwiki_read — a page or page#section. The YAML front matter is folded into one metadata line (title, type, status, tags, as-of date, description) instead of being sent raw. Ids may carry OpenWiki's /openwiki/ prefix.
• openwiki_update_suggestion — whether a refresh looks worthwhile, from OpenWiki's own last-run record rather than file timestamps. Never runs an update.

Tools are enabled only when the current Pi session already has codebase lookup capability (read, grep, find, or ls).

Slash command

Use /openwiki <subcommand>:

• doctor - CLI version, wiki, last run, drift since then, capability gate
• setup - interactive freshness policy setup
• init / update - confirms, then runs openwiki --init|--update --print
• visualize - starts openwiki visualize in the background (local graph + reader, opens the browser)
• install - shows install guidance
• enable / disable - toggles project config

Run progress

An OpenWiki generation run can take many minutes and prints nothing until it exits. This package reads OpenWiki's own checkpoint at openwiki/.run.json to report progress:

• The footer status bar shows a live line, for example openwiki: update · page 7/23 · 4m12s.
• /openwiki doctor, openwiki_status, and openwiki_update_suggestion report the phase, the page counter, and the run age.
• Runs started outside Pi are detected too, because the checkpoint is the same file. The package checks it at session start and at the start of each turn.
• /openwiki update and /openwiki init warn and ask for a second confirmation when a run already looks live. Two writers against one checkpoint corrupt the run.

A run whose checkpoint has not changed for over five minutes reads as interrupted. OpenWiki resumes such a run from its checkpoint.

Quitting Pi while /openwiki update or /openwiki init is running stops the run (and any /openwiki visualize server this session started); the next run resumes from the checkpoint. /reload and switching sessions do not stop it. Pi tears down its UI before extensions learn about a quit, so this cannot be a prompt.

Configuration

Project config lives at .pi/openwiki.json.

{
  "enabled": true,
  "openwiki": {
    "command": "openwiki",
    "cwd": ".",
    "timeoutMs": 1800000
  },
  "freshness": {
    "managedBy": "manual",
    "nudge": true,
    "significantFileThreshold": 10
  }
}

A global config at ~/.pi/agent/openwiki.json uses the same shape. Project values win.

Freshness

Freshness nudges are advisory. The package never updates OpenWiki automatically.

Since OpenWiki 0.5 every run ends by writing openwiki/.last-update.json (time, mode, model, git head, complete or interrupted) and a per-page openwiki/.page-manifest.json (the head each page was verified against). Drift is measured against that record: commits and changed source files since the recorded head (git diff --name-only <head>..HEAD, wiki paths excluded), uncommitted changes, "important" files (manifests, schemas, routes, configs), an interrupted last run, and pages whose baseline is older than the run's. A wiki without that record (generated before 0.5) falls back to comparing the openwiki/ directory mtime with the latest commit.

Set freshness.nudge to false to silence the session-start notice. /openwiki doctor still reports drift.

Claim evidence checks

OpenWiki 0.5's Grounded Claims cite repository files as evidence (repo://path#L1-L20) and its pre-update check refuses a run outright when a cited file is a symbolic link. The adapter scans openwiki/.claims/ before /openwiki update, and in doctor and openwiki_status, and reports the offending files with their targets and the pages that cite them, so the fix (make the path a regular file, for example a real AGENTS.md with CLAUDE.md containing @AGENTS.md) is known before any tokens are spent. Missing evidence files are reported too; OpenWiki handles those itself by reworking the affected pages.