Get a live wiki from your repo in five minutes.
Install the CLI, draft a wiki from the repository you're standing in, build it to static HTML, preview it. Four commands, and the only step that wants an API key is the one you can skip.
Install
Nothing to install if you just want to try it — run it straight from npm, in the root of any repo:
For repeat use, install it globally. Needs Node.js 18 or newer, and nothing else — no config file, no account. An API key is optional; it unlocks the AI pass described below.
Prefer to run the unreleased version, or hack on it? Build from source:
Initialize
Run this from the root of the repo you want documented. It asks who the wiki is for, then drafts real pages from your repo's own content — no blank templates to fill in.
Your answer decides which sections get drafted:
- Everything (the default) — all ten sections, ordered so the pages a newcomer needs come before the ones you look things up in:
start-here,getting-started,guides,onboarding,how-it-works,technologies,cookbook,faq,troubleshooting,reference - Technical —
start-here,onboarding,how-it-works,technologies,reference,cookbook - User guide —
start-here,getting-started,guides,faq,troubleshooting
The choice is saved to wikipilot.config.json, so later builds and the sync skill both know what belongs in this wiki.
--preset <technical|user-guide|all>— answer up front and skip the question-y, --yes— take the default (both audiences); use this in CI-o, --out <dir>— where to scaffold the wiki (default./wiki)--no-skill— skip scaffolding the Claude Code sync skill
The prompt only appears on an interactive terminal. Piped or non-TTY runs take the default instead of hanging, so wikipilot init is safe to put in a script.
The AI deep investigation
After drafting, init asks two more questions: whether to run the deep-investigation pass, and which provider should do it — Anthropic (the default, claude-opus-5-5), OpenAI, Gemini, or a custom OpenAI-compatible endpoint. Say yes and the agent lists, reads, and greps your repository, traces the main flow through the code, then rewrites the drafted pages. The overview leads with what the product does and who it's for; how-it-works gets architecture and user-flow diagrams in Mermaid; dependency pages cite the code that imports them; snippets are copied from real files and captioned with their paths. Technical wikis also gain an onboarding section that takes a new developer from clean checkout to a first change. Budget a few minutes for a mid-size repo, longer for a monorepo.
No key for the provider you picked — ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or WIKI_INIT_API_KEY for custom — in your environment, the repo's .env.local, or its .env? The wizard prompts for one with input hidden, and can save it to .env — which it keeps gitignored. In scripts and CI the pass runs only when you pass --ai with a key present; --no-ai skips it entirely. --provider and --base-url pin the provider and endpoint, and --model picks the model (WIKI_INIT_MODEL also works, but only for the default Claude provider). On Claude, --effort sets how hard it thinks each turn: low, medium, high (the default), xhigh, or max.
If the pass fails partway, the drafted wiki is untouched on disk, and init exits with code 1 so a script can tell the pass didn't happen.
Spend is bounded regardless of repo size — at most 200 turns, a fixed read budget, and a prompt-cached conversation — and the run prints its token count with an estimated cost when it finishes. Expect a few dollars for a mid-size repo on the default model. --model claude-sonnet-5-5 costs about half as much per token.
Run it on your Claude plan
Have Claude Code installed and signed in? The pass can run there, with no API key:
wikipilot gives Claude Code the same investigation prompt and your brief, and claude -p does the reading and writing. On a Pro or Max plan the run counts against your plan's usage instead of API credits. Any ANTHROPIC_API_KEY in your environment or .env is kept away from it, since that would switch Claude Code to API billing.
Its permissions are narrow. It can read the repo, write inside the wiki folder, and run git log plus wikipilot's own screenshot, image, and build commands. Anything else is refused, because nobody is at the keyboard to approve it. --model and --effort still apply. This engine is meant for your own repos on your own machine; a product built on wikipilot should use the API engine with its own key.
Steer it with a brief
The code says what the product does. It doesn't say who reads the wiki or which journeys matter most. Put that in a wikipilot.md at the repo root and init follows it:
All the frontmatter is optional. sections replaces the preset's list, siteName names the site, and screenshots names the sites the agent may capture. The agent reads the brief before anything else, but it treats every route, rule, and number in it as a lead: each one is checked against the code, and where they disagree the page follows the code and the run summary names the mismatch. --brief <path> points at a brief somewhere else. The sync skill reads the brief too, so its priorities outlast the first run.
Screenshots and your colours
List sites with --screenshots https://example.com or in the brief, and the agent captures the pages it documents, looks at each image, and embeds the ones that show the step. It uses Playwright, found in your repo or its workspace packages, so a project with browser tests usually has nothing to install; otherwise npm i -D playwright && npx playwright install chromium. It only loads pages — no clicking, typing, or signing in — and only on the sites you listed. Signed-in and native-app screens come from images already in the repo, such as your test runs' screenshots.
The same two abilities work by hand:
Both save into wiki/screenshots/; embed with . wikipilot image <path> --as logo (or --as favicon) sets the site's logo instead.
While it investigates, the agent also reads your Tailwind config, CSS custom properties, or design tokens and saves the brand colours and fonts under theme in wikipilot.config.json. The build styles the wiki with them, lightening or darkening each colour where needed until links reach 4.5:1 contrast in both dark and light mode. You can edit theme by hand, too.
Build & serve
The defaults line up with what init wrote, so both commands take no arguments:
The site is named after your project — @acme/billing-service becomes "Billing Service" — and --site-name overrides it. The output is plain HTML, CSS, and JS: search, theme toggle, and Mermaid diagrams all work with no server-side code, so you can host it anywhere.
The build also checks every link between pages and prints the ones that land nowhere, with the page each sits on. One trap it catches often: a section's index.md is served at /<section>/, so a link from it to a page in the same section is ./slug/, not ../slug/.
Ask-the-wiki assistant
Run a small local API that grounds a chat widget in your wiki's own content only.
Pass --agent-port 4402 to wikipilot build and the built site's chat widget will call it automatically. If the API lives somewhere else — a Worker, a container, another domain — use --agent-url https://api.example.com/api/chat instead. The wiki itself stays static either way; the assistant is the only part that talks to a server, and the API key never leaves it.
Deploy
Today: host the wiki-dist/ output anywhere that serves static files — GitHub Pages, S3, your own nginx box. Soon: skip that step entirely.
Join the hosted-wiki waitlist →
Next steps
- Star the repo and skim the source — it's a plain TypeScript CLI, nothing exotic.
- Open an issue if a command behaves differently than this guide says — that's a bug in one of us.
- Wire
wikipilot init's scaffolded skill into your normal workflow so the wiki stays synced without a separate chore. - Not sure which sections your project actually needs? There's an argument for each of the ten, and a case for starting with fewer.