## 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](https://github.com/langchain-ai/deepagentsjs) 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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)) 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: - **GitHub Actions:** copy [`openwiki-update.yml`](./examples/openwiki-update.yml) into `.github/workflows/openwiki-update.yml`. - **GitLab CI:** copy [`openwiki-update.gitlab-ci.yml`](./examples/openwiki-update.gitlab-ci.yml) into `.gitlab-ci.yml` or include it from your pipeline. - **Bitbucket Pipelines:** copy [`openwiki-update.bitbucket-pipelines.yml`](./examples/openwiki-update.bitbucket-pipelines.yml) into `bitbucket-pipelines.yml`, then schedule the `openwiki-update` pipeline. > [!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 ` 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](CONTRIBUTING.md#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//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://`. ### 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="" ``` 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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) 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/` (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](https://cli.github.com) 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`](https://github.com/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 [--project [path]] openwiki integrations uninstall [--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](./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](./LICENSE) ## 2. Official Technical Reference & Guides (langchain-ai/docs) # LangChain Docs ๐Ÿฆœ **Welcome!** This repository contains the documentation build pipeline for LangChain projects. * ๐Ÿ  [`docs.langchain.com`](https://docs.langchain.com) is our docs home, centralizing LangChain, LangGraph, LangSmith, and LangChain Labs (Deep Agents, Open SWE, Open Agent Platform). This site is hosted on [Mintlify](https://mintlify.com). * ๐Ÿ› ๏ธ [`reference.langchain.com`](https://reference.langchain.com/python/) hosts generated API reference for LangChain, LangGraph, LangSmith, and integration packages. That site is **not** built from this repository (no reference build scripts or output live here). * [`Python reference`](https://reference.langchain.com/python/) * [`JavaScript/TypeScript reference`](https://reference.langchain.com/javascript/) * ๐Ÿ’ฌ [`chat.langchain.com`](https://chat.langchain.com) is an AI-powered assistant that can answer questions about LangChain documentation. --- **Table of contents:** - [LangChain Docs](#langchain-docs) - [Contribute](#contribute) - [Reference](#reference) - [Repository structure](#repository-structure) - [`docs.langchain.com`](#docslangchaincom) - [`reference.langchain.com`](#referencelangchaincom) - [File formats](#file-formats) - [Available commands](#available-commands) - [Linting](#linting) - [Codespell](#codespell) - [Troubleshooting](#troubleshooting) - [`docs dev` not working / running](#docs-dev-not-working--running) - [Mintlify `.venv` parsing error](#mintlify-venv-parsing-error) - [Warning: page doesn't exist](#warning-page-doesnt-exist) - [General Mintlify errors](#general-mintlify-errors) --- ## 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](https://docs.langchain.com/oss/python/contributing/overview). 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](https://docs.langchain.com/oss/python/contributing/documentation). To report issues with **reference.langchain.com** (missing pages, broken links, or generated API content), [open a reference documentation issue](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml) 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](https://www.mintlify.com/docs/organize/navigation) for detailed syntax and component usage. Documentation changes follow a PR workflow where all tests must pass before merging. See the [contributing guidelines](https://docs.langchain.com/oss/python/contributing/documentation) for more details. #### `reference.langchain.com` API reference is generated and deployed outside this repo. Browse [Python](https://reference.langchain.com/python/) and [JavaScript/TypeScript](https://reference.langchain.com/javascript/) reference there. If something is wrong with that site, use the [reference docs issue template](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml). ### 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 `** - 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 * 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](https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vale-vscode) (Vale by Chris Chinchilla) 2. Install Vale CLI: `brew install vale` (macOS) or see [Vale installation](https://vale.sh/docs/vale-cli/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](https://docs.langchain.com/oss/python/contributing/documentation#set-up-local-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.