Skip to main content
Code mode builds a repository wiki in openwiki/ with durable details such as architecture, integrations, and workflows. Coding agents use that wiki as context so they can work in the package more efficiently, with less rediscovery and fewer tokens. Humans can read the same Markdown, but agents are the primary audience. Agents discover the wiki through pointers OpenWiki adds to AGENTS.md and CLAUDE.md. openwiki, openwiki --init, and openwiki --update run in code mode. You can also pass the mode explicitly:
Running openwiki --init again replaces the existing generated repository wiki and Claims with a new generation while preserving the user-authored openwiki/INSTRUCTIONS.md brief. On a persistent checkout, OpenWiki records in-progress generation in openwiki/.run.json, so rerunning the same command after an interruption resumes the durable page queue. Ephemeral CI runners start fresh after failure unless their workspace is preserved. A setup failure before the new run state is durable restores the previous wiki. To generate wiki pages in another language, pass a BCP-47 locale such as ko, zh-CN, or pt-BR:
You can also run OpenWiki inside Codex, Claude Code, OpenCode, or Cursor. See Coding-agent integrations.

​
What code mode produces

After a successful init or update, the repository typically includes:
  • openwiki/: Generated Markdown wiki (quickstart, architecture, operations, and related topics)
  • openwiki/INSTRUCTIONS.md: User-authored brief for scope and priorities. OpenWiki reads it on init and update. Edit it yourself, or ask OpenWiki in chat to change it; normal --init and --update runs do not rewrite it
  • openwiki/.claims/: Structured Claim sidecars that ground factual pages in versioned repository evidence
  • openwiki/.page-manifest.json: Per-page progress and source checkpoints for resumable generation
  • openwiki/.last-update.json: Metadata for the last successful documentation check (including no-op updates)
  • AGENTS.md / CLAUDE.md: OpenWiki inserts or refreshes an <!-- OPENWIKI:START --> … <!-- OPENWIKI:END --> block that tells coding agents when to consult the wiki. Existing content outside that block is left untouched
During an active run, openwiki/.run.json checkpoints the ordered page queue. OpenWiki deletes that file after a successful finish.

​
Grounded Claims

OpenWiki makes code wikis self-correcting by tracking the material propositions behind factual pages, not only when a Markdown file was last generated. Claims cover truths future agents rely on: behavior, responsibilities, architecture, data flow, invariants, failure semantics, configuration, and security boundaries. Each Claim points to exact repository evidence such as repo://src/server.ts#L40-L82, with the evidence version OpenWiki observed when the Claim was established. The Markdown stays clean. Structured Claim state lives under openwiki/.claims/. Page completion persists reconciled Claims, projects verification into OKF front matter, and proves the complete result before marking that page job complete. Grounded Claims apply to repository code wikis and repository evidence. Connector-derived facts, including LangSmith-only observations, are not included as Claims.

​
Markdown output

OpenWiki’s durable output is Markdown (OKF), not a static HTML site. To explore the wiki in a browser, run openwiki visualize. The command serves a viewer only on your local machine (127.0.0.1), or you can export a static visualizer for hosting.

​
Open Knowledge Format

OpenWiki emits Google Open Knowledge Format (OKF) v0.2 bundles in both code and personal modes:
  • A concept is an ordinary wiki Markdown page (one topic file). Every concept has YAML front matter with a non-empty type; other standard fields are optional
  • New and freshly initialized pages receive generated: {by, at}. During updates, any body change, including whitespace, advances the stamp; an unchanged body retains its prior event, and front-matter-only changes do not advance it. The producer is stamped as openwiki/<version> (or the coding-agent host)
  • Repository pages project grounded Claims evidence into sources. OpenWiki reconciles its deterministically identified entries while preserving independently authored sources
  • Repository pages receive verified: {by: openwiki/<version>, at: ...} only after a successful page submission reconciles a non-empty complete Claims set, passes the final evidence recheck, and persists the Claims sidecar
  • index.md and log.md are reserved scaffolding files, not concepts. The root index declares okf_version: "0.2"
  • The optional v0.2 provenance, trust, and lifecycle families (sources, verified, status, stale_after) are validated when present. Producer-defined extension fields are preserved across updates and migrations
  • Standard Markdown links between concept documents express relationships

​
LangSmith connector

The LangSmith connector enriches a code wiki: it pulls recent LangSmith traces (tool calls, outcomes, and latency) for the projects you choose, so repository docs reflect how the code behaves at runtime, not only what the source says. Configure it during openwiki --init in code mode. From the source menu, add LangSmith, pick your workspace region (US, EU, or APAC), and list the projects to document. OpenWiki writes a committed openwiki/.langsmith.json that names the workspaces and projects (never the key itself). The API key is read from the environment:
Locally the setup wizard can save this to ~/.openwiki/.env. In CI, set it as a repository secret and export it for the run. A LangSmith key is workspace- and region-bound. To document projects across more than one workspace, add an entry per workspace, each with its own key named OPENWIKI_LANGSMITH_API_KEY_2, OPENWIKI_LANGSMITH_API_KEY_3, and so on. The connector talks to the official US (api.smith.langchain.com), EU (eu.api.smith.langchain.com), and APAC (apac.api.smith.langchain.com) hosts.

​
Ignore paths

Create a .openwikiignore file in the repository root to keep generated docs from reading or describing private, generated, or irrelevant paths. The syntax supports comments, blank lines, * and ** globs, directory rules, and ! negation:
When .openwikiignore has active rules, OpenWiki filters filesystem discovery and restricts shell execute so ignored paths stay out of the run.
This is a read boundary: ignored paths are never read, scanned, or reproduced in the generated docs. It does not guarantee a topic will never be mentioned, because the agent may still infer an ignored area from other allowed evidence such as tests, the README, commit messages, or the existing wiki.

​
Diagrams

OpenWiki embeds Mermaid diagrams where they clarify a concept better than prose. After each run, it validates Mermaid fences. A diagram that fails validation is converted in place to a plain text fence with a short comment, then repaired on a later --update run when possible. For validation that matches GitHub rendering more closely, install the Mermaid parser wherever you run OpenWiki:
When the parser is present, OpenWiki uses it. When it is absent, OpenWiki falls back to a lightweight check. Diagram generation works either way.

​
Customize the wiki brief

Edit openwiki/INSTRUCTIONS.md to steer scope, priorities, and preferred writing conventions for repository documentation (for example tone, terminology, and what to emphasize or skip). OpenWiki reads this file on init and update runs. You can also ask OpenWiki in chat to revise the brief:
Normal --init and --update runs do not rewrite this file.

​
See also

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.