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

This adapter needs OpenWiki 0.5.0 or newer (npm i -g openwiki@latest; openwiki --version to check). Older releases abort a whole update with Could not restore /openwiki/…: Error: File … not found whenever the worker for a new page exits without submitting; 0.5.x skips that page and carries on. /openwiki doctor and openwiki_status warn when the installed CLI is too old.

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.

Which model writes the wiki

/openwiki init and /openwiki update run OpenWiki's own agent (openwiki --init|--update --print), which normally reads its provider from ~/.openwiki/.env (OPENWIKI_PROVIDER, OPENWIKI_MODEL_ID, that provider's key) — not Pi's model. This package can point that run at what Pi is using instead. routing.mode picks how:

• session (default) — the provider and model your Pi session is on. The extension asks Pi's model registry for the model's API dialect, base URL and the credential it would send, and translates that into the environment OpenWiki's matching provider reads (shell environment wins over ~/.openwiki/.env): Anthropic-dialect models (Anthropic, bedrouter's auto/rung aliases, any Anthropic-shaped gateway) → OPENWIKI_PROVIDER=anthropic with ANTHROPIC_BASE_URL set to the same endpoint; OpenAI-dialect models → openai, openrouter or openai-compatible depending on the host (bedrouter's gpt-oss aliases land on openai-compatible at …:20129/v1); Gemini → gemini. Nothing is written to disk; the credential lives only in the spawned process's environment.
• bedrouter — always a local bedrouter on 127.0.0.1:<port> with OPENWIKI_MODEL_ID=<model>, whatever Pi is on.
• native — leave OpenWiki's own configuration alone.

Each mode falls through to the next when it cannot apply — session → bedrouter → native — and the confirmation dialog, /openwiki doctor and openwiki_status all say which one will be used and why the others were skipped. The session route is skipped when the model has no API key Pi can hand over, when its dialect has no OpenWiki provider (e.g. Pi's direct Bedrock provider), and when you are signed in with OAuth (Claude Pro/Max or ChatGPT subscription logins): those tokens are bound to Pi and their terms do not permit reuse by another program, so OpenWiki cannot present them. Sign in with an API key, or run through bedrouter, if you want the wiki written by that vendor.

{ "routing": { "mode": "session", "port": 20129, "model": "auto" } }

Routed runs (session or bedrouter) are spawned with a throwaway OPENWIKI_CONFIG_DIR: a copy of your ~/.openwiki/.env with OPENWIKI_PROVIDER, OPENWIKI_MODEL_ID and OPENWIKI_REASONING_EFFORT removed, plus symlinks to everything else in ~/.openwiki (skills, connectors, wiki, telemetry ids). OpenWiki reads its .env for every key the environment does not define and offers no way to unset one, so a reasoning effort saved for one provider would otherwise fail every run routed to another (OPENWIKI_REASONING_EFFORT is not supported for provider "openai-compatible" …). Your real .env is never modified; native runs do not use the shim.

port and model describe the bedrouter fallback (auto lets it pick the rung per request; a rung name such as sonnet pins it).

Configuration

Project config lives at .pi/openwiki.json.

{
  "enabled": true,
  "openwiki": {
    "command": "openwiki",
    "cwd": ".",
    "timeoutMs": 1800000
  },
  "routing": { "mode": "session", "port": 20129, "model": "auto" },
  "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.

OpenWiki 0.5 can finish a run, exit 0, and still record it as interrupted at the previous head: it does this when a page worker exited without calling submit (the page is restored and skipped) or when the repository source changed mid-run. The pages it did verify carry the real head in .page-manifest.json, so when every page agrees on one newer head the adapter measures drift from that head, reports the baseline as held back (with the model that ran) instead of a spurious "N commits since", and the update dialog warns before spending money on the same model again. After a run, the two lines OpenWiki prints for these cases are surfaced as a separate warning with the page names rather than left inside the run log. Until a run completes with every page submitted, OpenWiki disables its no-op fast path and re-plans on each update.

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.