openwiki

Builds and maintains a source-grounded, interlinked markdown wiki for a code repository, and serves a browser UI to read and search it. Point it at a git repo: an agent reads the source, plans a hierarchical index, writes one cited page per topic, and keeps the wiki current from git diffs on a per-wiki schedule. Pages persist in iii-state; the engine serves the UI and JSON API under /openwiki.

Install

iii worker add openwiki

This pulls state, cron, and llm-router transitively. Add a model provider through the console's onboarding (anthropic, openai, codex, ...) and pages are model-written; the provider credential lives in the llm-router config, never in this worker.

For the best tier, agent-orchestrated pages written by one sub-agent per page with line citations, add the harness stack as well:

iii worker add harness

harness transitively pulls session-manager, context-manager, shell (jailed git for clone/diff), and the model providers. openwiki degrades gracefully when a worker is absent:

Present	Pages are
harness + a configured provider	agent-orchestrated, line-cited (best)
llm-router only	model-written from pre-selected files
neither	heuristic, built from file headers, always works

Quickstart

Open the browser UI on the engine's HTTP port:

http://localhost:3111/openwiki

Or drive it from the CLI:

iii trigger openwiki::generate --json '{"repo_url":"https://github.com/owner/repo"}'
# -> { "wiki_id": "<wiki_id>", "status": "started" }

iii trigger openwiki::status --json '{"id":"<wiki_id>"}'    # poll until phase = ready
iii trigger openwiki::page   --json '{"id":"<wiki_id>","slug":"overview"}'
iii trigger openwiki::search --json '{"id":"<wiki_id>","q":"config"}'

openwiki::refresh { id } is incremental: it pulls the clone, diffs against the recorded commit, and regenerates only the pages whose source changed. openwiki::set-schedule { id, schedule } puts that refresh on a per-wiki cadence (off | 3h | 6h | 12h | daily | weekly | a cron string); a content-hash gate keeps an unchanged repo from churning the wiki.

The full function catalogue (generation, scoped source readers for writer sub-agents, cited Q&A via openwiki::ask, Mermaid diagrams, AGENTS.md export, lint) is one iii worker info openwiki away. HTTP triggers mirror the read/generate functions under /openwiki/api/*, generation progress streams live over SSE, and page citations deep-link to source at the pinned commit.

openwiki also registers openwiki::read-wiki-structure, openwiki::read-wiki-contents, and openwiki::ask-question, which the mcp worker advertises to any MCP client:

iii worker add mcp

How generation works

1. Clone the repo (through the shell worker, with a local git fallback), inventory its files, and record the commit so citations deep-link to exact source.
2. A lead agent explores the clone through openwiki's scoped readers (openwiki::src::read / src::list / src::grep) and plans a reading-ordered index. The model decides how many pages the repo needs and follows the repo's own docs index (llms.txt, a docs/ tree) when present.
3. The lead spawns one writer sub-agent per page in parallel. Each writer reads its focused files and stores its finished page with openwiki::write-page; openwiki turns citations into pinned-commit source links and rejects a page that comes back too thin.
4. Pages stream into the UI as each writer lands; the lead submits only the table of contents.

Configuration

• Model: pick one in the browser UI's generate form (populated from the router's live catalog, grouped by provider), pass model to openwiki::generate, or set OPENWIKI_MODEL. Any model the router advertises works. Default claude-haiku-4-5-20251001.
• refresh_default: the auto-refresh cadence new wikis start with (off by default; each wiki overrides it in the UI). Editable in the console like the other openwiki config, or seed it with OPENWIKI_REFRESH_DEFAULT.
• OPENWIKI_DATA: wiki store and clone directory (default /tmp/openwiki-data). Must resolve inside the shell worker's fs.host_roots when git runs through shell.
• OPENWIKI_MAX_PARALLEL: concurrent page writers (default 3).

License

Apache-2.0