What OpenKnowledge writes to your system

Installing and launching the app

How the app lands depends on your platform:

• macOS — a signed .dmg you drag into /Applications. 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).
• Windows — a per-user installer: the app lands under %LOCALAPPDATA%\Programs\, with no admin prompt. The installer itself adds the bundled ok CLI to your user PATH (a registry value under HKCU\Environment) and registers the openknowledge:// URL scheme under HKCU\Software\Classes — both removed by its uninstaller. It also registers OpenKnowledge for .md and .mdx files under HKCU\Software\Classes, which can make it the default opener when you have not explicitly chosen one in Windows. Uninstall removes its Open With and file-handler registrations but does not restore a previous file-type default. To choose another opener, use Settings → Apps → Default apps. Your shell startup files are never touched.
• Linux — a deb or rpm package: the app installs to /opt/OpenKnowledge/, and the package's post-install script symlinks /usr/bin/ok, /usr/bin/open-knowledge, and /usr/bin/openknowledge (plus a desktop entry that registers the openknowledge:// scheme, and an AppArmor profile on Ubuntu 24.04+ so the Chromium sandbox keeps working). Your shell startup files are touched only with your consent, as described below.

On every platform the app writes app-level state and logs on launch. The table below shows the macOS locations; on Windows the same app-state files live under %APPDATA%\OpenKnowledge\ and staged updates under %LOCALAPPDATA%\@inkeepopen-knowledge-desktop-updater\. On Linux, app state defaults to ~/.config/OpenKnowledge/ and staged updates to ~/.cache/@inkeepopen-knowledge-desktop-updater/ (or the corresponding XDG config and cache directories). The ~/.ok/ paths are the same everywhere.

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). On macOS and Windows an update on your channel downloads in the background and installs on the next quit; on Linux — where there is no apt/rpm repository — the app downloads the new deb/rpm from the release feed and asks you to authorize the install (a pkexec password prompt) each time. 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. Reinstall a stable build for any supported platform from openknowledge.ai/download. The /download/beta shortcut serves the latest Apple Silicon macOS beta; Windows and Linux beta installers are available from GitHub Releases. 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 and Linux 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. (Windows doesn't need it: the Windows installer adds the bundled CLI to your user PATH itself, and never edits your shell files. OpenKnowledge no longer ships a Linux AppImage, but a build launched from one skips the shim too, because an AppImage has no fixed install location to link to.)

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/, ~/.lmstudio/skills/) plus the shared ~/.agents/skills/ hub.

Only open-knowledge-discovery is set up at first launch — it is what lets an agent recognize an OpenKnowledge project at all, so it comes with the MCP wiring. open-knowledge-write-skill is an authoring convenience with no bearing on whether your tools work, so setup neither installs it nor records a decision about it; it is offered the first time you open Settings → Skills Studio, and remains installable there afterwards.

Both are consent-gated, but at different moments. Declining open-knowledge-discovery at first launch means it is never installed. open-knowledge-write-skill has no first-launch step at all, so nothing is decided about it until you install it from Skills Studio — there is no option to decline it during setup, because setup never asks. Uninstalling either one removes its copies. 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, and a skill nobody has been asked about is never installed behind your back. Machines that already had the skills before the consent dialog are treated as consented (left in place).

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 touches only its own entry and leaves your other settings, comments, and formatting byte-for-byte intact. "Its own entry" means the one named open-knowledge; if that name is already taken by something OpenKnowledge does not recognize, see Opt-outs in one place.

The Scope column assumes you share this setup with your team. New projects don't: they keep OpenKnowledge's config to yourself, adding every in-project path above to .git/info/exclude, so those files are written but stay out of git.

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

Skills are never installed by a sweep. OpenKnowledge writes a skill into editor folders only when you ask for one — the first-launch setup dialog, the Settings toggles, Skills Studio, or ok init. A launch does two housekeeping passes over installed editor skills and writes nothing new into those folders: it removes superseded pre-split open-knowledge copies OpenKnowledge itself left in your agent folders, and it removes a bundle you switched off that is still on disk.

Home directory and credentials (~/.ok/)

Auth tokens (for GitHub sync, sharing, and cloning) are stored in your OS credential store under the service name open-knowledge — the Keychain on macOS, Credential Manager on Windows, and the Secret Service keyring (libsecret) on Linux. The ~/.ok/auth.yml file is only a fallback for headless environments where the credential store isn't reachable; when it 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 touches only the entry named open-knowledge and leaves your other settings, comments, and formatting byte-for-byte intact (if a config cannot be read or updated safely, it is left untouched and the reason is reported; follow that reason when repairing permissions, the path, or syntax. If it reports no format-preserving writer available, reinstall OpenKnowledge to restore its TOML writer or configure the integration manually).

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, decline at the first-launch prompt or uninstall from Settings → Skills Studio, either of which records a durable machine-wide choice. ok repair-skills re-runs it.

Pi has no user-level MCP config. ok init writes its project-scoped bridge extension; using Pi inside OpenKnowledge can also add a folder trust grant, whose location respects PI_CODING_AGENT_DIR.

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 open-knowledge-discovery (the same skill first launch sets up — pass --skills discovery,write-skill to add the authoring skill too), honoring any prior consent choice, and, for a project it is setting up for the first time, adds the OpenKnowledge paths to .git/info/exclude so .ok/ stays off your remote. Pass --shared to commit it instead. Re-running ok init on a project you already set up keeps that project's current choice. 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 both repair sweeps with OK_RECLAIM_DISABLE=1. They leave installed editor skills alone; ok repair-skills is the explicit command for those. Starting an in-app agent thread creates or refreshes the runtime skill copy listed above.

Projects initialized by an older CLI may lack the local/ rule in .ok/.gitignore, which leaves these runtime files visible in git status. Add local/ to that file or open the project in the desktop app, which updates it automatically. The runtime skill copy is always excluded from the knowledge base.

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.