OpenWiki: Bridging the Agent Context Gap

Our agent shipped a broken authentication flow last week.

The reason was almost stupid. Its internal AGENTS.md still pointed at a deprecated JWT helper function. We had refactored the auth module months earlier, but the agent was still working from an old map. It wrote code against a function that no longer existed, and staging failed quietly. That kind of bug is embarrassing because the code looks deliberate. It is wrong for a very boring reason, stale context.

I keep running into the same issue. Agents are only as good as the context you hand them. If you want useful code, the agent needs to know where the important logic lives, how files connect, and which patterns the codebase expects. Most of us stuff that into AGENTS.md, CLAUDE.md, or some other instruction file. That works for a while. Then the repo grows, the file gets huge, and nobody keeps it current. A function signature changes. A module gets refactored. The docs stay frozen. Now the agent is coding against a version of the repo that no longer exists.

That gets expensive fast. You burn tokens. You waste time debugging. And the failure mode is annoying, the agent sounds confident while doing the wrong thing.

OpenWiki

OpenWiki is a CLI from LangChain that tries to fix this by generating and maintaining a structured wiki for your codebase. The point is simple. Stop cramming everything into one giant instruction file. Keep the context in a wiki, then let the agent pull the pages it actually needs.

How it works

1. Initialize it

Install OpenWiki globally with npm, then run openwiki --init inside your repo.

It asks you to configure an inference provider and API key. The draft mentions OpenAI, Anthropic, OpenRouter, Fireworks, and Baseten.

2. Generate the wiki

OpenWiki scans the codebase, finds modules, functions, classes, and entry points, then uses an LLM to write documentation for each section.

It does not dump everything into one massive file. It creates an openwiki/ directory in the repo with a structured wiki. That detail matters. Granular docs are easier for an agent to retrieve than a giant wall of text.

3. Hook it into your agent docs

OpenWiki also updates your existing instruction files, like AGENTS.md or CLAUDE.md.

It adds a short reference to the wiki and tells the agent when to consult it. I like this part because it mirrors how people actually work. You do not memorize the whole codebase. You keep a map, then look up the specific page you need.

4. Keep it current

This is the part that got my attention.

OpenWiki uses git diffs to figure out what changed since the last run. When you run openwiki --update, it updates only the relevant parts of the wiki.

It also provides a GitHub Action template, openwiki-update.yml, that you can add to the repo. That action can run on a schedule, like daily, and open a pull request with documentation updates.

If the whole problem is stale context, this is the only part that really counts. Generated docs are nice. Generated docs that stay current are useful.

Here are the core commands:

# Install globally
npm install -g openwiki

# Initialize and generate initial documentation
openwiki --init

# Update existing documentation
openwiki --update

# Run in interactive chat mode
openwiki

When OpenWiki makes sense

Use it when the repo changes often and agents are part of the workflow.

When it probably does not

For a tiny, mostly static project with no agent integration, this may be too much.

If your AGENTS.md is actually small and rarely changes, the setup and update flow might not buy you much. But once the repo grows past a handful of files, or once agents start writing real code in it, I think the tradeoff changes pretty quickly.

What gets me here is how ordinary the failure is. Nothing exotic broke in that auth flow. The agent just trusted a bad document. OpenWiki is trying to fix that exact class of mistake by treating codebase context like something that needs maintenance, not something you write once and forget.

That is the pitch. Keep the map fresh, or expect weird bugs.

Until next time, happy coding 👨‍💻
– Patricio Marroquin 💜