Skip to main content
Personal mode builds a local personal brain wiki in ~/.openwiki/wiki from configured sources such as local repositories, Gmail, Notion, web search, Hacker News, Slack, and X/Twitter.

​
First-run onboarding

On first setup, you can:
  • Configure an inference provider, API key, and model
  • Set a LangSmith API key
  • Set up connectors for supported sources
  • Choose a wiki template, customize its scope, and save per-source ingestion notes and schedules
A schedule is an optional cron for a connector source, such as refreshing Gmail or web search on a recurring interval. OpenWiki stores those cron expressions and related setup details in ~/.openwiki/onboarding.json with the rest of onboarding preferences (selected template, connected sources, and per-source ingestion notes). Global personal wiki instructions are saved separately in ~/.openwiki/INSTRUCTIONS.md. On macOS, OpenWiki can install supported schedules as user LaunchAgents under ~/Library/LaunchAgents/. Those jobs run openwiki --update --print and write logs under ~/.openwiki/logs/.

​
Connect your sources

In personal mode, OpenWiki ingests knowledge from the tools you already use and synthesizes it into your local wiki under ~/.openwiki/wiki/. First-run onboarding can set up local git repositories, Notion, Gmail, X/Twitter, web search, Hacker News, and Slack. During an ingestion run, connector tools write raw data and manifests under ~/.openwiki/connectors/<connector>/raw/, then source-specific agent runs update the wiki from those local files. Connector secrets are referenced by env var name and stored in ~/.openwiki/.env.

​
Built-in sources

You can configure the same source more than once. For example, add one web search source for AI research and another for NBA news. OpenWiki stores them as separate instances such as web-search-1 and web-search-2.

​
Connect a source

For sources that need credentials, authenticate first, then ingest. Sources such as Hacker News need no auth; web search needs TAVILY_API_KEY in ~/.openwiki/.env.

Authenticate the provider

Run a local browser OAuth flow for providers that require it. OpenWiki saves returned tokens to ~/.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 ~/.openwiki/.env
  • Notion uses dynamic client registration for hosted MCP
  • X uses OAuth 2.0 with PKCE
  • After openwiki auth gmail, the Google connector can ingest Gmail directly with no MCP transport setup
Advanced retry helpers:

Ingest the source

Pull raw data into ~/.openwiki/connectors/ and synthesize updates into the personal wiki:
You can also refresh from chat or with openwiki personal --update after sources are configured.

​
Slack OAuth

Slack OAuth can require an HTTPS redirect URL:
OpenWiki saves OPENWIKI_HTTPS_OAUTH_REDIRECT_URI and prints the callback URL to register in Slack. X/Twitter and Gmail auth ignore that HTTPS override and keep using the local callback at http://127.0.0.1:53682/callback by default.

​
Credential storage

OpenWiki stores secrets under:
  • Directory: ~/.openwiki (mode 0o700)
  • File: ~/.openwiki/.env (mode 0o600)
Common connector-related keys include Gmail, Notion, Slack, and X OAuth tokens, plus TAVILY_API_KEY for web search. Optional OAuth callback settings:
  • OPENWIKI_OAUTH_CALLBACK_PORT: local callback port
  • OPENWIKI_HTTPS_OAUTH_REDIRECT_URI: Slack HTTPS callback URL
For model provider credentials, see Model providers.

​
Manage schedules

On macOS, manage the connector schedules with:
cron delete removes the saved schedule for a source from ~/.openwiki/onboarding.json and unloads its LaunchAgent. It does not remove auth, connector config, raw data, or wiki content.

​
See also

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.