Code mode

Generate and maintain repository documentation for coding agents with OpenWiki

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 the pointer OpenWiki maintains in AGENTS.md, and through an @AGENTS.md import in CLAUDE.md when that file already exists.

openwiki, openwiki --init, and openwiki --update run in code mode. You can also pass the mode explicitly:

openwiki code --init
openwiki code --update
openwiki code --update --print

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:

openwiki --init --language ko

You can also run OpenWiki inside Codex, Claude Code, OpenCode, Cursor, IBM Bob, Kiro, Oh My Pi, or Antigravity. See Coding-agent integrations.

Parallel page workers

Native CLI init and update runs can document multiple pages concurrently. Set concurrency with:

OPENWIKI_PAGE_CONCURRENCY=4 openwiki --update

Concurrency defaults to 1 and accepts values from 1 to 8. Start at 2 to 4 and watch your provider’s rate limits. Coding-agent integrations keep the host’s sequential page lifecycle; this setting controls native CLI workers only.

Each worker owns exactly one page, and completed pages remain durable resume units. The quickstart page is written last so it can link to the pages it routes to. A worker that fails on a provider rate limit lowers the run’s concurrency by one for the rest of the run; the page it was writing is restored and picked up by the next update.

Provider retries default to 3, or 5 when OPENWIKI_PAGE_CONCURRENCY is above 1. Override with OPENWIKI_PROVIDER_RETRY_ATTEMPTS (a positive integer).

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: Created when missing, then refreshed inside an <!-- OPENWIKI:START --> … <!-- OPENWIKI:END --> block that tells coding agents when to consult the wiki
• CLAUDE.md: Refreshed only when the file already exists. The managed block imports @AGENTS.md so Claude Code still loads the same instructions. OpenWiki does not create CLAUDE.md when it is absent

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.

Updates reconcile Claims sparsely. The page worker submits decisions for Claims that need attention (confirm, revise, add, or retract). Unaffected Claims keep their stable identifiers and do not round-trip their statements and evidence through the model. Host-driven runs expose the complete Claims set for the current page through the optional openwiki_inspect_page_claims MCP tool.

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:

OPENWIKI_LANGSMITH_API_KEY="<your-langsmith-key>"

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:

secrets/
*.log
!logs/keep.log

When .openwikiignore has active rules, OpenWiki filters filesystem discovery and restricts shell execute so ignored paths stay out of the run. Repository agents use constrained filesystem tools rather than arbitrary host shell commands or unrestricted repository inspection.

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:

npm install mermaid jsdom

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:

openwiki "Update openwiki/INSTRUCTIONS.md to prioritize the public API and skip internal tooling"

Normal --init and --update runs do not rewrite this file.

See also

• Coding-agent integrations
• Search and link wikis
• Visualize your wiki
• Automate updates
• Customize OpenWiki
• Personal mode

---

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.