langchain-ai/openwiki

All integrations install at user level by default, so one installation works from any Git repository. Use openwiki integrations list to inspect installation status or openwiki integrations uninstall <host> to remove an integration safely. Add --project [path] to list, install, or uninstall for repository-scoped state; project paths resolve to their Git repository root.

Host-specific locations and notes:

• OpenCode uses ~/.config/opencode.
• IBM Bob / Bob Shell uses ~/.agents/skills and ~/.bob/settings/mcp.json at user scope; .agents/skills and .bob/mcp.json at the project.
• Kiro uses ~/.kiro/skills and ~/.kiro/settings/mcp.json.
• Oh My Pi uses ~/.omp/agent at user scope (the default profile). Use --project for named profiles or a relocated PI_CODING_AGENT_DIR.
• Antigravity uses ~/.gemini/antigravity-cli/skills and ~/.gemini/config/mcp_config.json.
• GitHub Copilot CLI uses ~/.copilot/skills and ~/.copilot/mcp-config.json at user scope; .github/skills and .github/mcp.json at the project.
• Pi is separate from Oh My Pi. Pi loads OpenWiki's skill and six lifecycle tools from the npm package; use pi install --local npm:openwiki for a project-local install. Its extension starts the package's own CLI through Node, so openwiki need not be on PATH. Pi is not a target of openwiki integrations install.

On Windows, install with a Node.js package manager (npm install -g openwiki or pnpm add -g 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.

Host-driven runs currently support repository code wikis, not personal brains. They use repository source and tests; connector-sourced context, including LangSmith, is not yet supported.

The coding agent investigates the repository, plans the wiki, and writes each assigned page sequentially with its native repository tools. OpenWiki owns the durable queue, Claims validation and persistence, source-drift handling, and deterministic finalization of Claims, indexes, provenance, setup files, and metadata.

The MCP generation lifecycle is openwiki_begin → openwiki_submit_plan → openwiki_next_page → openwiki_submit_page → … → openwiki_finish, with optional on-demand openwiki_inspect_page_claims. The host submits only sparse Claim decisions for each page: OpenWiki retains current unaffected Claims, applies explicit confirmations, revisions, additions, or retractions, and refuses to finish until the final state is durable.

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

The finder streams Git repositories below the editable path, starting at the launch directory. Extend the path to narrow results, or Backspace toward ~ to broaden and rescan from the nearest existing directory. Each repository appears once by path: ○ marks an available OpenWiki repository and becomes ● when selected. Repositories without OpenWiki documentation are dimmed. Selections remain pinned above the changing results and also remain in the finder.

From an OpenWiki source checkout, run the manager with pnpm run dev link ~/dev. The registry is stored privately under ~/.openwiki (or OPENWIKI_CONFIG_DIR).

Search chooses its scope as follows:

1. A wiki in no workspace searches itself.
2. A wiki in one workspace searches that workspace automatically.
3. A wiki in multiple workspaces uses its active workspace.
4. If it belongs to multiple workspaces without an active selection, search returns workspace_required and the agent asks which workspace to use.

Set, inspect, or clear a repository's persistent active workspace from anywhere inside that repository:

openwiki workspace use payments
openwiki workspace current
openwiki workspace clear

Agents can call openwiki_list_workspaces to discover the current or another wiki's memberships and openwiki_list_wikis to inspect a workspace. Workspace search results identify their supplying wiki; pass that ID to openwiki_read with the result's page and section anchors.

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 <port> to choose the port (it increments on conflict; default 4321), and --no-open to leave the browser alone:

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

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

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.

Auto-merge is repository infrastructure rather than an OpenWiki runtime feature. The GitHub Actions example creates a docs-only PR and enables GitHub auto-merge only after OpenWiki finishes successfully; required branch checks and reviews still control when the PR merges. Failed runs can preserve partial documentation in the PR and explicitly disable any pending auto-merge.

Before using the example:

1. Enable Allow auto-merge in the repository's pull request settings.
2. Add branch protection or a ruleset for the default branch. Require the checks that should gate generated docs, and decide whether OpenWiki PRs still require human review.
3. Create a fine-grained personal access token or GitHub App token with access only to the target repository and permissions for Contents: read and write and Pull requests: read and write. Save it as the OPENWIKI_PR_TOKEN Actions secret.
4. Copy the example to .github/workflows/openwiki-update.yml, choose a pinned OpenWiki version and provider, and add the provider secret.

The dedicated token is intentional: pull requests created with the default GITHUB_TOKEN do not start most pull_request workflows, so required PR checks may never run. Organization policies may require a GitHub App token instead of a personal access token. Keep the workflow's add-paths restricted to generated documentation, pin every action and package version, and do not auto-merge changes to executable workflow files.

Running openwiki --init again replaces the existing generated repository wiki and Claims with a brand-new generation while preserving the user-authored openwiki/INSTRUCTIONS.md brief. On a persistent checkout, OpenWiki records in-progress repository generation in openwiki/.run.json, so rerunning the same command after an interruption resumes the durable page queue. Ephemeral CI runners start fresh after failure unless their workspace is preserved. A setup failure before the new run state is durable restores the previous wiki.

Each worker owns exactly one page, and completed pages remain durable resume units. The quickstart page is written last so it can link to the pages it routes to. A worker that fails on a provider rate limit lowers the run's concurrency by one for the rest of the run; the page it was writing is restored and picked up by the next update.

LangChain handles transient provider errors. Retry attempts default to 3, or 5 when OPENWIKI_PAGE_CONCURRENCY is above 1. Override with OPENWIKI_PROVIDER_RETRY_ATTEMPTS=3 (a positive integer).

With LangSmith tracing on, the planner and each page worker are separate traces, grouped into one LangSmith thread per run. The thread id is the run's id, which a resumed run keeps; set OPENWIKI_TRACE_THREAD_ID to choose it yourself, for example from CI so a run's thread can be found from the commit that triggered it.

OpenWiki stores local credentials, the personal wiki, connector data, conversation history, and skills under ~/.openwiki by default. Set OPENWIKI_CONFIG_DIR before starting OpenWiki to use a different writable directory, such as a mounted container volume:

OPENWIKI_CONFIG_DIR=/data/openwiki openwiki personal --init

The override selects a separate state directory; OpenWiki does not move or delete an existing ~/.openwiki directory. Copy any state you want to preserve yourself, and point the variable at a dedicated directory because OpenWiki restricts its permissions for the current user.

Claims cover the truths future agents rely on: behavior, responsibilities, architecture, data flow, invariants, failure semantics, configuration, and security boundaries. Each records the evidence version observed when the claim was established, rather than relying only on when a Markdown file was last generated.

Before an update, OpenWiki checks every persisted evidence version, before even deciding whether the repository is a no-op. A stale or unresolved Claim requires work for its owning page even if the planner omits it. The page worker receives only Claims requiring attention; current issue-free Claims are retained deterministically without being repeated through every model turn. The worker explicitly confirms rechecked issue Claims, submits only revisions and additions, and names retractions. Complete current Claims remain available through on-demand inspection for broad rewrites. The Markdown stays clean; structured Claim state lives alongside it under openwiki/.claims/.

Page completion is a durability boundary. OpenWiki persists the reconciled Claims, projects verification, synchronizes the sidecar's page version, and proves the complete result before marking that page's job complete. Finalization repeats the whole-run proof before deleting openwiki/.run.json.

• Every concept document carries YAML front matter with a non-empty type; all other standard fields are optional.
• New and freshly initialized pages receive generated: {by, at}. During updates, any body change, including whitespace, advances the stamp; an unchanged body retains its prior event, and front-matter-only changes do not advance it. 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.
• Repository pages project their grounded Claims evidence into sources; OpenWiki reconciles its deterministically identified entries while preserving independently authored sources.
• Repository pages receive verified: {by: openwiki/<version>, at: ...} only after a successful page submission reconciles a non-empty complete Claims set, passes the final evidence recheck, and persists the Claims sidecar. Clean preflight alone never creates or advances verification; human and other process events are preserved.
• 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.

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:

npm install mermaid jsdom

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.

• 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 <provider> 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 <provider> and openwiki auth tools <provider> 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>.

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:

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.

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:

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

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

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

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) runs Google's Gemini models with a single API key:

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.

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.

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.

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.

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.

# 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

# EU-hosted gateway (for example Opper, which serves 700+ models behind one key)
OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=your-opper-key
OPENAI_COMPATIBLE_BASE_URL=https://api.opper.ai/v3/compat
OPENWIKI_MODEL_ID=claude-sonnet-4-6

# 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

# 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 API-key mode still requires OPENAI_COMPATIBLE_API_KEY because the client expects one.

Microsoft Entra ID gateways. During interactive openwiki --init, select OpenAI-compatible, then Microsoft Entra ID. Enter the HTTPS API root, the token scope accepted by your gateway, and the model ID. OpenWiki saves these settings for later --update runs; it does not ask for or store an access token. Azure Identity must be configured separately in each environment that runs OpenWiki. For non-interactive runs, set the same values explicitly:

OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_AUTH=entra-id
OPENAI_COMPATIBLE_BASE_URL=https://gateway.example.com/openai/v1
OPENAI_COMPATIBLE_ENTRA_SCOPE=api://gateway-application-id/.default
OPENWIKI_MODEL_ID=your-gateway-model

OPENAI_COMPATIBLE_ENTRA_SCOPE defaults to https://cognitiveservices.azure.com/.default for Azure OpenAI. Custom gateways may require a different scope. Azure Identity obtains and refreshes the bearer token on model requests, so no OPENAI_COMPATIBLE_API_KEY is needed in Entra mode. Generated CI workflows retain the mode and scope but still require you to configure an unattended Azure Identity credential in CI.

For workload identity federation, provide AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE in the environment running OpenWiki. The file variable must point to the runner-provided federated token file; do not paste the token into OpenWiki or commit the file. When the file variable is set, OpenWiki uses WorkloadIdentityCredential rather than another credential in the default chain. If it is not set, OpenWiki uses DefaultAzureCredential.

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:

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.

Reasoning-capable gateways. OpenAI-compatible endpoints are user-supplied, so OpenWiki does not assume that an arbitrary model supports reasoning controls. If your gateway accepts OpenAI-style reasoning effort, opt in explicitly before setting OPENWIKI_REASONING_EFFORT:

OPENWIKI_OPENAI_COMPATIBLE_REASONING_EFFORT_SUPPORTED=true
OPENWIKI_REASONING_EFFORT=high

When OPENWIKI_OPENAI_COMPATIBLE_USE_RESPONSES_API=true is also set, the effort is sent through the Responses API reasoning field. Otherwise it is sent as the chat-completions reasoning_effort model argument.

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.

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:

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:

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:

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.

For native worker concurrency and provider retry settings, see Parallel page workers.

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. Gemini 3.6 Flash maps low, medium, and high to Gemini's thinking level. 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.