What OpenKnowledge writes to your system

Installing and launching the app

The macOS app ships as a signed .dmg you drag into /Applications. On launch it writes app-level state and logs, and — because a .dmg app can't put a CLI on your PATH on its own — first launch asks, in one dialog, whether to register the MCP server with your AI editors and whether to add ok to your shell's PATH (both covered below, both with your consent).

The app registers the openknowledge:// URL scheme (for deep links) and checks for updates — on launch and periodically while it runs — against the OpenKnowledge update service at openknowledge.ai/updates, which redirects to the GitHub release asset and counts the update per version and channel (falling back to GitHub directly if it's unreachable). An update on your channel downloads in the background and installs on the next quit; you can also check on demand from Check for updates… in the app and Help menus. The channel (stable or beta) is fixed by the build you installed — switch by reinstalling the other from openknowledge.ai/download/stable or /download/beta. Override the feed with OK_UPDATER_FEED_URL.

On its first launch the app also opens your default browser once to openknowledge.ai/continue, to check whether you installed from a share link and redeem it if so; the exchange completes over a short-lived local loopback listener.

Shell and PATH

So ok can work in your terminal too, the packaged app manages a PATH shim. This is macOS-only, packaged-build-only, and disabled by OK_RECLAIM_DISABLE=1. It never uses sudo, never runs an admin prompt, and never installs a login item.

The first two rows below live in OpenKnowledge's own ~/.ok/ directory and are maintained automatically. The third — the only write into files OpenKnowledge doesn't own — happens only with your consent: the first-launch dialog has an "Add the ok command to your terminal" toggle (checked by default), and nothing is written to your shell config if you uncheck it.

If you decline, only ok typed in an external terminal (Terminal, iTerm) is affected — the app's built-in terminal, the MCP server, and the "Open with AI" launches all work without it. You can add it later from File → Set up OpenKnowledge integrations…. Machines that already had the block from a version before the consent dialog are treated as consented: the block is left in place and maintained.

The managed block is clearly fenced so you can see and remove it:

# >>> open-knowledge cli >>>
# ! Contents within this block are managed by OpenKnowledge. Do not edit.
# ! Delete this whole block to opt out — OpenKnowledge will not re-add it.
[ -f "$HOME/.ok/env.sh" ] && . "$HOME/.ok/env.sh"
# <<< open-knowledge cli <<<

Delete the block and the app won't re-add it — the removal is recorded and respected. Or set OK_RECLAIM_DISABLE=1 to disable all of this before first launch.

User-global Agent Skills

OpenKnowledge ships two user-global Agent Skills — open-knowledge-discovery (helps your coding agent recognize and route through OpenKnowledge projects) and open-knowledge-write-skill (a workflow for authoring new skills). They install into each detected editor's global skill folder (~/.claude/skills/, ~/.cursor/skills/, ~/.codex/skills/, ~/.opencode/skills/) plus the shared ~/.agents/skills/ hub.

These are consent-gated, one checkbox per skill in the same first-launch dialog (both checked by default). Uncheck one and it is never installed; uncheck an already-installed one and its copies are removed. The choice is recorded in ~/.ok/skill-state.yml and honored by every install path — the desktop app, ok init, and ok start — so a skill you declined is never re-added. Machines that already had the skills before the consent dialog are treated as consented (left in place). Re-enable later from File → Set up OpenKnowledge integrations….

Setting up a project

When you initialize or open a project, the app scaffolds the same project files the CLI's ok init creates, and registers the open-knowledge MCP server with the AI editors it detects. The MCP registration is surgical — it adds only its own entry and leaves your other settings, comments, and formatting byte-for-byte intact.

While a project is open

The app runs a collaboration server for the open project. It writes runtime state, gitignored under .ok/local/, plus a shadow git repo that powers the timeline and recovery features:

Diagnostic logs and telemetry are on by default but local-only — credential-bearing attributes are redacted ([REDACTED]) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run ok diagnose bundle. Turn the local sink off with telemetry.localSink.enabled: false; see Configuration.

On each launch and project open, the app also runs repair sweeps: it rewrites existing open-knowledge MCP entries (in the editor configs above) to the current canonical form, and seeds the built-in OpenKnowledge skill bundles (open-knowledge-discovery and open-knowledge-write-skill, in ~/.agents/skills/ and each detected editor's ~/.claude/skills/, ~/.cursor/skills/, ~/.codex/skills/, ~/.opencode/skills/) only when they are missing — an existing copy is left untouched (updates to a built-in flow through the skills.sh "update available" path, never a force-refresh). It also removes any stale open-knowledge-ui entry left in .claude/launch.json by an older OK version. It never adds an MCP entry to an editor that doesn't already have one. Same OK_RECLAIM_DISABLE=1 opt-out.

Home directory and credentials (~/.ok/)

Auth tokens (for GitHub sync, sharing, and cloning) are stored in the macOS Keychain under the service name open-knowledge. The ~/.ok/auth.yml file is only a fallback for headless environments where the Keychain isn't reachable; when the Keychain becomes available, the token is migrated into it and the file copy is removed.

The Install for Claude Chat & Cowork command (command palette or Help menu) builds ~/Downloads/openknowledge.skill on demand and hands it to Claude Desktop for upload; the build is version-gated via ~/.ok/skill-state.yml.

Installing the package

Installing @inkeep/open-knowledge from npm (or invoking it with npx) drops the two CLI binaries plus a bundled native addon. Nothing is written to your home directory at install time — no lifecycle scripts run, and no skills are registered until you run ok init.

ok init

ok init turns a folder into an OpenKnowledge project. It scaffolds the project's .ok/ directory, and — unless you pass --no-mcp — registers the open-knowledge MCP server with the AI editors it detects. The MCP registration is surgical: it adds only its own entry and leaves your other settings, comments, and formatting byte-for-byte intact (if a config can't be parsed safely, it's left untouched and reported).

With --scope user or both (the default), ok init also registers the open-knowledge MCP server in each detected editor's user-level config, so it's available in every project:

ok init also installs the user-global discovery skill — a short instruction file that teaches an agent host how to find and initialize OpenKnowledge — so it is available in every project. It is written only into the skills directories of agent hosts already present in your home directory, plus the shared ~/.agents/skills/ hub those hosts read. If none of them is present, nothing is written at all.

The install is non-fatal (ok init still exits 0 if it fails), version-gated (a no-op when the current version is already installed), and needs no network access. Skip it for one run with ok init --no-skills, or choose individual bundles with --skills <ids>. Skipping records nothing and removes nothing, so skills already on the machine are left alone. An installed bundle is remembered in ~/.ok/skill-state.yml and honored by every later install path; to turn the built-in skills off for good, use the first-launch prompt or the Settings toggle, which record a durable machine-wide choice. ok repair-skills re-runs it.

Pi is the exception: it has no user-level MCP config (it has no MCP support at all), so its integration is only ever the project-scoped bridge extension above.

On Windows, Claude Desktop and OpenCode configs live under %APPDATA%\Claude\ and %APPDATA%\opencode\, and the MCP entry is a PowerShell launcher.

ok init also installs the two user-global skills (open-knowledge-discovery and open-knowledge-write-skill), honoring any prior consent choice, and, if you choose local-only sharing, adds the OpenKnowledge paths to .git/info/exclude so .ok/ stays off your remote. Switch modes later with ok config-sharing share / unshare (unshare refuses if an OK config file is already tracked); ok config-sharing status prints the current mode and the excluded paths.

ok start

ok start runs the collaboration server. Most of what it writes stays inside your project, gitignored under .ok/local/, plus a shadow git repo for the timeline and recovery features:

Diagnostic logs and telemetry are on by default but local-only — credential-bearing attributes are redacted ([REDACTED]) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run ok diagnose bundle. Turn the local sink off with telemetry.localSink.enabled: false; see Configuration.

On each boot, ok start also runs repair sweeps: it re-checks a few things that drift as OpenKnowledge updates and rewrites any that have fallen out of the current canonical form — a no-op when nothing has changed, and it never adds an entry that isn't already there.

Disable all three with OK_RECLAIM_DISABLE=1.

ok mcp

ok mcp is the stdio bridge your editor spawns to talk to the server. It writes nothing to disk — it routes tool calls to a running ok start backend (starting one on the first tool call that needs it — reads included).

Home directory and credentials (~/.ok/)

Auth tokens (for GitHub sync, sharing, and cloning) are stored in your operating system's secure credential store when one is available — the macOS Keychain (service open-knowledge), or the platform equivalent (Windows Credential Manager, Linux Secret Service) — falling back to a 0600 ~/.ok/auth.yml file on headless systems (a Linux server, CI) where none is reachable.