gem-hunter
Language: TypeScript
OpenWiki is a CLI that writes and maintains agent documentation for your codebase.
OpenWiki turns your codebase and knowledge sources into a linked Markdown wiki that you own. Your coding agent can use it to understand a repository, answer questions, and find context across related projects. You can read the same pages or explore them as an interactive graph.
For repository wikis, OpenWiki tracks facts back to source evidence so updates can focus on what changed. Start inside your coding agent, or use the standalone CLI for repository docs, personal knowledge, and scheduled updates.
Get started · Search and link wikis · Explore · Standalone CLI · Command reference
openwiki link, search across their wikis, and read relevant sections through MCP. See how it works →Portable OKF v0.2 output and publishable visualizers are also available.
The easiest way to get started is inside the coding agent you already use. OpenWiki uses that agent's authenticated model session and repository tools, so there is no separate model provider to configure.
You'll need Node.js 22.22.0 or newer.
npm install -g openwiki
If you use Pi, install the package through Pi in step 2 instead; a separate global OpenWiki installation is not required.
Choose the integration for your agent:
| Coding agent | Install |
|---|---|
| Codex | openwiki integrations install codex |
| Claude Code | openwiki integrations install claude |
| OpenCode | openwiki integrations install opencode |
| Cursor | openwiki integrations install cursor |
| IBM Bob / Bob Shell | openwiki integrations install bob |
| Kiro | openwiki integrations install kiro |
| Oh My Pi | openwiki integrations install omp |
| Antigravity | openwiki integrations install antigravity |
| GitHub Copilot CLI | openwiki integrations install copilot |
| Pi | pi install npm:openwiki |
Restart your coding agent, open a repository, and ask:
Initialize this repository's OpenWiki from the current source and tests.
Your agent researches the repository and writes a linked wiki in openwiki/. OpenWiki tracks its source evidence and saves progress as each page completes.
Once your wiki is ready, ask questions, link related repositories, or explore it visually.
Installation scope, host-specific paths, and removalAll 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:
~/.config/opencode.~/.agents/skills and ~/.bob/settings/mcp.json at user scope; .agents/skills and .bob/mcp.json at the project.~/.kiro/skills and ~/.kiro/settings/mcp.json.~/.omp/agent at user scope (the default profile). Use --project for named profiles or a relocated PI_CODING_AGENT_DIR.~/.gemini/antigravity-cli/skills and ~/.gemini/config/mcp_config.json.~/.copilot/skills and ~/.copilot/mcp-config.json at user scope; .github/skills and .github/mcp.json at the project.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.
Ask your agent to look up a question in the wiki:
Search this repository's OpenWiki for how retry handling works, then read the
relevant sections.
openwiki_search finds compact, ranked results; openwiki_read retrieves the complete sections your agent selects. Agents are guided to use retrieval for concrete questions, read relevant sections, and stop once grounded. It is optional context, not a routine step at the start of every task.
These tools are local, read-only, and model-free: they do not start a generation run or make their own model calls. openwiki_list_workspaces and openwiki_list_wikis provide discovery when repositories are linked.
A service often spans several repositories: a control plane, a data plane, and infrastructure. Use openwiki link to group their existing wikis into a named workspace. Your agent can then search across the whole service and read relevant sections from any member wiki.
Start the workspace manager from a directory such as ~/dev:
cd ~/dev openwiki link
Create a workspace such as Payments, then select the repositories to include. They keep their own wikis, can belong to more than one workspace, and do not need to share a parent directory.
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:
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.
Turn any wiki into an interactive node graph with a live, side-by-side Markdown reader:
openwiki visualize
The graph updates as you edit your wiki.
Local server options and publishing a static visualizerThis 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.
After changing your code, ask your coding agent:
Update this repository's OpenWiki for changes since its last successful run.
OpenWiki checks repository changes and the evidence behind existing Claims to decide what needs updating. Clean updates skip model work and leave the wiki content untouched.
Keep it current automatically by adding a scheduled CI job that opens a docs PR whenever the wiki changes:
openwiki-update.yml into .github/workflows/openwiki-update.yml.openwiki-update-auto-merge.yml instead, then follow the setup details below.openwiki-update.gitlab-ci.yml into .gitlab-ci.yml or include it from your pipeline.openwiki-update.bitbucket-pipelines.yml into bitbucket-pipelines.yml, then schedule the openwiki-update pipeline.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:
OPENWIKI_PR_TOKEN Actions secret..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.
You can also use OpenWiki's own Deep Agents documentation agent, including for scheduled runs and personal wikis. After installing the CLI, initialize a repository wiki:
openwiki --init
The first run walks you through choosing a provider, credentials, and model, then writes docs to openwiki/. OpenWiki supports fourteen model providers, including hosted models and local OpenAI-compatible endpoints.
Update an existing wiki from repository changes since its last successful run and any stale Claims:
openwiki --update
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.
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.
Native repository init and update runs can document several pages at once:
OPENWIKI_PAGE_CONCURRENCY=4 openwiki --update
Concurrency defaults to 1 and accepts values from 1 to 8. Start at 2 to 4 and watch your provider's rate limits. Coding-agent integrations use their host's sequential page lifecycle; this setting controls the native CLI's workers.
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.
Your wiki stays in the repository as plain Markdown you own, with OpenWiki-managed grounding and run metadata versioned alongside it.
code run, OpenWiki maintains an AGENTS.md at the repo root, and refreshes CLAUDE.md when the repository already has one. Claude Code reads AGENTS.md when no CLAUDE.md exists, so OpenWiki does not create one. Their managed instructions use selective, progressive openwiki_search/openwiki_read retrieval for concrete questions when available and use openwiki/quickstart.md as the fallback. OpenWiki only rewrites its own <!-- OPENWIKI:START -->…<!-- OPENWIKI:END --> block and leaves the rest of each file untouched.openwiki/.claims/ travel with the Markdown, so the evidence needed to maintain factual pages is inspectable and reviewable.openwiki/INSTRUCTIONS.md, a user-authored file OpenWiki reads for scope and priorities but never rewrites during normal runs..last-update.json to record that the check ran.~/.openwiki/.env on your machine.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:
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.
OpenWiki separates repository research and writing from the bookkeeping that keeps a wiki consistent. Repository pages carry their source evidence, and completed work is saved for future updates.
Repository generation follows an ordered queue of independently durable page jobs. Native CLI runs can process eligible pages concurrently; coding-agent integrations consume the queue sequentially. openwiki/.run.json checkpoints the active run and its progress. A page advances only after its Markdown, Claims, verification, and openwiki/.page-manifest.json entry are durable, preserving completed work and page-specific source baselines across interruptions and future runs.
OpenWiki tracks the facts behind each repository page as Grounded Claims. Each Claim points to versioned source evidence, such as repo://src/server.ts#L40-L82. When that evidence changes or disappears, OpenWiki identifies which facts need to be confirmed, rewritten, or retired.
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.
Grounded Claims currently apply to repository code wikis and repository evidence. Connector-derived facts, including LangSmith-only observations, are not claimed.
OpenWiki emits Google Open Knowledge Format (OKF) v0.2 bundles in both modes, so your wiki is portable to any OKF-aware tool.
Front matter, provenance, and verification metadatatype; all other standard fields are optional.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.sources; OpenWiki reconciles its deterministically identified entries while preserving independently authored sources.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.sources, verified, status, stale_after) are validated when present.index.md and log.md are reserved documents rather than concepts. The root index declares okf_version: "0.2".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:
npm install mermaid jsdom
Beyond repository docs, OpenWiki has nine built-in connectors. 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.
Start a personal wiki with openwiki personal --init, then authenticate and ingest sources as needed:
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
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>.
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:
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.
These settings apply when running OpenWiki directly. Coding-agent integrations use the host's authenticated model session.
OpenWiki supports fourteen providers. The onboarding default is OpenAI with gpt-5.6-terra. Choose from preset models where available or supply a custom model ID. Provider credentials are stored in ~/.openwiki/.env.
| Provider | Credential |
|---|---|
| OpenAI (default) | OPENAI_API_KEY |
| OpenAI (ChatGPT login) | Browser sign-in, uses your ChatGPT plan |
| Anthropic | ANTHROPIC_API_KEY |
| IBM Bob | BOB_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 |
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.
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.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