OpenWiki Can Track Code Changes, but It Can't Prove the Docs Are Correct

AGENTS.md is a good place for build commands and working rules, but not for a full architecture write-up. When a coding agent takes over an unfamiliar repo, it still has to work out module relationships, data flow, and failure handling from the source code and tests. OpenWiki’s approach is to organize that information into a wiki inside the repo, which the agent reads when it needs to. In this post, I want to find out how it decides which pages need rewriting after the code changes, and how far you can trust the updated result.

When LangChain announced OpenWiki, it argued that as long as the agent instruction file points to a repo wiki, a coding agent can pull in documentation on demand, without cramming a lot of explanation into a single instruction file. This split keeps the instruction file short, but it adds a wiki that goes stale as the code changes. Below, I look at how OpenWiki deals with that problem from two angles: the update flow and the source checks.

OpenWiki turns repo docs into an updatable wiki

OpenWiki is a command-line tool that generates and maintains a repo wiki. The source I checked for this post is commit 715109a. At that commit, package.json lists version 0.5.2, requires Node.js 22.22.0 or later, and is released under the MIT License.

This post focuses on code mode, where the generated docs go back into the original repo and are version-controlled alongside the code. When you run initialization, OpenWiki creates an openwiki/ directory and writes OpenWiki-managed instruction blocks into AGENTS.md and CLAUDE.md. If the repo doesn’t have an update workflow yet, it also creates .github/workflows/openwiki-update.yml. So --init doesn’t just read your code; it also modifies your agent instructions and GitHub Actions configuration. You can find this behavior in ensureCodeModeRepoSetup and writeCodeModeAgentSnippets.

The agent instructions OpenWiki writes position openwiki/ as an evidence index to consult on demand. In other words, the agent uses the wiki to locate the relevant systems and files, then goes back to the source code and tests to confirm; the wiki itself is not the final authority. This constraint is spelled out in the instructions generated by createCodeModeAgentsSnippet.

AGENTS.md only points the way; the wiki is an on-demand evidence index, and you still go back to the code to confirm.

How a single update decides which pages to change

OpenWiki generates wiki pages, and for the important statements on each page it creates a Claim that records the source code location backing that statement. Each page plus its Claims forms one page job, and page jobs are processed in order. The Claims aren’t written into the wiki body; they’re stored separately in a sidecar metadata file. When you run a repo update, OpenWiki works through the following steps in order.

1. getRepositoryChangedPaths first figures out what changed in the code. It compares the last recorded Git commit against the HEAD of the current checkout. Uncommitted changes are included too: staged files already added to the Git index, unstaged files not yet added to the index, and new files Git isn’t tracking yet. It excludes OpenWiki’s own generated openwiki/ directory and any paths listed in .openwikiignore, so documentation output isn’t mistaken for code changes. src/agent/utils.ts lists the actual Git commands it uses.
2. Next, the planner decides which pages the wiki should have. It reads manifests like package.json, program entry points, the main directories, and representative tests, then organizes pages around system boundaries, runtime environments, and cross-system flows. The prompt given to the planner explicitly forbids listing files one by one in source-directory order, because the goal is to explain how the system works, not to copy the file tree. You can find this requirement in createRepositoryPlannerPrompt.
3. The worker, which writes the pages, handles only the page job currently at the front of the queue. After finishing a page, it also has to list which Claims were added, revised, confirmed, or retracted. These actions tell OpenWiki whether an existing statement still holds, needs its content changed, or should be removed from the docs. submitRepositoryPage rejects pages submitted out of queue order, and confirms the page file is readable before accepting it.
4. When writing a page and its Claims, OpenWiki checks that the page version the worker read is still the latest, so it doesn’t overwrite other updates. It then confirms that each Claim in the sidecar can find the code it cites, and only after that passes does it mark the page job as done. Once all pages are processed, it also checks the Mermaid diagrams, the wiki index, internal links, Claim sources, and the generation record for this run. This set of final checks is implemented in finalizeWikiArtifacts.

An update first looks at what changed in the code, then decides on pages and writes Claims, and only runs the batch-wide checks at the end.

Each time OpenWiki finishes a page, it writes the result to this run’s checkpoint. If the process fails partway through, the records for completed pages aren’t lost. Only after every page passes validation and this run’s generation record is written does finishRepositoryRun remove the run state. This means partial progress survives an interruption; it does not mean an unfinished wiki is ready to merge.

How far Claims can check

The purpose of Grounded Claims is to let important statements in the docs be traced back to the source code. Every Claim links to a repo:// URI, and the location can be an entire file or narrowed down to a range of lines. Beyond line numbers, the repository resolver also computes a SHA-256 of the cited content and stores hashes of the first and last lines and the surrounding content. If someone inserts code near the top of the file and the original lines all shift down, the resolver uses the original content and its context to find the new location. This logic lives in resolveLineRangeEvidence and locateUnchangedLineRange.

Before each update, runClaimsPreflight resolves the code each Claim cites. If the file or the cited range can no longer be found, the status is unresolved. If the location is found but the content version differs, the status is stale. OpenWiki treats a run as a no-op, regenerating no docs, only when the Git check finds no changes that need handling, all Claims are fine, and every page already has Claims to serve as its coverage baseline. preflight.ts and repository-run.ts implement these two layers of checks.

This check answers only two questions: does the cited location still exist, and has the content at that location changed? It does not re-evaluate whether the natural-language statement in the docs is correct. Suppose the docs claim “after three retries, the message is written to the dead-letter queue,” but the cited code actually retries only twice. As long as that code hasn’t been modified, the stored hash stays the same, and neither stale nor unresolved will show up.

So an all-green source check only means each Claim can still reach the content it originally cited. Reviewers still need to read that code and the related tests to make sure the docs haven’t misunderstood a condition, a count, or an execution order.

Even with all Claims green, the doc statements still need a human check.

What changes when it’s part of daily work

Coming back to a personal project after a few months

When you maintain a personal project, you’re both the developer and the doc reviewer. Coming back after a few months away to fix a login bug, you might still remember which directory the feature lives in, but forget where the session gets renewed, which tests cover timeouts, and which environment variable the deployment reads. If the wiki has a page explaining the login flow, with Claims linking to the session code, the tests, and the deployment config, a coding agent can read those few locations first instead of searching the whole repo for related keywords.

It’s also easy to skip review on a personal project, since nobody will reject an incorrect docs PR. If the project is already split into several modules, or you only touch it every few months, consider making spot-checking Claims a routine part of every update. If the project has only a handful of files and you’re changing it every week, reading the source and tests directly usually saves more time.

On-call and cross-team changes at a company

Say the on-call engineer gets an alert about duplicate orders being created, but the original author is on vacation. The first step is to find the API that receives orders, where retries happen, and where the service generates and checks idempotency keys. If the wiki’s order-flow page already links to that code and those tests, the engineer and a coding agent can start directly from the cited locations. The wiki won’t pinpoint the root cause of the incident, but it helps the engineer confirm which services a request passes through without waiting for the original author to come online.

Cross-team changes make the cost of outdated docs more obvious. Suppose the payments team adds a required version field to the event format, and both the order and notification services need to update their parsing code. OpenWiki can use Git changes and existing Claims to find pages that may need rewriting and open a docs PR. Reviewers still need to check whether the docs clearly state if old-format events will keep working, and whether the tests cover both the old and new formats. The team also has to decide up front who reviews docs PRs, how quickly they must be handled, and whether partial results are acceptable when a generation run is interrupted. Without those arrangements, auto-generated PRs will just sit in the queue.

Whether a project is personal or corporate doesn’t directly determine whether it needs a repo wiki. A wiki only has a chance to save repeated lookup time if everyone who takes over has to rediscover the entry points, flows, and tests each time, and if someone is responsible for checking the docs.

Which repos are worth the maintenance cost

OpenWiki adds model calls, CI configuration, and human review. Before adopting it, at least confirm who bears the following costs.

• Every generation and update calls a model. The README quick start requires you to configure a model provider, API key, and model name. Cost, run time, and output quality vary with the model and the repo’s contents. I didn’t run a full generation for this post, so I have no measured numbers for these.
• The official openwiki-update.yml fetches the full Git history so OpenWiki can compare commits. It also needs a model key, plus contents: write and pull-requests: write permissions to commit doc changes and open PRs. These permissions should get the same scrutiny as any other automation that can write to the repo.
• --init creates openwiki/, modifies agent instructions, and may add a GitHub Actions workflow. After the first run, your review should cover the entire diff, not just the generated wiki pages.
• Claims link a doc statement to an exact source location, but clicking the link isn’t the same as finishing the review. Reviewers still need to compare the statement, the cited range, and the related tests.

If a repo contains multiple subsystems, coding agents often need to modify unfamiliar areas, and the team is willing to review automated docs PRs, a wiki can centralize each system’s entry points and how the systems interact. If a small repo has only a few entry points and the source code and tests already explain the behavior directly, there’s no need to maintain a wiki that says much the same thing. And if you don’t have people to review, don’t turn on scheduled updates, because each run just adds another PR waiting to be handled.

Company repos also need to exclude paths that shouldn’t be handed to a model. .openwikiignore blocks OpenWiki’s file tools from reading the specified content. Once ignore rules are enabled, OpenWiki’s local execution backend also rejects arbitrary shell commands, because a shell could bypass the file tools and read ignored files directly. This restriction is implemented in OpenWikiLocalShellBackend.execute. .openwikiignore only restricts OpenWiki’s tools; it doesn’t replace repo access controls, and it can’t undo secrets that have already been committed to Git.

Validate the update flow on one repo first

First, make sure the CLI starts locally. The commands below install OpenWiki into a new directory under /tmp, so they don’t touch the test repo’s dependencies or write to npm’s usual global install location. I actually ran these commands on macOS arm64 with Node.js 25.2.1 and npm 11.6.2. OpenWiki uses Ink’s interactive terminal UI, so run it in an environment with a PTY, such as Terminal. If stdin doesn’t support raw mode, Ink prints an error right away.

check_prefix="$(mktemp -d /tmp/openwiki-check.XXXXXX)"
npm install --global --prefix "$check_prefix" [email protected] --no-audit --no-fund
PATH="$check_prefix/bin:$PATH" openwiki --help

If the CLI installed successfully, the output shows version 0.5.2 and a Usage section. The ellipsis below marks content I trimmed from the middle.

>_ OpenWiki v0.5.2 agent docs for codebases
...
# Usage
   openwiki [--init|--update] [message]

For this post I only verified that the CLI starts; I didn’t provide model credentials or run a full generation. The --init and --update commands below are the commands as listed in the project’s README. Because --init modifies agent instructions and may add a workflow, do your first test in a throwaway repo or on a test branch with no other changes.

openwiki --init

# After changing and committing a behavior that has test coverage
openwiki --update

A successful exit only means the process finished. Whether it’s worth adopting depends on the following checks.

1. Review the full diff of openwiki/, AGENTS.md, CLAUDE.md, and the new workflow to confirm which files OpenWiki changed and which permissions the workflow gets.
2. Pick a wiki page about a feature you know well, and check whether it misses any major entry points, error handling, or representative tests.
3. Spot-check a few Claims from that page, confirming one by one that the doc statement is precise, that the repo:// range actually supports it, and that the related tests match the statement.
4. Record generation time, model usage, the number of incorrect statements, and the time spent on manual edits. Only these numbers let you compare it against the time it takes to maintain docs by hand.

How far should docs maintenance be automated

The source code cited above lets you verify how OpenWiki tracks its sources, but it can’t prove that it saves every team money or time. The adoption order I’d use: first run --init and --update manually on one real repo, keep the wiki and Claims for the team to review, but hold off on enabling the scheduled workflow. Once doc quality and review time are acceptable, let GitHub Actions open update PRs on a schedule.

OpenWiki stores the code location and content version each Claim cites, so reviewers can find out whether a source still exists. You can’t do that check by looking only at when the docs were last generated. Even so, the team still needs to record how many incorrect statements spot-checks turn up, which major flows are missing from the wiki, and how much manual editing each docs PR requires. If this review work takes more time than updating the docs by hand did, automation has just moved that time into PR review.

Start with one update whose sources you can check

OpenWiki first compares Git changes, then has the planner read the repo structure and tests to decide which pages to handle. As each page finishes, it checks the page, the Claims sidecar, and the cited sources, and before the batch completes it checks the index and internal links. These mechanisms can confirm what progress was saved when a run was interrupted, and whether the content version a Claim cites has changed. They can’t tell whether the docs interpreted the code correctly.

The smallest test is to run --init once in a throwaway repo, commit a code change that has tests, then run --update. After that, spot-check the Claims on the pages related to the change, and record model usage, the number of errors, and human review time. Only add the scheduled workflow to a production repo if the docs describe the change correctly and the update cost is acceptable.

Further reading

• Introducing OpenWiki: understand why the launch post favors a short agent instruction file that links to a large repo wiki.
• OpenWiki README: look up how to use the CLI, code mode, Grounded Claims, and scheduled updates.
• Claims preflight implementation: check the actual logic behind stale and unresolved.
• Repository evidence resolver: trace how evidence is relocated using content hashes and context after line numbers shift.