openwiki Documentation

OpenWiki is a CLI that writes and maintains agent documentation for your codebase.

14,797 stars TypeScript TypeScript 1 file · ~10,519 tokens
RAW Doc

1. Project Overview & Quickstart (langchain-ai/openwiki)

OpenWiki is a CLI that writes and maintains a wiki for your codebase or your personal knowledge. An agent reads your sources, synthesizes a linked Markdown wiki you own, and keeps it current on every change. It is built for agents to read as memory, and it ships an interactive visualizer for humans to explore.

OpenWiki gives you:

  • Agent-written docs that stay accurate, generated by a Deep Agents documentation agent.
  • Two modes: a code wiki for a repository, or a personal wiki for your own knowledge.
  • Thirteen model providers out of the box, from OpenAI and Anthropic to Bedrock, Gemini, and any OpenAI-compatible gateway.
  • Coding-agent integrations for Codex and Claude Code, using the host's model and repository tools.
  • Grounded Claims that track material facts back to versioned source evidence and surface them when the evidence changes.
  • Nine built-in connectors for Custom MCP, Notion, Slack, Gmail, X, Web Search, Hacker News, LangSmith, and local git repositories.
  • An interactive visualizer that turns any wiki into a live, explorable node graph.
  • Self-updating through GitHub Actions, GitLab CI, or Bitbucket Pipelines.
  • Open Knowledge Format (OKF v0.2) output with validated Mermaid diagrams.

🎉 What's new

  • Grounded Claims: material facts in code wikis now carry versioned source evidence. When that evidence changes or disappears, OpenWiki knows exactly which propositions need to be confirmed, rewritten, or retired.
  • OpenWiki integrations: run OpenWiki directly inside Codex or Claude Code, using the coding agent's authenticated model and native repository tools while OpenWiki manages the documentation lifecycle.
  • OKF v0.2: every wiki is a portable Open Knowledge Format bundle with deterministic generation provenance and validated trust and lifecycle metadata.
  • Publishable visualizers: export the interactive graph and Markdown reader as a deployable static site for GitHub Pages, MkDocs, or any static host.

Quick start

Install the CLI (Node.js 22 or newer):

sh
npm install openwiki

Generate a wiki for the current repository. The first run walks you through picking a provider, key, and model, then writes docs to openwiki/:

sh
openwiki --init

Keep it current automatically by adding a scheduled CI job that opens a docs PR whenever the wiki changes:

[!NOTE]
On Windows, install with a Node.js package manager (npm install openwiki or pnpm add openwiki). Installing with bun can fall back to compiling the better-sqlite3 native dependency, which needs Visual Studio Build Tools with the Desktop development with C++ workload.

Coding-agent integrations

OpenWiki can run inside an existing coding agent instead of launching its own model. The coding agent investigates the repository, plans and writes the documentation, and uses its native tools and subagents when helpful. OpenWiki provides the MCP lifecycle that prepares the repository, constrains the run, and deterministically finalizes indexes, provenance, setup files, and metadata.

Install the integration for your coding agent (choose one):

sh
openwiki integrations install codex
openwiki integrations install claude

The supported targets are Codex and Claude Code. Both install at user level by default, so one installation works from any Git repository. Project paths are resolved to their Git repository root. Restart the coding agent after installation, open the repository, and ask:

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

For an existing wiki, ask:

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

Host-driven runs currently support repository code wikis, not personal brains. They use the coding agent's authenticated model session, so OpenWiki provider credentials are not required. OpenWiki still owns deterministic setup and finalization; the coding agent owns research, planning, factual authoring, and semantic review.

External coding-agent integrations currently use repository source and tests only. Connector-sourced context, including LangSmith, is not yet supported.

The integration exposes lifecycle bookends plus Grounded Claims inspection and resolution. Codex or Claude authors Markdown with native repository tools while OpenWiki validates and persists the evidence-backed propositions behind factual pages.

Use openwiki integrations list to inspect user-level installation status or openwiki integrations uninstall <host> to remove an integration safely. Add --project [path] to list, install, or uninstall for repository-scoped state.

Contributors adding another coding agent should follow
Adding a coding-agent integration.

Grounded Claims

OpenWiki makes code wikis self-correcting by tracking the material propositions behind factual pages—not just when a Markdown file was last generated. Claims cover the truths future agents rely on: behavior, responsibilities, architecture, data flow, invariants, failure semantics, configuration, and security boundaries. Each one points to exact repository evidence such as repo://src/server.ts#L40-L82, with the evidence version OpenWiki observed when the claim was established.

Before an update, OpenWiki checks those evidence versions. If source lines changed or disappeared, the affected claim becomes stale or unresolved. That debt stays quiet until the relevant page is read, then the agent can inspect it and confirm, revise, or retract the proposition. The Markdown stays clean; structured claim state lives alongside it under openwiki/.claims/.

Grounded Claims currently apply to repository code wikis and repository evidence. Connector-derived facts, including LangSmith-only observations, are not claimed.

Two modes

OpenWiki runs in one of two modes. Bare openwiki, openwiki --init, and openwiki --update default to code mode; add the personal positional (or --mode personal) for the personal brain.

Mode Documents Writes to Get started
Code (default) The current repository openwiki/ in the repo openwiki --init
Personal Your connected sources ~/.openwiki/wiki openwiki personal --init

By default the CLI stays open after a run so you can send follow-up messages. Add -p / --print for a one-shot, non-interactive run that prints the final output and exits. --init and --update auto-exit on success in an interactive terminal, so the same command works one-shot or interactively.

Explore your wiki

Turn any wiki into an interactive node graph with a live, side-by-side Markdown reader:

sh
openwiki visualize

This serves ./openwiki on a local loopback address (127.0.0.1, never exposed on the network) and opens your browser to the graph. Edits to the wiki files are picked up automatically while the server runs. Pass a path to visualize a different directory, --port to choose the port (it increments on conflict; default 4321), and --no-open to leave the browser alone:

sh
openwiki visualize openwiki --port 4400 --no-open

To publish the visualizer beside generated documentation, export a static directory instead of starting the server:

sh
openwiki visualize openwiki --export docs/openwiki-visualizer

The export contains index.html, client.js, client-lib.js, styles.css, and graph.json. Its client reads the sibling graph file and does not use live reload, so the directory can be hosted by GitHub Pages, MkDocs, or any other static host. --export cannot be combined with --port or --no-open.

[!NOTE]
The page loads its graph, Markdown, and diagram libraries from a public CDN, so an internet connection is required for both local and static viewers.

Connect your sources

In personal mode, OpenWiki ingests knowledge from the tools you already use, synthesizing them into your local wiki. First-run onboarding offers setup for Custom MCP, local git repositories, Notion, Gmail, X/Twitter, Web Search, and Hacker News. Slack is also available with its OAuth app and HTTPS callback configured.

During an ingestion run, deterministic connector tools write raw data and manifests under ~/.openwiki/connectors/<connector>/raw/, then source-specific agent runs synthesize the wiki under ~/.openwiki/wiki/. You can configure the same connector more than once (for example one Web Search source for AI research and another for NBA news); OpenWiki stores them as separate instances like web-search-1 and web-search-2.

sh
openwiki auth notion        # run a local browser OAuth flow for a provider
openwiki ingest all         # run every configured source
openwiki ingest web-search  # run one connector's sources

Connector details and OAuth

  • git-repo reads configured local repository paths and writes compact manifests.
  • custom-mcp connects to any configured HTTP or stdio MCP server and permits only explicitly safe, read-only tools.
  • x uses the X API directly with OAuth user-context credentials for home timeline, user posts, mentions, bookmarks, and list posts.
  • notion targets the hosted Notion MCP server, so authenticate through Notion OAuth rather than pasting a token.
  • google uses the Gmail API directly with OAuth user credentials to fetch recent mail.
  • slack uses Slack's Web API with OAuth user and bot tokens to ingest scoped conversations and search results.
  • web-search uses Tavily through LangChain and requires TAVILY_API_KEY.
  • hackernews uses the public Hacker News feed and search APIs, with no credentials required.

openwiki auth runs a local browser OAuth flow, saves returned tokens into ~/.openwiki/.env, creates connector config when possible, and discovers MCP tools for MCP-backed providers. Slack and Gmail require app client credentials to already be set in that file; Notion uses dynamic client registration for hosted MCP; X uses OAuth 2.0 with PKCE. openwiki auth configure and openwiki auth tools are advanced retry commands.

Connector secrets are referenced by env var name and stored in ~/.openwiki/.env; connector config files never contain raw secret values.

Slack OAuth tunnel. openwiki ngrok start starts an ngrok tunnel with a random HTTPS forwarding URL, reads ngrok's local inspection API, appends /callback, and saves OPENWIKI_HTTPS_OAUTH_REDIRECT_URI automatically. Register the printed callback URL in Slack. With a fixed domain, run openwiki ngrok start https://<your-ngrok-domain>.

LangSmith connector (code mode)

The connectors above feed a personal wiki. The LangSmith connector instead enriches a code wiki: it pulls recent LangSmith traces (tool calls, outcomes, and latency) for the projects you choose through the official LangSmith SDK, so a repository's docs reflect how its code actually behaves at runtime, not just 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), so every teammate and CI run documents the same set. The API key is read from the environment:

sh
OPENWIKI_LANGSMITH_API_KEY="<your-langsmith-key>"

Locally the setup wizard saves this to ~/.openwiki/.env. In CI, set it as a repository secret and export it for the run.

[!NOTE]
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 only talks to the official US (api.smith.langchain.com), EU (eu.api.smith.langchain.com), and APAC (apac.api.smith.langchain.com) hosts.

How it stays yours

Your wiki stays in the repository as plain Markdown you own, with OpenWiki-managed grounding and run metadata versioned alongside it.

  • Agents read it as memory. On each code run, OpenWiki maintains an AGENTS.md and CLAUDE.md at the repo root that point your coding agent at the wiki. It only rewrites its own … block and leaves the rest of each file untouched.
  • Grounding stays with the wiki. Versioned claim sidecars under openwiki/.claims/ travel with the Markdown, so the evidence needed to maintain factual pages is inspectable and reviewable.
  • You set the brief. Repository-specific instructions live in openwiki/INSTRUCTIONS.md, a user-authored file OpenWiki reads for scope and priorities but never rewrites during normal runs.
  • No-op runs do not churn docs. A clean update skips model work and leaves wiki content untouched while refreshing .last-update.json to record that the check ran.
  • Local, private config. Provider choice, keys, and optional LangSmith tracing are saved to ~/.openwiki/.env on your machine.

Open Knowledge Format (OKF v0.2)

OpenWiki emits Google Open Knowledge Format (OKF) v0.2 bundles in both modes, so your wiki is portable to any OKF-aware tool.

  • Every concept document carries YAML front matter with a non-empty type; all other standard fields are optional.
  • Pages record their last body change as generated: {by, at}; any body change, including whitespace, advances the stamp, while front-matter-only changes do not. The producer is stamped as openwiki/<version> (or the coding-agent host), making provenance explicit. The legacy v0.1 timestamp field is still tolerated on existing pages.
  • The optional v0.2 provenance, trust, and lifecycle families (sources, verified, status, stale_after) are validated when present.
  • Standard Markdown links between concept documents express their relationships.
  • index.md and log.md are reserved documents rather than concepts. The root index declares okf_version: "0.2".
  • Producer-defined extension fields are preserved across updates and migrations.

Diagrams

OpenWiki embeds Mermaid diagrams wherever they make a concept clearer than prose: sequence diagrams for runtime flows, ER diagrams for data models, state diagrams for lifecycles, and flowcharts for control flow. Diagrams are grounded in the inspected source, added where they add signal, and kept in sync on --update. No configuration is required.

After each run, OpenWiki validates every mermaid fence. A diagram that fails validation is converted in place to a plain text fence with a short comment explaining why, so it degrades to readable text instead of a broken block. The next --update finds that comment and repairs the diagram, so quality recovers over successive runs.

[!TIP]
By default OpenWiki runs a lightweight, zero-dependency check that catches common breakages. For authoritative validation that matches exactly what GitHub renders, install the Mermaid parser wherever you run OpenWiki (for example in your scheduled workflow), and no broken diagram will ship:

sh
npm install mermaid jsdom

Model providers

The onboarding default is OpenAI with gpt-5.6-terra. Every provider includes preset model options plus support for custom model IDs, and stores its credentials in ~/.openwiki/.env.

Provider Credential
OpenAI (default) OPENAI_API_KEY
OpenAI (ChatGPT login) Browser sign-in, uses your ChatGPT plan
Anthropic ANTHROPIC_API_KEY
Gemini (AI Studio) GEMINI_API_KEY
Gemini Enterprise (Vertex AI) Google ADC, keyless
AWS Bedrock IAM credentials
GitHub Copilot GitHub CLI session
OpenRouter OPENROUTER_API_KEY
Nebius / Fireworks / Baseten / NVIDIA NIM Provider API key
OpenAI-compatible (LiteLLM, Ollama, LM Studio, gateways) Base URL + key

GitHub Copilot

The GitHub Copilot provider routes inference through the OpenAI-compatible Copilot API (https://api.githubcopilot.com), so teams can reuse an existing Copilot subscription instead of provisioning a separate inference key.

  1. Select GitHub Copilot during openwiki --init. If you have an active GitHub CLI session, OpenWiki detects it and offers to reuse it. Otherwise, press Tab at the credential prompt to run gh auth login and sign in.
  2. Choose a model (for example gpt-5.5).

OpenWiki leaves the token in the GitHub CLI's own credential store. For CI or another headless environment, set COPILOT_API_KEY to a GitHub OAuth token. Personal Access Tokens are rejected by the Copilot API for third-party integrations. The local config can stay token-free:

env
OPENWIKI_PROVIDER="copilot"
OPENWIKI_MODEL_ID="gpt-5.5"

In CI, set the COPILOT_API_KEY repository secret and export OPENWIKI_PROVIDER=copilot.

AWS Bedrock

The bedrock provider calls foundation models on AWS Bedrock using IAM credentials rather than a single vendor key:

bash
OPENWIKI_PROVIDER=bedrock
BEDROCK_AWS_ACCESS_KEY_ID=your-access-key-id
BEDROCK_AWS_SECRET_ACCESS_KEY=your-secret-access-key
BEDROCK_AWS_REGION=us-east-1
OPENWIKI_MODEL_ID=anthropic.claude-sonnet-5

When explicit Bedrock credentials are not set, OpenWiki uses the AWS SDK default credential provider chain (OIDC/web identity, IAM roles, AWS profiles, ECS/EC2). The region resolves from BEDROCK_AWS_REGION, AWS_REGION, or AWS_DEFAULT_REGION. Available model IDs depend on which foundation models you have enabled in your account and region, so there is no preset list; paste the Bedrock model ID directly.

Some newer models only accept on-demand invocation through a cross-region inference profile. If you see ValidationException: Invocation of model ID ... with on-demand throughput isn't supported, prefix the model ID with the profile's region code, for example us.anthropic.claude-sonnet-5. Your IAM policy then also needs bedrock:InvokeModel / InvokeModelWithResponseStream on both the foundation-model and inference-profile resource types.

Gemini (AI Studio) and Gemini Enterprise (Vertex AI)

Gemini (AI Studio) runs Google's Gemini models with a single API key:

bash
OPENWIKI_PROVIDER=gemini
GEMINI_API_KEY=your-ai-studio-key

Gemini Enterprise runs models from the Gemini Enterprise Model Garden (formerly Vertex AI): Google's Gemini/Gemma, Anthropic's Claude, and partner/open-weight models (Llama, Mistral, DeepSeek, Qwen). It routes each model ID to the right API surface automatically and uses no API key. Authentication happens with Google Application Default Credentials (ADC):

  • a service account key file via GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json,
  • user credentials from gcloud auth application-default login, or
  • workload identity when running on Google Cloud or in CI.
bash
OPENWIKI_PROVIDER=gemini-enterprise
GOOGLE_CLOUD_PROJECT=your-gcp-project
GOOGLE_CLOUD_LOCATION=global   # optional, defaults to global

Set OPENWIKI_MODEL_ID to any Model Garden model. Gemini and Claude ship as presets; partner models are reached by pasting their ID (for example publishers/meta/models/llama-3.3-70b-instruct-maas). The credentials need Vertex AI access (roles/aiplatform.user), and the models must be enabled in the Model Garden. The global endpoint serves Gemini and Claude with the best availability; set GOOGLE_CLOUD_LOCATION to a regional endpoint for data residency, and always set it explicitly for region-specific partner (MaaS) models.

For CI, authenticate before the update job runs (for example with google-github-actions/auth) and set OPENWIKI_PROVIDER=gemini-enterprise and GOOGLE_CLOUD_PROJECT in the job environment.

OpenAI (ChatGPT login)

The openai-chatgpt provider calls OpenAI's Codex backend using your ChatGPT subscription instead of a metered API key, drawing on your Plus/Pro/Team plan's included Codex usage. It serves the same model list as the openai provider.

bash
OPENWIKI_PROVIDER=openai-chatgpt openwiki code --init
# or
OPENWIKI_PROVIDER=openai-chatgpt openwiki personal --init

The wizard opens https://auth.openai.com in your browser (and prints the URL for headless/SSH use). After you sign in, OpenWiki captures the OAuth callback, shows the signed-in email and plan, and continues to model selection. It stores the access token, refresh token, expiry, account id, email, and plan in ~/.openwiki/.env. These are managed for you and the access token is refreshed automatically, so you normally never edit them by hand. Treat the refresh token like a password.

OpenAI-compatible endpoints (LiteLLM, Ollama, LM Studio, gateways)

The openai-compatible provider targets any OpenAI-compatible chat-completions endpoint via a required base URL. Set the model ID to whatever the endpoint exposes.

bash
# Hosted gateway (for example Requesty, which fronts many upstream providers)
OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=your-gateway-key
OPENAI_COMPATIBLE_BASE_URL=https://router.requesty.ai/v1
OPENWIKI_MODEL_ID=openai/gpt-5.5
bash
# Ollama, after `ollama serve` and `ollama pull llama3.2`
OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=ollama
OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1
OPENWIKI_MODEL_ID=llama3.2
bash
# LM Studio, after starting the local server from the Developer tab
OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=lm-studio
OPENAI_COMPATIBLE_BASE_URL=http://localhost:1234/v1
OPENWIKI_MODEL_ID=your-loaded-model-id

Some local servers ignore the API key value, but OpenWiki still requires OPENAI_COMPATIBLE_API_KEY because the client expects one.

Streaming-only gateways. Some gateways serve only the streaming transport: a non-streaming request is either rejected outright (Stream must be set to true) or answered with HTTP 200 and empty content, which leaves you with a blank wiki and no error. OpenWiki issues non-streaming requests internally, so force the streaming transport for those endpoints:

bash
OPENWIKI_OPENAI_COMPATIBLE_STREAMING=true

It stays off by default because this provider points at arbitrary third-party endpoints, where SSE is not guaranteed to survive proxies and load balancers. Enabling it also makes the client report estimated rather than server-reported token counts.

Alternative base URLs, OpenRouter pinning, and retries

Alternative base URLs. Route a provider at a self-hosted or proxied gateway by setting its base URL alongside its key: ANTHROPIC_BASE_URL, OPENAI_BASE_URL, BASETEN_BASE_URL, FIREWORKS_BASE_URL, NVIDIA_BASE_URL, or COPILOT_BASE_URL. The openai provider routes tool calls through the Responses API (/v1/responses), which is useful for gateways that expose it.

bash
OPENWIKI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-key
ANTHROPIC_BASE_URL=https://your-gateway.example.com/anthropic

OpenRouter provider pinning. When OpenRouter serves a model through multiple upstreams, restrict routing with a provider or comma-separated allowlist:

bash
OPENWIKI_PROVIDER=openrouter
OPENROUTER_API_KEY=your-key
OPENWIKI_OPENROUTER_PROVIDER_ONLY=Novita

Output-token limit. OpenWiki uses a 16,384-token per-request default for modern Claude 4/5 models because older LangChain model metadata otherwise limits newer Claude aliases to 4,096 tokens. Set a provider-neutral limit for the currently selected model with:

bash
OPENWIKI_MAX_OUTPUT_TOKENS=16384

OpenWiki maps this setting to the selected provider's request shape. Custom models otherwise retain their provider or SDK default, since their supported output windows are not known to OpenWiki.

OpenRouter output-token cap. By default no max_tokens is sent, so OpenRouter's credit pre-check budgets for the model's full advertised output ceiling — on a low credit balance every request can fail with a 402 error. Existing installations can keep an OpenRouter-specific cap with:

bash
OPENWIKI_OPENROUTER_MAX_TOKENS=8192

The OpenRouter-specific setting takes precedence over OPENWIKI_MAX_OUTPUT_TOKENS for OpenRouter runs. A cap trades those hard 402 failures for possible truncation when a long wiki generation genuinely needs more output tokens, so prefer the largest value your balance allows.

Retry attempts. OpenWiki uses LangChain's retry handling for transient provider errors. Override the retry count (default 3) with OPENWIKI_PROVIDER_RETRY_ATTEMPTS=3 (a positive integer).

Bedrock stream idle timeout. For the Bedrock provider, set OPENWIKI_STREAM_IDLE_TIMEOUT to control how long the client waits for the first or next streamed response chunk, for example OPENWIKI_STREAM_IDLE_TIMEOUT=300000. The value is milliseconds and must be an integer from 0 to 2147483647. Set it to 0 to disable the watchdog. If unset, OpenWiki preserves the @langchain/aws provider default. Prefer a sufficiently long finite timeout over disabling the watchdog so a stalled stream cannot hang forever.

Reasoning effort. Set OPENWIKI_REASONING_EFFORT to configure reasoning for a supported provider and model. OpenAI GPT-5.6 models use the Responses API values none, low, medium, high, xhigh, and max. NVIDIA NIM's Nemotron 3 Super supports none, low, and high. In an interactive chat, use /effort to choose an available value or /effort default to restore the provider default. Leave the variable unset to preserve the provider default; invalid provider, model, or effort combinations fail before a request is sent.

[!NOTE]
If there is an inference provider or model you would like to see added, please open a PR.

Ignoring 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:

gitignore
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. This is a read boundary: ignored paths are never read, scanned, or reproduced in the docs. It does not guarantee a topic is never mentioned, since the agent may still infer an ignored area from other allowed evidence such as tests, the README, or commit messages.

Command reference

sh
openwiki                         # interactive chat, code mode, current repo
openwiki personal                # interactive chat, personal brain
openwiki "generate docs"         # start with an initial request
openwiki -p "what can you do?"   # one-shot, print, and exit
openwiki --init                  # initialize code docs (personal: openwiki personal --init)
openwiki --update                # update code docs (personal: openwiki personal --update)
openwiki visualize               # interactive graph + live reader
openwiki visualize openwiki --export docs/openwiki-visualizer  # static graph + reader
openwiki auth          # authenticate a connector (slack, gmail, x, notion)
openwiki ingest          # run connector ingestion (all, or a connector/instance)
openwiki integrations list       # show installed coding-agent integrations
openwiki integrations install <codex|claude> [--project [path]]
openwiki integrations uninstall <codex|claude> [--project [path]]
openwiki --help                  # full help

In chat, /api-key updates the current provider key and /langsmith-key updates or clears LangSmith tracing credentials, both with masked prompts.

Telemetry

OpenWiki collects anonymous, aggregate usage data to understand how the tool is used and improve it. Telemetry is on by default and easy to turn off.

Collected on a single openwiki_run event, keyed by a random install ID in ~/.openwiki/install-id: the command (init / update), the outcome (success / failure / no-op) with a coarse error category on failure (never the message), and at setup only, the brain mode, model provider, and configured connector names.

Never collected: file contents, repository data or names, credentials, prompts, model output, connector payloads, error messages, file paths, URLs, model IDs, run duration, or your IP address. Interactive chat, auth, and ingest are not recorded. Scheduled/CI runs are tagged as anonymous reliability data under a shared CI identifier and never counted as installs.

Opt out with either environment variable, or add the first line to ~/.openwiki/.env to disable permanently:

sh
export OPENWIKI_TELEMETRY_DISABLED=1
export DO_NOT_TRACK=1   # cross-tool standard

To see exactly what a run would send, add --telemetry-file= to any run.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR. We intentionally keep PRs tightly scoped to one change each, and PRs that bundle unrelated changes may be closed with a request to split them.

License

MIT

2. Official Technical Reference & Guides (langchain-ai/docs)

LangChain Docs

🦜 Welcome! This repository contains the documentation build pipeline for LangChain projects.

Table of contents:

Contribute

To run a local preview of the documentation:

bash
git clone https://github.com/langchain-ai/docs.git
bash
cd docs
bash
make install
bash
make dev

For more information on how to contribute to LangChain documentation, follow the steps outlined in the contributing guide. The contributing guide also explains our documentation types and their writing and quality standards.

For detailed information about setting up your development environment and contributing to documentation, see the documentation contributing guide.

To report issues with reference.langchain.com (missing pages, broken links, or generated API content), open a reference documentation issue on this repo so maintainers can route it.

Reference

Repository structure

text
# --- docs.langchain.com ----------------------------------------------
build/                    # Built docs (DO NOT EDIT)
packages.yml              # Package metadata (indexes, tables, downloads; not the API reference build)
pipeline/                 # Build pipeline source code
scripts/                  # Helper scripts
src/                      # Source documentation files (< EDIT CONTENT HERE)
    langsmith/            # LangSmith docs
    oss/                  # LangChain, LangGraph, Deep Agents, and integrations docs
    docs.json             # Mintlify site configuration and navigation
tests/                    # Test files for the pipeline
Makefile                  # Build targets
pyproject.toml            # Dependencies

`docs.langchain.com`

The Mintlify docs pipeline is structured with .mdx source files in /src and build artifacts in /build. Mintlify deploys from the /build folder, which is generated by preprocessing logic.

[!IMPORTANT]
Never edit /build directly.

The /src/docs.json file is used to configure the Mintlify site navigation and settings. Refer to the Mintlify documentation for detailed syntax and component usage.

Documentation changes follow a PR workflow where all tests must pass before merging. See the contributing guidelines for more details.

`reference.langchain.com`

API reference is generated and deployed outside this repo. Browse Python and JavaScript/TypeScript reference there. If something is wrong with that site, use the reference docs issue template.

File formats

  • Markdown files (.md, .mdx) - Standard documentation content
  • Snippets (src/snippets/) - Reusable MDX content that can be imported into multiple pages. Important: Snippets undergo special link preprocessing. When writing links in snippets, be careful about path segments.
  • Jupyter notebooks (.ipynb) - Converted to markdown during build, though these are not recommended for new content! Your PR will likely be rejected if you attempt to add a Jupyter notebook unless asked to by a maintainer.
  • Assets - Images and other files are copied to the build directory

Available commands

Make commands:

  • make dev - Start development mode with file watching and live rebuild
  • make build - Build documentation to ./build directory
  • make broken-links - Check for broken links in documentation
  • make broken-links-with-anchors - Check for broken links + check links with anchors
  • make install - Install all dependencies
  • make clean - Remove build artifacts
  • make test - Run the test suite
  • make lint - Check code style and formatting
  • make format - Auto-format code
  • make lint_md - Lint markdown files
  • make lint_md_fix - Lint and fix markdown files
  • make help - Show all available commands

docs CLI tool:

The docs command (installed as uv run docs) provides additional functionality:

  • docs migrate - Convert MkDocs markdown/notebook files to Mintlify format

    • --dry-run - Preview changes without writing files
    • --output - Specify output location (default: in-place)
    • Supports .md, .markdown, .ipynb files

  • docs migrate-docusaurus - Convert Docusaurus markdown/notebook files to Mintlify format

    • --dry-run - Preview changes without writing files
    • --output - Specify output location (default: in-place)
    • Supports .md, .markdown, .mdx, .ipynb files
    • Converts Docusaurus-specific syntax (admonitions, tabs, imports, etc.)

  • docs mv <old_path> <new_path> - Move files and update cross-references

    • --dry-run - Preview changes without moving files

These can be used directly using the Makefile or via the docs CLI tool:

  • docs dev - Start development mode with file watching and hot reload

    • Automatically rebuilds changed files from src/ to build/
    • Launches Mintlify dev server at http://localhost:3000
    • Provides automatic browser refresh when files change
    • --skip-build - Skip initial build and use existing build directory

  • docs build - Build documentation files

    • --watch - Watch for file changes after building

Linting

After running make install, you can use make lint_prose to ensure your writing meets our style guide rules.

Codespell

make lint runs uv run codespell src to check source documentation for common spelling errors.

Codespell is configured in pyproject.toml under [tool.codespell]:

  • Add custom accepted words to src/.codespellignore. This file is referenced by ignore-words = "src/.codespellignore".
  • Exclude generated files, vendor content, or other paths that should not be spell checked by adding glob patterns to the skip setting.
  • Keep skip patterns scoped. Prefer adding accepted words to src/.codespellignore when the word is valid documentation content, and use skip when the file or directory should not be checked at all.

You can also follow these steps to enable vale with VS Code or Cursor:

  1. Install the Vale extension (Vale by Chris Chinchilla)
  2. Install Vale CLI: brew install vale (macOS) or see Vale installation for other platforms
  3. Navigate to the Vale extension settings:
    • Set Vale CLI: Config to the absolute path to .vale.ini (in the root of this repo)
    • Set Vale CLI: Min Alert Level to suggestion (many rules are coded as suggestions)

If you cannot use the VS Code UI to configure Vale, add these settings to your settings.json:

json
"vale.valeCLI.config": "/path/to/docs/.vale.ini",
    "vale.valeCLI.minAlertLevel": "suggestion"

Note: The extension requires Vale on your PATH. If annotations don't appear (e.g., when Cursor is launched from the Dock), launch Cursor from a terminal so it inherits your PATH, or ensure Homebrew is in your shell profile.

Troubleshooting

General Mintlify errors

In some cases, we use new features that are only available in the latest Mintlify CLI. If you encounter errors, ensure you have the latest version installed:

bash
mint update

# or

npm install mint

`docs dev` not working / running

Re-do the steps to set up your dev environment, ensuring you have activated the virtual environment and installed all dependencies.

[!IMPORTANT]
Most of the time, mint update solves any docs dev / make dev issues!

Mintlify `.venv` parsing error

Problem: Running mint broken-links or other Mintlify commands from the project root causes parsing errors like:

txt
Unable to parse .venv/lib/python3.13/site-packages/soupsieve-2.7.dist-info/licenses/LICENSE.md
- 3:48: Unexpected character '@' (U+0040) in name

Root Cause: Mintlify tries to parse all files in the directory, including Python virtual environment files that contain invalid MDX syntax.

Solutions (in order of preference):

  1. Use the safe Make commands (recommended):

    bash
    make broken-links-with-anchors      # Builds docs first, then checks internal links

  2. Run Mintlify commands from the build directory:

    bash
    cd build               # Change to build directory where final docs are
mint broken-links      # Now safe to run

Why this works: The solution ensures Mintlify commands run from the build/ directory where the final documentation is generated, which is the correct place to check for broken links. This avoids scanning the Python virtual environment in the project root.

Prevention: Always use the provided Make commands instead of running raw mint commands from the project root.

Warning: page doesn't exist

If adding a new group, ensure the root index.mdx is included in the pages array like:

json
{
  "group": "New group",
  "pages": ["new-group/index", "new-group/other-page"]
}

If the trailing /index (no extension included) is omitted, the Mintlify parser will raise a warning even though the site will still build.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →