The Problem

Maintaining accurate, up‑to‑date documentation for a growing codebase is labor‑intensive. Developers either write docs manually and let them drift, or rely on ad‑hoc scripts that quickly become brittle. The result is stale knowledge, lost onboarding speed, and duplicated effort across teams.

What This Does

openwiki is a Node‑CLI that runs an LLM‑driven agent over a repository, extracts code concepts, and emits a linked Markdown wiki under the openwiki/ folder. The agent lives in src/agent/ – index.ts orchestrates prompting, prompt.ts builds queries, and docs‑only‑backend.ts writes the OKF‑compatible output. Connectors in src/connectors/sources/ (e.g., langsmith, git-repo, gmail) let the agent pull external context, while src/visualize/ ships a lightweight Express server (server.ts) that renders the wiki as an interactive Mermaid graph.

How It Is Wired

Execution starts in src/cli.tsx, which parses the command line (e.g., openwiki --init) and dispatches to src/commands.ts. The primary command creates an OpenWikiAgent by importing src/agent/index.ts.

  1. src/agent/index.ts builds a Prompt (src/agent/prompt.ts) and calls the model provider defined in src/agent/prompts/*.ts.
  2. The prompt result is handed to src/agent/docs‑only‑backend.ts, which formats data per the Open Knowledge Format (OKF) and writes files via utilities in src/utils.ts.
  3. If a connector is requested, the agent imports the corresponding source module (e.g., src/connectors/sources/langsmith/index.ts) which uses the API helpers in src/connectors/sources/langsmith/*.ts to fetch trace data.
  4. Telemetry is injected early via src/telemetry/index.ts; all major modules import src/telemetry/client.ts to emit run‑level events.
  5. When the visualizer is launched (openwiki visualize), src/visualize/server.ts starts an Express app, reads the generated markdown tree, and renders it with the Mermaid helpers in src/mermaid/*.ts.

The internal import graph contains 168 modules and 356 edges with no cycles. The highest‑degree hub is src/constants.ts (31 inbound, 1 outbound imports) and src/agent/types.ts (19 inbound). These hubs have the widest blast radius: changes ripple through many callers, so stability is critical.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/openwiki
cd openwiki

# Install dependencies (pnpm is the declared manager)
pnpm install

# Global install of the CLI (optional)
pnpm add -g .

# Initialise a wiki for the current repo
openwiki --init

Configuration is stored in openwiki/.openwikiignore (gitignore‑style) and optional .env variables for model keys (e.g., OPENAI_API_KEY). The CLI reads src/env.ts for these values. To run the visualizer:

openwiki visualize
# opens http://localhost:3000 with the Mermaid graph

For CI automation copy one of the examples, e.g. examples/openwiki-update.gitlab-ci.yml, into your project’s .gitlab-ci.yml.

Real‑World Use

A microservice team adds openwiki to its monorepo. On each merge request, the GitLab pipeline runs openwiki generate which produces openwiki/ markdown and opens a PR with updated docs. Developers consult the live visualizer during code reviews, reducing onboarding time and preventing stale documentation.

Code Health & Issues

  • Measured findings (static analysis)
  • HIGH cognitive load – deep nesting (e.g., src/constants.ts, src/agent/index.ts).
  • HIGH cognitive load – oversized files (e.g., src/constants.ts 725 LOC).
  • HIGH clarity – hub module (src/constants.ts, src/agent/types.ts).
  • HIGH clarity – duplicated code blocks (≈160 repeats across 49 files).
  • MEDIUM cognitive load – high branching density (src/telemetry/errors.ts).
  • MEDIUM resilience – broad exception handling in evals/deepswe/run.py.
  • LOW clarity – 5 TODO/FIXME markers in src/agent/prompts/code.ts.
  • Code‑health audit
  • MEDIUM – checkout persists credentials in .github/workflows/checks.yml.
  • LOW – missing timeout-minutes on workflow jobs.
  • LOW – repository lacks convention files (.editorconfig, formatter config).
  • Other observations
  • Tests are comprehensive (77 files) and CI runs via GitLab CI.
  • License (MIT) and lockfile (pnpm-lock.yaml) are present.
  • No Dockerfile or container build scripts; the CLI runs directly on Node.

The Bottom Line

openwiki delivers a functional, agent‑driven documentation pipeline with solid test coverage and CI integration. However, several core modules are large, deeply nested, and heavily depended upon, raising maintenance risk. Teams that need automated wiki generation and can allocate effort to refactor the hub files will benefit most; smaller projects may find the complexity outweighs the advantage.