DEV Community

Cover image for OpenWiki: Persistent Context for Your Codebase and Documents
Sudhakar Punniyakotti
Sudhakar Punniyakotti

Posted on Edited on AI-assisted

OpenWiki: Persistent Context for Your Codebase and Documents

When a coding agent starts a new session, it often has to work out your codebase again. That takes time and tokens, and it can still miss things, like the middleware the rest of your code uses.

Now imagine you hit the five-hour limit on Claude Pro and move to Codex or Antigravity. The code is the same, but the context isn't, so you explain it all again. Spec-driven development helps, but a spec usually covers what you're building, not everything around it. In a big project the documents fall behind too: a small patch changes the retry limit from five to three, and the runbook still says five.

OpenWiki is an open-source (MIT) tool from LangChain that keeps this context as a wiki inside your repo. Any agent you switch to can read it, and a scheduled job can update it as the code changes. It works for documents too. The commands and behavior were checked against the source and docs of OpenWiki 0.9.0.


Why not just write a bigger AGENTS.md?

The usual ways of giving agents context each have a weakness:

Approach What goes wrong
One big AGENTS.md / CLAUDE.md It's loaded every turn, relevant or not. As it grows it gets noisy and stops being updated.
Hand-written docs They go out of date as the code changes, and agents may still follow them.
RAG over raw source It's good at finding snippets, but weaker on architecture, rules and the reasons behind them.

OpenWiki uses a wiki maintained by an LLM: small, linked pages, each about one concept, with key facts tied to evidence in the code. In unfamiliar code, an agent can search the wiki, read a section or two and then confirm in the source.

The diagram below shows an example:

Same task, two starting points. The wiki doesn't make the model smarter. It just stops it from starting at zero.
An example task in unfamiliar code, where checking the wiki first helps. For routine changes, OpenWiki tells agents to skip it.

The idea isn't new. The OpenWiki team credits DeepWiki, AutoWiki and Andrej Karpathy's "LLM Wiki" concept as inspiration. OpenWiki's focus is on keeping the wiki current and connecting it to the agents you already use.


How it works

The OpenWiki agent writes; your coding agent reads. Claims tie the two back to real code.
The OpenWiki agent writes the wiki and your coding agent reads it. Claims link it back to the code.

There are four parts:

  1. Documentation agent. It's built on LangChain's DeepAgents harness. It explores your repo, plans the pages and writes each one separately. An interrupted run can resume on the same checkout, so finished pages aren't lost.
  2. Wiki. This is plain Markdown in openwiki/, in the Open Knowledge Format (OKF v0.2): YAML front matter, an index and normal Markdown links. It can include Mermaid diagrams, which are validated. A broken diagram becomes a text block so it doesn't break the page.
  3. Grounded Claims. These are separate files in openwiki/.claims/ that tie facts to evidence like repo://src/server.ts#L40-L82.
  4. Agent setup. A small managed block in AGENTS.md points agents to the wiki. Optional integrations give them tools to search, read, generate and update it.

You bring the model. OpenWiki supports fifteen providers, including OpenAI (the default), Anthropic, Gemini, OpenRouter, Bedrock, Fireworks, Baseten, Mistral and GitHub Copilot.


We'll see how to use it in two parts: first on a codebase, then on documents.

Part 1: OpenWiki on a codebase

Setup

You need Node.js 22.22.0 or newer.

Inside a coding agent such as Claude Code or Codex, the integration uses that agent's model, so you don't need a separate key. You need a provider only for the standalone CLI, scheduled jobs and personal mode.

npm install -g openwiki
cd ~/code/your-repo
openwiki --init
Enter fullscreen mode Exit fullscreen mode

--init asks for a provider and credentials, then starts. On a real repo the first run takes time and costs money because the agent reads your code. Pick a capable model you can afford. You can also limit what it reads, as shown below.

Some useful options:

openwiki --init --language pt-BR         # write the wiki in another language (BCP-47)
openwiki --init --modelId <model-id>     # pick the model for this run
OPENWIKI_PAGE_CONCURRENCY=4 openwiki --update   # 1–8 parallel page workers
openwiki -p "How does request auth work?"       # one-shot question, print and exit
openwiki --debug                         # full error detail when something breaks
Enter fullscreen mode Exit fullscreen mode

Running openwiki with no flags opens an interactive session. There, /provider, /model, /effort and /api-key let you change settings without editing files.

What lands in your repo

your-repo/
├── AGENTS.md                ← created if missing; gets a managed OpenWiki block
├── CLAUDE.md                ← updated only if it already exists (never created)
├── .openwikiignore          ← optional: paths to skip
├── .github/workflows/
│   └── openwiki-update.yml  ← created by --init; runs daily
└── openwiki/
    ├── index.md             ← root index, declares okf_version: "0.2"
    ├── INSTRUCTIONS.md      ← YOUR brief. Kept when the wiki is rebuilt.
    ├── quickstart.md        ← entry page that routes to the others
    ├── architecture/        ┐
    ├── concepts/            ├ pages grouped by topic (names depend on your repo)
    ├── operations/          ┘
    ├── .claims/             ← grounded evidence for each page
    ├── .page-manifest.json  ← per-page progress, for resumable runs
    ├── .last-update.json    ← what was documented, and when
    └── .langsmith.json      ← optional: LangSmith projects to document (no keys)
Enter fullscreen mode Exit fullscreen mode

--init also creates .github/workflows/openwiki-update.yml, which runs every day once it's on your default branch. Check its provider and secrets before committing it, or delete it if you don't want scheduled updates.

Apart from that, commit all of it except openwiki/.run.json, a temporary file that exists only during a run. The wiki can then be reviewed and diffed like code.

Grounded Claims

Generated docs are only useful if you can check them, so this is the most important feature.

OpenWiki records material facts (behavior, architecture, invariants, security boundaries) as Claims. Each one points to exact evidence in the repo and records which version of that evidence it saw. Claim data lives in openwiki/.claims/, not inline, so the Markdown stays readable.

Example only: the session timeout and file path are made up to show the mechanism.
Example only: the session timeout and file path are made up to show the mechanism. Updates are planned page by page.

This helps in two ways:

  • When code changes, OpenWiki knows which claims and pages depend on it, so it doesn't need to regenerate the whole wiki.
  • Before changing something risky, an agent can open the cited evidence and check that the wiki is right.

Pages also record their sources in the front matter. This follows the format used in OpenWiki's own repository, with example values:

---
type: concept
title: Session handling
sources:
  - id: openwiki-source-<hash>
    resource: repo://src/auth/session.ts
generated: { by: "openwiki/0.9.0", at: "<timestamp>" }
verified:
  - by: openwiki/0.9.0
    at: <timestamp>
---
Enter fullscreen mode Exit fullscreen mode

sources lists whole files. The exact line ranges are kept in the matching file under openwiki/.claims/.

verified means the evidence behind that page's tracked claims was current when it was stamped. It doesn't mean every sentence on the page is correct.

Tell it what matters with INSTRUCTIONS.md

By default OpenWiki decides what's important, but you know your repo better. Put that knowledge in openwiki/INSTRUCTIONS.md. Re-running --init rebuilds everything except this file, so you can safely refine it over time.

For a typical web backend it could look like this:

# OpenWiki instructions

## Audience
Coding agents first. New human contributors second.

## Must cover
- The request lifecycle: `api/` → `services/` → `db/`, including where auth
  and rate limiting happen.
- Money handling in `billing/`: amounts are integer minor units, never floats.
  Call this out as an invariant.
- How feature flags are evaluated and cached, and how to add a new one.
- How to run tests locally, including which ones need Docker.

## Skip or keep brief
- Generated code in `src/gen/`.
- Legacy `v1/` endpoints (deprecated, scheduled for removal).

## Style
- Short pages that link to each other beat long pages.
- Every architecture page gets a Mermaid diagram.
- When something is surprising, explain *why* it is that way.
Enter fullscreen mode Exit fullscreen mode

Use .openwikiignore to keep out private paths, vendored code, fixtures, snapshots and build output. One side effect is that while ignore rules are active, the update planner doesn't get commit messages as hints, because they could describe ignored files.

How agents find the wiki

OpenWiki doesn't copy the wiki into your instruction files, because a full wiki can run to hundreds of pages. It adds a short managed block to AGENTS.md:

<!-- OPENWIKI:START -->
(short, generated guidance: the wiki exists, where it lives,
 and when an agent should consult it)
<!-- OPENWIKI:END -->
Enter fullscreen mode Exit fullscreen mode

The guidance says: "Do not enumerate, preload, or search wikis at task start." Agents are told to use the wiki when you ask, when unfamiliar architecture matters to the task, or when reading the source leaves a real question. The code and tests stay authoritative.

The block is refreshed on every run, and anything you write outside the markers is left alone. If CLAUDE.md exists, its managed block imports @AGENTS.md, so Claude Code gets the same guidance and you don't maintain two files.

You can also install an integration for your agent:

openwiki integrations install claude    # Claude Code
openwiki integrations install codex     # Codex
openwiki integrations install cursor    # Cursor
# also: opencode, copilot, bob, kiro, omp, antigravity

openwiki integrations list
openwiki integrations install claude --project .   # repo-scoped instead of user-wide
Enter fullscreen mode Exit fullscreen mode

Restart the agent afterwards. Integrations work on code wikis, not personal ones. They provide four read-only retrieval tools:

  • openwiki_search returns short, ranked results. It runs locally and makes no model calls.
  • openwiki_read gets the full sections the agent picked.
  • openwiki_list_wikis / openwiki_list_workspaces help agents find related repos.

They also provide six tools that generate and update the wiki, so your agent can write to it. You can then ask in plain English:

"Initialize this repository's OpenWiki from the current source and tests."

"Update this repository's OpenWiki for changes since its last successful run."

Scheduled updates

The wiki needs regular updates, because agents may trust a page that is out of date.

An update looks at the Git diff and checks the evidence behind every claim:

Nightly: diff, rewrite only what changed, open a PR, a human merges.
A nightly job finds changes, rewrites the affected pages and opens a PR for someone to merge.

The OpenWiki repo has a ready-made GitHub Actions workflow. Below is a shorter version to show the steps. Use the full file in practice, as it pins action SHAs and adds tracing and a fuller PR description.

# .github/workflows/openwiki-update.yml
name: OpenWiki Update

on:
  workflow_dispatch:
  schedule:
    - cron: "0 8 * * *"   # daily, UTC

permissions:
  contents: write
  pull-requests: write

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # needed! --update diffs against the last documented commit

      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - run: npm install --global openwiki@0.9.0

      - name: Run OpenWiki
        id: openwiki
        continue-on-error: true
        run: openwiki code --update --print
        env:
          OPENWIKI_PROVIDER: openrouter
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          OPENWIKI_MODEL_ID: your-model-id   # replace with a real model ID
          # OPENWIKI_TELEMETRY_DISABLED: "1"   # opt out of anonymous telemetry

      - run: rm -f -- openwiki/.run.json
        if: ${{ !cancelled() }}

      - id: paths
        if: ${{ !cancelled() }}
        run: |
          paths=openwiki,AGENTS.md
          if [ -e CLAUDE.md ]; then paths="$paths,CLAUDE.md"; fi
          echo "list=$paths" >> "$GITHUB_OUTPUT"

      - uses: peter-evans/create-pull-request@v7
        if: ${{ !cancelled() }}
        with:
          add-paths: ${{ steps.paths.outputs.list }}
          branch: openwiki/update
          commit-message: "docs: update OpenWiki"
          title: "docs: update OpenWiki"

      - name: Propagate OpenWiki failure
        if: ${{ steps.openwiki.outcome == 'failure' }}
        run: exit 1
Enter fullscreen mode Exit fullscreen mode

Points to check:

  • Keep fetch-depth: 0. With a shallow clone, OpenWiki can't see the commit it last documented, so it has to fall back to a full review of the affected pages, which is slower and costs more.
  • You don't need --init in CI. --update handles the first run when the env vars are set.
  • Failed runs can still save progress. If a run stops partway, the workflow still opens a PR with the finished pages, then marks the run as failed. Merge that PR so the next run starts from there.
  • Allow Actions to create PRs in the repository's Actions settings. PRs opened with the default GITHUB_TOKEN also don't start most pull_request checks, so use a scoped token if you need those.

GitLab CI and Bitbucket Pipelines are supported too.

Skim the wiki PR before merging. If a page is wrong, fix the cause (a misleading comment, a missing line in INSTRUCTIONS.md) rather than editing generated text that will be overwritten.

Multiple repos: workspaces

If your frontend calls a payments service, and that service's infrastructure is defined in a third repo, an agent in one of them needs to know how the others behave. Workspaces link their wikis:

cd ~/code          # the folder that contains your repos
openwiki link      # interactive: create "platform" and select its repos

# only needed when a repo belongs to more than one workspace
cd web-app
openwiki workspace use platform
openwiki workspace current
Enter fullscreen mode Exit fullscreen mode

One search, across every wiki in the workspace.
One search covers every wiki in the workspace.

What gets searched depends on membership. A wiki in no workspace searches only itself, and a wiki in one workspace searches that workspace. If it's in several, it uses the active one, and you'll get a workspace_required error until you pick one.

Browse the wiki as a graph

openwiki visualize                                    # local graph + Markdown reader on 127.0.0.1
openwiki visualize openwiki --export docs/openwiki-visualizer   # static site for GitHub Pages
Enter fullscreen mode Exit fullscreen mode

This opens a graph of the concepts with a reader beside it. New team members can use it to read the same pages the agents do. The viewer loads its libraries from a CDN, so it needs internet access.


Part 2: OpenWiki on documents

Agents also need information that isn't in code, such as product specs, architecture decisions, research and meeting notes.

OpenWiki now calls the original repo workflow Code Brain, and the documents-and-tools workflow Personal Brain (personal mode). The main difference is that grounded claims only exist in Code Brain. Personal Brain labels what it writes by confidence (confirmed, source-backed, contested and so on), but doesn't tie facts to versioned evidence.

Two stages: ingest raw data you can inspect, then let the agent write the wiki from it.
openwiki ingest does both stages. It saves raw data you can inspect, then updates the wiki from it. You don't need a separate personal --update straight afterwards.

Option A: a folder of documents

If your documents are already files, such as Markdown specs, ADRs or exported docs, the simplest option is to put them in a git repo and run code mode on it:

product-knowledge/
├── design/
│   └── checkout-v2.md
├── specs/
│   └── payments-api.md
└── adr/
    ├── 0007-idempotency-keys.md
    └── 0012-retry-policy.md
Enter fullscreen mode Exit fullscreen mode
cd product-knowledge
git init          # skip if it's already a git repo
openwiki --init
Enter fullscreen mode Exit fullscreen mode

Use INSTRUCTIONS.md to ask for pages that combine the documents, rather than a summary of each file:

These are product and architecture documents, not source code.

- Build one concept page per major decision, linking back to the source ADR.
- Maintain a "Current state" page that reconciles conflicting documents
  and says which one is authoritative (newer ADRs supersede older ones).
- Keep a glossary of domain terms with one-line definitions.
- Flag open questions and contradictions explicitly instead of guessing.
Enter fullscreen mode Exit fullscreen mode

The "Current state" page is useful when documents disagree, for example an old spec and a newer decision. People and agents can see which one applies.

As this is still code mode, the features from Part 1 apply: grounded claims pointing at your document files, the AGENTS.md pointer, scheduled updates and visualize.

Option B: personal mode with connectors

If the information lives in tools rather than files, use personal mode:

openwiki personal --init      # onboarding: provider, connectors, wiki template, schedules
Enter fullscreen mode Exit fullscreen mode

Connect sources:

openwiki auth                 # list providers and their status
openwiki auth notion          # OAuth via Notion's hosted MCP (no pasted tokens)
openwiki auth gmail           # needs Google app client credentials in ~/.openwiki/.env first
openwiki auth slack           # needs app credentials + HTTPS callback: `openwiki ngrok start`
openwiki auth x
Enter fullscreen mode Exit fullscreen mode

Then pull the data. This also updates the wiki:

openwiki ingest all           # or a single source: openwiki ingest web-search
Enter fullscreen mode Exit fullscreen mode

Sources include local git repos (recent commits and changed files), Notion, Gmail, Slack, web search (needs a TAVILY_API_KEY), Hacker News, X/Twitter and custom MCP. For custom MCP, point it at any HTTP or stdio MCP server and list the read-only operations to run. OpenWiki permits only tools that are allow-listed or marked read-only. A source can be set up more than once (web-search-1, web-search-2) for different topics.

Three details to know:

  • Ingestion writes to ~/.openwiki/connectors/<source>/raw/ before updating the wiki, so you can inspect what was pulled in.
  • Tokens go in ~/.openwiki/.env with restrictive permissions. Connector configs refer to them by env-var name only.
  • For Notion and web search you describe what you care about, and the agent searches for that instead of copying everything.

Schedules are macOS-only and run as LaunchAgents. Pause and resume apply to all schedules at once:

openwiki cron list
openwiki cron pause all
openwiki cron resume all
Enter fullscreen mode Exit fullscreen mode

The result is plain Markdown in ~/.openwiki/wiki/. Any agent that can read files can use it, and you can read it yourself in Obsidian or VS Code.


Tips for using it with agents

Generating the wiki is only the first step. These habits help agents use it well.

1. Say when to use the wiki. The managed block already tells agents not to search at task start, so don't add a blanket "wiki-first" rule. Outside the managed markers, name the cases that matter in your repo:

## How to work in this repo
- For unfamiliar subsystems, or changes to auth and billing, use `openwiki_search`
  (without the tools, start at `openwiki/quickstart.md`) and read only what's relevant.
- When you use the wiki, cite the page you relied on in your plan.
- If the wiki and the code disagree, trust the code and point out the mismatch
  in your summary so we can fix the source of truth.
Enter fullscreen mode Exit fullscreen mode

2. Plan with the wiki, edit from the code. Use the wiki for where things are and what the rules are. Use the source files for the actual change.

3. Check claims before risky changes. For auth, billing, migrations or anything near a security boundary, tell the agent to open the evidence behind a claim before acting. That catches cases where the wiki is behind.

4. Review wiki PRs. You don't have to read every line. Look for anything wrong or misleading, and fix it at the source.

5. Ignore what doesn't help. Put generated code, lockfiles, fixtures, snapshots and vendored dependencies in .openwikiignore. A smaller wiki is easier to use.

6. Use tracing while you tune. With a LangSmith key (/langsmith-key in the interactive CLI) you can follow the planner and page writers, and see what to change in INSTRUCTIONS.md.


Limitations

  • The first run costs tokens. Updates can skip pages that haven't changed, but --init writes every page from scratch. Start with a capable, affordable model and a strict .openwikiignore.
  • Generated docs can still be wrong. Grounded claims make mistakes easier to catch, but don't eliminate them. Keep a person reviewing the PRs.
  • Your code goes to your model provider. The agent sends your source to the LLM you configure, so choose one that fits your data policy. In personal mode, think carefully before connecting your inbox.
  • Telemetry is on by default, locally and in CI. OpenWiki sends an anonymous event for each init or update run. Set OPENWIKI_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 to opt out.
  • It's young and changing quickly. It started as a codebase tool and now has a second mode. Commands and formats may change, so pin a version in CI and read the changelog when you upgrade.
  • It doesn't replace design docs. It explains what's in your code and docs. You still need to write decisions down.

Cheat sheet

I want to… Run
Generate a wiki for this repo openwiki --init
Refresh it after changes openwiki --update
Refresh it in CI openwiki code --update --print
Ask a one-off question openwiki -p "..."
Give my agent search/read tools openwiki integrations install claude (or codex, cursor, …)
Link related repos openwiki link (interactive)
Browse it as a graph openwiki visualize
Build a wiki from Notion/Gmail/Slack openwiki personal --init, openwiki auth <source>, openwiki ingest all
Change provider or model openwiki, then /provider or /model

If you want to try OpenWiki, start with one repo and read what it writes before you commit it. If you've already used it, especially on a monorepo, let me know in the comments how it went.


Resources

Top comments (0)