What OpenKnowledge writes to your system

OpenKnowledge keeps your knowledge base as plain markdown in your own project directory, but the tooling around it — the CLI, the MCP server, and the desktop app — also writes a handful of supporting files, some of them outside the project, in your home directory, your shell startup files, your editors' configs, and the macOS Keychain.

This page lists every one of them: when each write happens, what it is, and where it lands. Everything here is verified against the source.

How to read this page

Writes fall into two buckets, and each table's Scope column tells you which:

• In-project — inside your project folder. Either committed (shared through git with your team) or gitignored (this machine only, under .ok/local/ or .git/).
• Outside-project — your home directory (~/.ok/, ~/Library/...), your shell startup files (~/.zshrc and friends), your editors' user-level configs, or the macOS Keychain.

There are five moments OpenKnowledge writes to disk: installing the package, ok init, ok start, ok mcp, and the desktop app. Jump to the opt-outs if that's all you need.

When you install the package

Installing @inkeep/open-knowledge from npm (or invoking it with npx) drops the two CLI binaries plus a bundled native addon, and runs a postinstall step that registers a small "discovery" skill so the AI editors on your machine know OpenKnowledge exists.

The postinstall step is non-fatal (install always succeeds even if it fails) and version-gated (it does nothing if the current version is already installed). It writes only the discovery skill into the shared ~/.agents/skills/ directory; it does not touch your editors' individual skill folders. The only network access is npm fetching the skills helper.

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).

In-project (this project)

Outside-project (user-level editor configs)

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 re-runs the user-global skill install (the discovery skill above) and, if you choose local-only sharing, adds the OpenKnowledge paths to .git/info/exclude so .ok/ stays off your remote.

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. It also runs a few repair sweeps on each boot that can touch files outside the project — see below.

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 entirely with telemetry.localSink.enabled: false; see Configuration.

Repair sweeps

On each boot, ok start also 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. These sweeps only update entries that already exist; they never add one where there wasn't one.

These are the same sweeps the desktop app runs. 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 write).

OK Desktop (macOS app)

The packaged macOS app writes some app-level state and logs, and — because a .dmg app can't put a CLI on your PATH on its own — it manages a PATH shim and shell startup entries so ok works in your terminal too. All of the shell and PATH behavior below 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.

App data, logs, and updates

The app registers the openknowledge:// URL scheme (for deep links) and checks for updates against the OpenKnowledge GitHub releases feed. Updates are not downloaded automatically until you choose to update; they install on the next quit. Override the feed with OK_UPDATER_FEED_URL.

Shell and PATH

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

# >>> open-knowledge cli >>>
[ -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.

Keeping MCP entries current

On each launch (and on each project open), the app runs the same repair sweeps as ok start — rewriting existing open-knowledge MCP entries, .claude/launch.json, and skill files to the current canonical form, and never adding an entry to an editor that doesn't already have one. On a project open it also rewrites an existing open-knowledge entry in that project's .vscode/settings.json. This keeps a working setup from drifting as the app updates, and is covered by the same first-launch consent and the OK_RECLAIM_DISABLE=1 opt-out.

Your home directory and credentials (~/.ok/)

Pulling the home-directory writes together — this is everything that can live under ~/.ok/, across all of the above:

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.

Opt-outs in one place

To review or reverse the footprint after the fact, ok diagnose reports what's on disk, and the desktop path-install.json records exactly which shell/PATH changes were made.

What leaves your machine

By default, nothing. Everything above is written to your own disk. The only ways data leaves your machine are these — all opt-in or on-demand, except the desktop app's update check, which is automatic:

Local diagnostic logs and telemetry are scrubbed of credential-bearing attributes and never sent anywhere on their own.

See also