# What OpenKnowledge writes to your system (https://openknowledge.ai/docs/reference/what-open-knowledge-writes) Every file OpenKnowledge creates or changes — when, where, in-project vs. your home directory — plus the opt-outs and what leaves your machine (nothing by default). 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 OS credential store. This page lists every one of them: **when** each write happens, **what** it is, and **where** it is written. > **The short version** > > **Nothing about your content leaves your machine by default.** Diagnostic logs and telemetry stay on your machine. The things that *can* send data off it — semantic search, a diagnostic or bug-report bundle, and GitHub sync — are opt-in or on-demand. Three automatic exceptions, none of which touch your documents: the desktop app checks for updates (sending its app version and channel), on its first launch it opens your browser once to check for a pending share link, and installing a **published skill** reports that install to skills.sh so the skill's public install count is accurate — the skill's name and source repository, once per skill (per project, for a skill installed into a project), and never for a private or local source. All of them are listed under [What leaves your machine](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#what-leaves-your-machine), and the skill report can be turned off. ## 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 OS credential store. OpenKnowledge installs one of two ways, and the footprint differs a little between them. Pick yours below — each tab lists the complete set of writes for that path. The [opt-outs](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#opt-outs-in-one-place) and [what leaves your machine](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#what-leaves-your-machine) at the end apply to both. ## Desktop app ### 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. | Path | What it is | Scope | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | | `~/Library/Application Support/OpenKnowledge/state.json` | Recent projects, window/view state, update channel | Outside-project (home dir) | | `~/Library/Application Support/OpenKnowledge/path-install.json` | Records the `PATH`/shell changes it made and your `PATH`-consent choice, so they can be reverted | Outside-project (home dir) | | `~/.ok/logs/desktop..log` | Desktop app + renderer log | Outside-project (home dir) | | `~/.ok/mcp-status.json` | Records your first-launch MCP-setup consent choice | Outside-project (home dir) | | `~/Library/Caches/@inkeepopen-knowledge-desktop-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) | | `~/Library/Caches/com.inkeep.open-knowledge.ShipIt/` | Install log of the macOS update helper (Squirrel's ShipIt), which swaps the app bundle after the app has quit. The only record of why an update failed to install, so a bug report you send collects it — only this app's, never those of other applications that use the same update mechanism | Outside-project (home dir) | | `~/Library/Logs/DiagnosticReports/` | Not written by OpenKnowledge at all — this is macOS's own crash-report directory, shared by every application on the machine. When the OS ends one of this app's processes it records why there, which is sometimes the only account of a session that stopped without a crash dump, so a bug report you send at the **Detailed diagnostics** level collects the reports macOS wrote for this app and its helper processes — only ours, never those of any other application, and never at the standard level. A report of ours still names the processes it was running alongside. A report also carries machine details macOS puts in every one of them — the account uid, the Mac model, and the name of the process that launched the app, which on a managed machine can be internal tooling — while the identifiers that would link your bundles to each other are replaced before bundling. `ok diagnose bundle` collects them too, on every run: that command produces the Detailed superset by design, and its summary tells you what the search found before it writes the zip | Outside-project (home dir) | | `~/Library/Application Support/OpenKnowledge/Crashpad/` | Native crash minidumps, written by the OS crash handler (Electron's Crashpad) if the app ever crashes. Local-only: the crash reporter runs with `uploadToServer: false`, so no dump is ever uploaded automatically | Outside-project (home dir) | | `~/Library/Application Support/OpenKnowledge/bug-report-dirty-shutdown.json` | Dirty-shutdown sentinel — written on **every** launch, refreshed as it runs, and removed on a clean quit. The next launch reads it to tell an app crash (prompts you) from the endings that are not a crash: a reboot, an OS shutdown, or dying asleep (all suppressed and logged instead), an update install shutting the app down to replace its files (logged either way, and suppressed in almost every case: a shutdown the app had no chance to record, or one it cannot date because the previous session left no heartbeat, can still prompt so you are able to report it), and a death the app can date to more than a week ago, which is too stale to report usefully — the diagnostics a report would gather describe the day you sent it rather than the day it happened. A fresh crash dump still overrides those, the same as it does for a reboot, a suspend or an OS shutdown — except in the first 30 seconds after the app committed to quitting for an update install, where a dump is part of that same shutdown rather than a crash you could act on. A session that left neither a heartbeat nor a crash dump cannot be dated, so it is never treated as stale | Outside-project (home dir) | | `~/Library/Application Support/OpenKnowledge/bug-report-crash-acks.json` | Records which crash-report invitations you already answered or dismissed, so the same crash never re-prompts. Answering is what retires a crash: an invitation you simply never saw — because it went unanswered for a day, or the window it was waiting on never appeared — is dropped rather than answered, so that crash can be offered again the next time you open the app | Outside-project (home dir) | | `~/Library/Application Support/OpenKnowledge/bug-report-main-thread-liveness.json` | Main-thread liveness witness. A background worker rewrites it every five seconds while the app runs. The next launch can identify a main-thread block that had lasted at least 15 seconds at the last successful sample. A sample below that threshold does not rule out a shorter or recovered block, or a block after the worker stopped writing. Read only at the next launch; left in place on a clean quit and overwritten on the next run, through a `.tmp-` sibling during each write. The verdict lands in the desktop log a bug report carries; it does not change whether the app prompts you | Outside-project (home dir) | 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](https://github.com/inkeep/open-knowledge/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. | Path | What it is | Scope | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | `~/.ok/bin/ok`, `~/.ok/bin/open-knowledge` | Symlinks to the CLI bundled inside the app | Outside-project (home dir) | | `~/.ok/env.sh` | A managed shim that prepends `~/.ok/bin` to your `PATH` | Outside-project (home dir) | | `~/.zshrc`, `~/.bash_profile`, `~/.bashrc` (Linux), `~/.config/fish/conf.d/open-knowledge.fish` | A **fenced managed block** that sources `~/.ok/env.sh` — written **only if you consent** in the first-launch dialog. The block is created in the startup file for your login shell, and maintained in any of these that already exists, except `~/.bashrc`, which is only ever touched on Linux | Outside-project (shell config) | 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: ```bash # >>> 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](https://openknowledge.ai/docs/features/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](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#opt-outs-in-one-place). | Path | What it is | Scope | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | `.ok/`, `.ok/config.yml` | Project directory and its [config](https://openknowledge.ai/docs/reference/configuration) | In-project, committed | | `.ok/.gitignore` | Keeps machine-local runtime state (`local/`, `principal.json`, `server.lock`, …) out of git | In-project, committed | | `.okignore` | Paths excluded from the editor, search, and agents — see [Ignore patterns](https://openknowledge.ai/docs/features/ignore-patterns) | In-project, committed | | `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration for the four MCP-capable project editors (Claude, Cursor, Codex, OpenCode), written regardless of what's installed so the repo is ready for teammates | In-project, committed | | `.pi/extensions/open-knowledge.ts` | Managed bridge extension connecting [Pi](https://openknowledge.ai/docs/integrations/pi) (which has no MCP support) to the project | In-project, committed | | `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for Claude, Cursor, Codex, GitHub Copilot, OpenCode, and Pi | In-project, committed | | `.ok/skills-lock.json` | Provenance for imported skills — source, selected skill, commit/ref when available, content hash, publisher, and import time | In-project, committed | | `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.copilot/mcp-config.json`, `~/.config/opencode/opencode.json`, `~/.openclaw/openclaw.json`, `~/.gemini/config/mcp_config.json`, `~/.lmstudio/mcp.json`, `~/.hermes/config.yaml` | User-level `open-knowledge` MCP registration, one per detected editor, so it's available in every project (`~/.copilot/mcp-config.json` only when `~/.copilot/` exists; `~/.openclaw/openclaw.json` only when `~/.openclaw/` exists; `~/.gemini/config/mcp_config.json` is Antigravity's shared IDE + `agy` config, only when `~/.gemini/` exists; `~/.lmstudio/mcp.json` and `~/.hermes/config.yaml` only when those apps are installed) | Outside-project (editor config) | 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: | Path | What it is | Scope | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `.ok/local/server.lock` | Advertise the running server's URL and capabilities (the `ui` capability marks a UI-serving server) | In-project, gitignored | | `.ok/local/principal.json` | Your local identity (id, email) for edit attribution | In-project, gitignored | | `.ok/local/sync-state.json` | GitHub-sync engine state | In-project, gitignored | | `.ok/local/conflicts.json` | Every conflict the app is holding a document for, including conflicts that involve no remote. A row for OpenKnowledge's own merge of the editor against disk embeds up to three full copies of the document body, so **keep this file while any conflict is open**. Deleting it loses those copies. If the app cannot read the file, it renames it to `conflicts.json.corrupt-` and leaves it in place | In-project, gitignored | | `.ok/local/stale-external-writes.json` | Recovery snapshot for a rejected stale external save. It can hold the acknowledged, rejected, and retained document text. Protection expires after 30 minutes, but an unresolved snapshot stays until you resolve the conflict | In-project, gitignored | | `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the last detached-spawn error log | In-project, gitignored | | `.ok/local/last-server-exit.json` | Why the collaboration server the app started last exited — a timestamp, its process id, the exit code, the signal that ended it, and which part of the app was watching. One record, overwritten on each exit; a server the app only attached to, or one you started yourself with `ok start`, leaves none. No document content or paths | In-project, gitignored | | `.ok/local/last-server-crash.json` | The collaboration server's own account of a crash it did not survive — a timestamp, the error message and stack, its process id, and how long it had been running. Written by the server itself, so it covers `ok start` too. Holds the most recent crash only | In-project, gitignored | | `.ok/local/telemetry/spans-*.jsonl` | Local diagnostic spans, rotated at \~50 MB | In-project, gitignored | | `.ok/local/logs/server-*.jsonl` | Local server logs, rotated at \~25 MB | In-project, gitignored | | `.ok/local/cache//backlinks.json` | Backlink-graph cache | In-project, gitignored | | `.ok/local/installed-skills.json` | Per-project skill-install markers (which editors each skill is projected into) | In-project, gitignored | | `.ok/local/agent-skill/open-knowledge/` | Runtime copy of the OpenKnowledge project skill (`SKILL.md` and `references/`), refreshed before in-app agent processes start. New in-app agent sessions receive this guidance automatically, even when the skill is not installed into an editor | In-project, gitignored with the `local/` ignore rule | | `.ok/local/skill-move-retained.json` | Bookkeeping for a skill move between Project and Global scope that could not finish: which destination copy was kept, why, and what the source looked like at the time. Keyed by scope and skill name, one record each. A record clears when a later move of that skill completes, when the copy at the destination stops matching the one recorded, or when you delete that skill at that scope. No document content | In-project, gitignored | | `.ok/local/terminal/claude-settings-{mcp,tools,mcp-tools}.json` | Windows-only Claude launch settings written when **Open in Claude** requests MCP or tool preapproval; one of three possible files, overwritten rather than appended on each launch that uses that combination. macOS and Linux pass the same settings inline | In-project, gitignored | | `.ok/local/comments/` | [Comments](https://openknowledge.ai/docs/features/comments) left on documents, one JSON file each — the note, the passage it quotes, and whether it has been sent | In-project, gitignored | | `.ok/worktrees//` | Git worktree checkout created when you open a branch in its own window (project switcher); the path is also added to `.git/info/exclude` | In-project, gitignored | | `.git/ok/` — or `.git/worktrees//ok/` in a linked worktree, or the enclosing repo's `.git/ok-/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs; always inside a git admin dir, never in your content tree. Its own `info/exclude` file, written when OpenKnowledge opens the repo, keeps machine-local runtime state — `.ok/local/` and `.ok/worktrees/`, plus the pre-`.ok/local/` equivalents that older projects still keep at the `.ok/` root (`.ok/principal.json`, `.ok/server.lock`, `.ok/cache/`, …) — and the `.tmp.` files an in-flight atomic write leaves behind out of every saved version, the way `.ok/.gitignore` keeps them out of git | In-project, gitignored (inside `.git/`) | 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](https://openknowledge.ai/docs/reference/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/`) | Path | What it is | Sensitive? | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `~/.ok/global.yml` | User-global [config](https://openknowledge.ai/docs/reference/configuration) (applies to every project) | No | | `~/.ok/secrets.yml` | Embeddings provider API key for [semantic search](https://openknowledge.ai/docs/reference/configuration#semantic-search), if you set one. Written `0600`; never in `config.yml` | **Yes** (`0600`) | | `~/.ok/auth.yml` | Auth-token fallback, used only when the Keychain is unavailable. Written `0600` | **Yes** (`0600`) | | `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No | | `~/.agents/skills//`, `~/.claude/skills//`, … | Your global-scope skills, versioned in place in your home editor dirs (kept by `ok uninstall` unless `--purge-content`) | No | | `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-move-retained.json` | The same skill-install markers and unfinished-scope-move bookkeeping the tables above list under a project's `.ok/local/`, written under your home directory for Global-scope skills instead | No | | `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No | | `~/.ok/themes/` | Your saved color themes from the [Themes plugin](https://openknowledge.ai/docs/plugins/themes), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No | | `~/.ok/mcp-status.json` | First-launch MCP consent record | No | | `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` and the app's **Help → Report a bug…** dialog (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). Each report from the dialog also gets a small YAML record holding its send state and a secret-redacted copy of the note you wrote, so report history can still show what a report was about. The zip is deleted once the report is sent; the record is kept, and both go when you delete the report from report history. If that record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send, so history still shows it as sent instead of offering to send it again | No | | `~/.ok/bin/`, `~/.ok/env.sh` | `PATH` shim (see [Shell and `PATH`](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#shell-and-path) above) | No | **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`. ## CLI ### 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`. | Path | What it is | Scope | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `ok`, `open-knowledge` (on your `PATH`) | The two CLI binaries (identical entry point) | Outside-project (npm global/bin) | | `/dist/native/` | Bundled native addon, shipped inside the package: TOML editing on all platforms, plus a Windows-only reader that checks a running server's process creation time during `ok uninstall` / `ok deinit` | Outside-project (package dir) | > **Opt out** > > Installing the package writes nothing outside its own directory, so there is nothing to opt out of here. The user-global skills are installed by `ok init`, and `ok init --no-skills` skips installing them for that run. ### `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). | Path | What it is | Scope | | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `.ok/`, `.ok/config.yml` | Project directory and its [config](https://openknowledge.ai/docs/reference/configuration) | In-project, committed | | `.ok/.gitignore` | Keeps machine-local runtime state (`local/`, `principal.json`, `server.lock`, …) out of git | In-project, committed | | `.okignore` | Paths excluded from the editor, search, and agents — see [Ignore patterns](https://openknowledge.ai/docs/features/ignore-patterns) | In-project, committed | | `.gitignore` (project root) | Seeded (with `.DS_Store`) **only** when `ok init` creates a new git repo | In-project, committed | | `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, `opencode.json` | Project-scoped MCP registration for the four MCP-capable project editors (Claude, Cursor, Codex, OpenCode) regardless of what's installed — prepares the repo for teammates (with `--scope project` or `both`) | In-project, committed | | `.pi/extensions/open-knowledge.ts` | Managed bridge extension connecting [Pi](https://openknowledge.ai/docs/integrations/pi) (which has no MCP support) to the project | In-project, committed | | `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for Claude, Cursor, Codex, GitHub Copilot, OpenCode, and Pi | In-project, committed | | `.ok/skills-lock.json` | Provenance for imported skills — source, selected skill, commit/ref when available, content hash, publisher, and import time | In-project, committed | 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: | Path | Editor | Scope | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------- | | `~/.claude.json` | Claude Code | Outside-project (editor config) | | `~/Library/Application Support/Claude/claude_desktop_config.json` | Claude Desktop | Outside-project (editor config) | | `~/.cursor/mcp.json` | Cursor | Outside-project (editor config) | | `~/.codex/config.toml` | Codex | Outside-project (editor config) | | `~/.copilot/mcp-config.json` | GitHub Copilot CLI (only when `~/.copilot/` exists; respects `COPILOT_HOME`) | Outside-project (editor config) | | `~/.config/opencode/opencode.json` | OpenCode | Outside-project (editor config) | | `~/.openclaw/openclaw.json` | OpenClaw (only when `~/.openclaw/` exists) | Outside-project (editor config) | | `~/.gemini/config/mcp_config.json` | Antigravity (only when `~/.gemini/` exists) — shared by the IDE and the `agy` CLI | Outside-project (editor config) | | `~/.lmstudio/mcp.json` | LM Studio (only when installed; also checks `~/.cache/lm-studio/mcp.json`) | Outside-project (editor config) | | `~/.hermes/config.yaml` | Hermes (only when `~/.hermes/` exists) | Outside-project (editor config) | `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. | Path | What it is | Scope | | -------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------- | | `~/.agents/skills/open-knowledge-*/` | Shared hub read natively by Codex, OpenCode, and Cursor | Outside-project (home dir) | | `~/.claude/skills/open-knowledge-*/` | Written only when `~/.claude/` already exists | Outside-project (home dir) | | `~/.lmstudio/skills/open-knowledge-*/` | Written only when `~/.lmstudio/` already exists (LM Studio reads these in agent mode) | Outside-project (home dir) | | `~/.cursor/skills/open-knowledge-*/` | Written only when `~/.cursor/` already exists | Outside-project (home dir) | | `~/.codex/skills/open-knowledge-*/` | Written only when `~/.codex/` already exists | Outside-project (home dir) | | `~/.opencode/skills/open-knowledge-*/` | Written only when `~/.opencode/` already exists | Outside-project (home dir) | | `~/.ok/skill-state.yml` | Records which skill version is installed, so the step is skipped next time | Outside-project (home dir) | | `~/.ok/skill-install-events.jsonl` | Append-only local log of skill-install attempts | Outside-project (home dir) | 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 `. 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](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#pi-folder-trust), 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. > **Controlling it** > > - `--no-mcp` — scaffold `.ok/` only; register nothing with any editor. > - `--scope user | project | both` — where the MCP entry is written. In an interactive terminal, `ok init` prompts for this; scripted/CI runs default to `both`, so pass the flag to constrain them. > - `--no-skills` — install no user-global skills on this run; `--skills discovery,write-skill` — install only the named bundles. **Default installs `discovery` only**, matching what the desktop's first launch sets up; `write-skill` is opt-in here and in **Settings → Skills Studio**. Installing is recorded and honored by the desktop app too; skipping is not recorded, so it never affects another project. > - `--shared` (vs `--local-only`) — commit `.ok/` rather than keeping it out of git. ### `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: | Path | What it is | Scope | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `.ok/local/server.lock` | Advertise the running server's URL and capabilities (the `ui` capability marks a UI-serving server) | In-project, gitignored | | `.ok/local/principal.json` | Your local identity (id, email) for edit attribution | In-project, gitignored | | `.ok/local/sync-state.json` | GitHub-sync engine state | In-project, gitignored | | `.ok/local/conflicts.json` | Every conflict the app is holding a document for, including conflicts that involve no remote. A row for OpenKnowledge's own merge of the editor against disk embeds up to three full copies of the document body, so **keep this file while any conflict is open**. Deleting it loses those copies. If the app cannot read the file, it renames it to `conflicts.json.corrupt-` and leaves it in place | In-project, gitignored | | `.ok/local/stale-external-writes.json` | Recovery snapshot for a rejected stale external save. It can hold the acknowledged, rejected, and retained document text. Protection expires after 30 minutes, but an unresolved snapshot stays until you resolve the conflict | In-project, gitignored | | `.ok/local/state.json`, `.ok/local/last-spawn-error.log` | State-schema manifest and the last detached-spawn error log | In-project, gitignored | | `.ok/local/last-server-crash.json` | The server's own account of a crash it did not survive — a timestamp, the error message and stack, its process id, and how long it had been running. Holds the most recent crash only | In-project, gitignored | | `.ok/local/telemetry/spans-*.jsonl` | Local diagnostic spans, rotated at \~50 MB | In-project, gitignored | | `.ok/local/logs/server-*.jsonl` | Local server logs, rotated at \~25 MB | In-project, gitignored | | `.ok/local/cache//backlinks.json` | Backlink-graph cache | In-project, gitignored | | `.ok/local/installed-skills.json` | Per-project skill-install markers (which editors each skill is projected into) | In-project, gitignored | | `.ok/local/agent-skill/open-knowledge/` | Runtime copy of the OpenKnowledge project skill (`SKILL.md` and `references/`), refreshed before in-app agent processes start. New in-app agent sessions receive this guidance automatically, even when the skill is not installed into an editor | In-project, gitignored with the `local/` ignore rule | | `.ok/local/skill-move-retained.json` | Bookkeeping for a skill move between Project and Global scope that could not finish: which destination copy was kept, why, and what the source looked like at the time. Keyed by scope and skill name, one record each. A record clears when a later move of that skill completes, when the copy at the destination stops matching the one recorded, or when you delete that skill at that scope. No document content | In-project, gitignored | | `.ok/local/comments/` | [Comments](https://openknowledge.ai/docs/features/comments) left on documents, one JSON file each — the note, the passage it quotes, and whether it has been sent | In-project, gitignored | | `.git/ok/` — or `.git/worktrees//ok/` in a linked worktree, or the enclosing repo's `.git/ok-/` when your project is a subfolder of a larger repo | Shadow git repo holding per-writer work-in-progress refs (powers the timeline); always inside a git admin dir, never in your content tree. Its own `info/exclude` file, written when OpenKnowledge opens the repo, keeps machine-local runtime state — `.ok/local/` and `.ok/worktrees/`, plus the pre-`.ok/local/` equivalents that older projects still keep at the `.ok/` root (`.ok/principal.json`, `.ok/server.lock`, `.ok/cache/`, …) — and the `.tmp.` files an in-flight atomic write leaves behind out of every saved version, the way `.ok/.gitignore` keeps them out of git | In-project, gitignored (inside `.git/`) | 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](https://openknowledge.ai/docs/reference/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. | What it re-checks | Where | Scope | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | Existing `open-knowledge` MCP entries | The same editor configs `ok init` writes — **both** user-level (`~/.claude.json`, `~/.cursor/mcp.json`, …) and project-level | Outside-project (editor config) **and** in-project | | Stale `open-knowledge-ui` entry in `.claude/launch.json` | Project | Removed if present — OK no longer writes launch.json | 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/`) | Path | What it is | Sensitive? | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `~/.ok/global.yml` | User-global [config](https://openknowledge.ai/docs/reference/configuration) (applies to every project) | No | | `~/.ok/secrets.yml` | Embeddings provider API key for [semantic search](https://openknowledge.ai/docs/reference/configuration#semantic-search), if you set one. Written `0600`; never in `config.yml` | **Yes** (`0600`) | | `~/.ok/auth.yml` | Auth-token fallback, used when no OS credential store is reachable. Written `0600` | **Yes** (`0600`) | | `~/.ok/skill-state.yml`, `~/.ok/skill-install-events.jsonl` | Skill-install bookkeeping | No | | `~/.agents/skills//`, `~/.claude/skills//`, … | Your global-scope skills, versioned in place in your home editor dirs (kept by `ok uninstall` unless `--purge-content`) | No | | `~/.ok/local/installed-skills.json`, `~/.ok/local/skill-move-retained.json` | The same skill-install markers and unfinished-scope-move bookkeeping the tables above list under a project's `.ok/local/`, written under your home directory for Global-scope skills instead | No | | `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No | | `~/.ok/themes/` | Your saved color themes from the [Themes plugin](https://openknowledge.ai/docs/plugins/themes), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No | | `~/.ok/logs/` | CLI logs (`cli..log`), size- and age-capped | No | | `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` — the desktop app's **Help → Report a bug…** dialog writes here too (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). A report filed from the dialog also leaves a small YAML record beside its bundle, holding the report's send state and a secret-redacted copy of the note you wrote so report history can name it. That record outlives the bundle: the zip is deleted once the report is sent, and the record is kept until you delete the report from report history. If the record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send. That marker holds only the send time and the report's reference, never your note, and it is removed with the rest of the report | No | **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. ## Versions saved before the shadow exclusions The shadow repo's `info/exclude` is forward-only. Versions saved by an earlier OpenKnowledge build, and the work-in-progress commits folded into them, still carry the machine-local paths in their trees: the contents of `.ok/local/`, including `principal.json` and `server.lock`, and the caches and logs beside them. A project that predates `.ok/local/` carries the same runtime state at the `.ok/` root instead — `.ok/principal.json`, `.ok/state.json`, `.ok/server.lock`, `.ok/ui.lock`, `.ok/sync-state.json`, `.ok/conflicts.json` and `.ok/last-spawn-error.log`, alongside `.ok/cache/` and `.ok/tmp/`. Opening the project on a current build drops those paths from the shadow repo's staging index and stops adding them to new versions; it does not rewrite the versions already written, and those older commits stay reachable from the versions that folded them. All of it stays in the shadow git repo inside your own `.git/` directory, which OpenKnowledge never pushes anywhere. A version you saved yourself is kept rather than expired, so this does not age out on its own. `ok deinit` removes the shadow repo along with the rest of a project's OpenKnowledge state. ## Pi folder trust When you use Pi inside OpenKnowledge and accept its bridge setup prompt, OpenKnowledge also grants Pi trust in the project folder. This applies to both the desktop app and the web app served by `ok start`; `ok init` writes the project bridge without adding this trust grant. | Path | What it is | Scope | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | `~/.pi/agent/trust.json` (or `$PI_CODING_AGENT_DIR/trust.json`) | Pi's trust store. Bridge setup can add an exact-folder trust decision so Pi can load the OpenKnowledge bridge | In-project or Outside-project (follows the trust destination) | | `~/.ok/pi-trust/` | Records the previous decision and trust-store path when OpenKnowledge changes a folder's trust. An interrupted, unconfirmed change is not treated as proven ownership | Outside-project (home dir) | | `.lock` | Temporary directory lock shared with Pi while accessing its trust store | In-project or Outside-project (follows the configured Pi directory) | | `.ok.lock` | Temporary OpenKnowledge lock coordinating access through different symlinks. For a linked trust file, this sits beside its destination | In-project or Outside-project (follows the trust destination) | Pi's directory lock coordinates with Pi itself at the configured path. The separate OpenKnowledge lock uses the resolved destination so OpenKnowledge processes using different symlinks also coordinate. Pi's store and locks normally live outside the project; a custom configuration or symlink can place them inside it. New Pi trust checks, grants, and ownership records use the real project directory, even when the project was opened through a symlink. The setup prompt shows that directory; if the symlink points elsewhere when setup begins, OpenKnowledge refuses the change and asks you to reopen the intended project and approve it again. OpenKnowledge also refuses a project path it cannot resolve or access, instead of falling back to an unverified spelling. `ok deinit`, project cleanup selected during `ok uninstall`, and removing the Pi connection in Settings reverse recorded OpenKnowledge trust changes when the current exact-folder value still matches the recorded grant and no other Pi resources need it. Cleanup restores the previous exact-folder decision, or removes the entry if none existed. Other projects' entries, parent-folder decisions, and Pi's global trust default are preserved; a folder may still be trusted through those settings. Every Pi trust grant made before ownership recording was introduced lacks a record and is preserved, including grants made by OpenKnowledge. There is no automatic backfill. Older entries under a non-canonical project spelling, such as a symlink path, are also preserved and named when found. Pi does not use those literal keys, and cleanup does not move them to the real-path key. An interrupted setup can leave a pending record that does not prove the trust write completed; setup and cleanup do not reconcile it while the folder remains trusted. To remove an unrecorded or non-canonical grant manually, close Pi and remove only the project's exact-folder key from its `trust.json`, leaving the other entries intact. The cleanup message names an entry's exact key and file when it can inspect that entry. If the project path is already unavailable when cleanup starts and ownership records can be read, cleanup names those records and their recorded locations without checking current trust decisions. If a later project-path check fails, the affected trust store is left pending with guidance to repair the path and retry. For manual cleanup using a record, inspect the intended destination and restore the recorded previous decision only if you choose to undo a current true entry, removing that key only when there was no previous entry. Parent-folder and global trust settings can still apply; see [Pi's project trust rules](https://pi.dev/docs/latest/security#project-trust). Trust is also kept when other project resources need it, including Pi settings, extensions, skills, prompts, themes, system prompts, and inherited project skills. Cleanup lists up to three of those resources, reports how many more remain, and relinquishes its ownership record where one exists: later cleanup runs will not revoke that grant even if those resources are removed. Manage the retained decision in Pi or remove the exact-folder key manually as described above. Removing the grant may stop Pi from loading those resources. OpenKnowledge's own skill namespace is managed separately in the current project; ancestor skill roots remain outside that project's cleanup and can still require trust. Bridge setup requires a project directory it can resolve and access, and refuses unreadable trust files or broken or cyclic trust-file symlinks. Cleanup reports a failure if a project path or required trust check cannot be verified, retains retry information, and tells you what to repair. For a missing project, cleanup checks for ownership records under both the supplied path and the missing path appended to its nearest resolvable, accessible ancestor's real path. Healthy directory aliases are followed for this additional record lookup only; it cannot recover a deleted symlink's former target or an ancestor's historical target. With no bridge or record at either checked path, cleanup treats the project as already absent. A record at either path, or an ancestor that cannot be resolved or accessed, requires repairing the project path before retrying. With neither a bridge nor a record and a verifiable project path, cleanup treats the trust store as unrelated and does not inspect it. `PI_CODING_AGENT_DIR` changes the trust-store directory; it does not relocate the project's `.pi/extensions/open-knowledge.ts` bridge. When a bridge or record requires trust cleanup, OpenKnowledge checks the currently configured store as well as saved locations for recorded grants, even if the environment setting has changed. It reports retained exact keys it finds, including the supplied project spelling when it differs from the real path. It does not search arbitrary Pi directories or infer unknown historical aliases for older, unrecorded entries. ## Opt-outs in one place | To skip… | Do this | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | The `postinstall` skill install (CLI) | `npm install --ignore-scripts` | | The shell-config `PATH` block (macOS and Linux app) | Uncheck "Add the `ok` command to your terminal" in the first-launch dialog | | All editor MCP registration in `ok init` | `ok init --no-mcp` | | User-level (vs project) MCP writes | `ok init --scope project` | | Committing `.ok/` to git | Off by default for a new project; `ok init --shared` commits it instead | | The repair sweeps and the desktop app's shell / `PATH` changes | `OK_RECLAIM_DISABLE=1` (also delete the managed block from your shell config to remove the `PATH` entry) | | Local diagnostic logs and telemetry | `telemetry.localSink.enabled: false` in config | | Auto-starting the MCP server | `OK_MCP_AUTOSTART=0` | To review 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). To reverse it, `ok deinit` removes OpenKnowledge from one project and `ok uninstall` removes the global footprint, with optional project cleanup. Both keep your markdown and authored skills by default; OpenKnowledge's bundled skills are removed. Shared configs and their symlinks are preserved, and incomplete cleanup reports a failure while retaining state needed to retry. Both commands take `--dry-run` to preview. See the [CLI reference](https://openknowledge.ai/docs/reference/cli#remove-openknowledge) for project selection and scripting behavior. In the desktop app you don't need the CLI for finer control, and the split follows what each thing is. **Settings → Agent connections** lists every agent OpenKnowledge can wire up, grouped by how you reach it — In app, Terminal, External apps. Each row says whether OpenKnowledge can reach that agent's tools and offers the action that fits: **Add MCP & skill** when nothing is set up, **Manage** when something is, and **Remove** when the tool itself is present but you have turned it off. A tool that is not on this machine always leads with **Install**, or **How to set up** when OpenKnowledge has no download link for it; neither writes anything. When OpenKnowledge files are still on disk for a tool that is not on this machine, the row keeps whichever of **Install** or **How to set up** it already had, and adds a muted **Remove** link beside the hint — `Not installed · OpenKnowledge files present`, or `Not detected on this machine · OpenKnowledge files present` for a tool OpenKnowledge cannot launch directly. Where one tool has two rows — a CLI and its editor, sharing a single setup — that hint and link appear only when OpenKnowledge can confirm the other row's tool is also absent, so the row for the half you do not have never offers to delete a setup the other half is using — and when it cannot tell, it says nothing rather than guess. Both scopes are chosen in the same place: the dialog behind those actions groups what it writes under *This project* and *This machine*, so a project-scoped MCP config and a user-global one sit side by side, each naming the file it touches. *Skills* live on their own page at both scopes: **Settings → Skills Studio** carries the skills OpenKnowledge ships (user scope) or the project's own skill (project scope), each with an explicit Install/Uninstall button behind a confirmation naming every path it touches, plus the folders your AI tools read skills from. Removal keeps the guest discipline you would expect: only entries OpenKnowledge recognizably wrote are removed, and anything you customized is left intact. One case works differently, and it is the only place OpenKnowledge replaces something it did not write. If the entry named `open-knowledge` is there but OpenKnowledge does not recognize it, because you edited it by hand or another tool claimed the name, that row is offered as an overwrite rather than left dead. It opens unticked with a warning naming the file, so nothing happens until you ask for it, and ticking it replaces that one entry outright rather than merging into it. Other servers in the file are untouched. This is offered only where the config is JSON; for Codex, Hermes, and Pi the entry is left alone, because on those formats OpenKnowledge merges its own keys into an existing entry instead of replacing it, and a merge would leave part of the entry you edited attached to a server OpenKnowledge starts. Removal never takes an unrecognized entry away, in any format. ## What leaves your machine None of your content, by default. Everything above is written to your own disk. The only ways data leaves your machine are these — all opt-in or on-demand, except three automatic actions that carry no document content (the desktop update check, a one-time share-link check on first launch, and the skill-install report): | What | When | Where it goes | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Diagnostic bundle | Only when you run `ok diagnose bundle` (you can inspect it first). On macOS it also carries the crash reports the OS recorded for this app and its helper processes (listed above), which are machine-wide rather than project-scoped; only this app's are collected, never another application's, though a report of ours still names the processes it was running alongside, and the summary printed before the zip is written says what that search found even when the answer is nothing | Wherever you send it | | In-app bug report | Only when you click **Send** in the desktop app's **Help → Report a bug…** dialog, or the `Cmd+Shift+D` / `Ctrl+Shift+D` shortcut that opens the same dialog — it builds a secret-redacted zip you can reveal and inspect first, and nothing is sent without that explicit click. The zip carries a picture of the app window unless you uncheck **Screenshot** in that dialog, and the preview there is the picture that would be sent. You can also attach up to three images by dragging them into the dialog or browsing for files. Neither these images nor the screenshot are scanned or redacted, so review them before sending. A report reached through a surface you opened only to get to the reporter — the command palette, the Help popover, or the Windows and Linux menu bar — waits for that surface to close first, and carries no marker, because the row it would point at has already gone. Every other report you start yourself photographs the screen as it is, so an open menu or another person's document visible at the time is in the picture, and carries a marker drawn where your pointer was, since a screenshot never includes the cursor. No marker is drawn either if the pointer has not moved since the window loaded, or has since left the window. The invitation that appears on its own after a crash is the exception to all of this: it carries no picture at all. After a crash, the same dialog adds an **off-by-default** "Include crash dump" checkbox: a crash dump is a memory snapshot that can contain document content and can't be redacted, and it is only ever attached when you check that box. On macOS the zip also carries the update helper's install log (listed above), which is machine-wide rather than project-scoped; the zip's own README names it and says where it came from. At the **Detailed diagnostics** level — pre-checked on the invitation that follows a crash — it additionally carries the crash reports macOS itself recorded for this app and its helpers (also listed above), which are machine-wide for the same reason and named in the same README; only this app's are collected, never another application's, though a report of ours still names the processes it was running alongside, and the zip always says what that search found even when the answer is nothing. The zip also carries a short send history of the bug reports previously generated on this machine — when each was generated and whether sending it succeeded — which is what makes a report that failed to send diagnosable at all. That history is machine-wide too, so it names the other projects you have filed reports from; it carries no document content, and the README names it the same way | By default, Send makes no network request — it opens a prefilled email draft to [support@inkeep.com](mailto:support@inkeep.com) that you send yourself, naming the zip to attach. Only when an operator has configured a bug-report intake endpoint ([`OK_BUG_REPORT_INTAKE_URL`](https://openknowledge.ai/docs/reference/configuration#environment-variables)) does Send upload the zip there, falling back to the same email draft if the upload fails | | Uninstall feedback | Only if you answer the optional "Before you go" screen or prompt. The macOS desktop asks after you confirm removal, before the app quits and cleanup starts; feedback can be sent even if cleanup later fails. Interactive `ok uninstall` asks only after successful cleanup. Skipping sends nothing; CLI runs with `--yes`, `--json`, or non-interactive input never ask | `openknowledge.ai/api/feedback` — the reason you picked, your note, your email address if you gave one, plus the app version and platform. It files one ticket for the team; nothing from your notes is included | | Semantic search embeddings | Only when you enable [semantic search](https://openknowledge.ai/docs/reference/configuration#semantic-search) **and** set a key — off by default | Your configured embeddings provider (OpenAI by default) | | GitHub sync / share | When you sync, clone, publish, or share | GitHub | | Update check | Automatically — on launch and periodically while the desktop app runs | OpenKnowledge update service (`openknowledge.ai/updates`), which redirects to GitHub; sends the app version and channel | | First-launch share check | Once, automatically, on the desktop app's first launch | `openknowledge.ai/continue` — redeems a share link if you installed from one | | Skill-install report | Automatically, the first time a published skill is actually installed — OpenKnowledge's own built-in and starter-pack skills, and skills you install from a skills.sh listing. Counted once per skill for machine-wide installs (the built-in bundles), and once per skill **per project** for skills installed into a project, since each project gets its own copy in its own editor dirs. Never re-sent on a re-run, a reinstall, an app launch, or reopening a project — an app launch that installs nothing sends nothing. A skill you install by typing a **third-party** repository yourself is **not** reported, and neither is a private, local, or internal-hostname source. A skill bundle you switched off is never installed and so is never reported | `add-skill.vercel.sh` — the skill's name, its source repository, and which agent tools it was installed for. No file contents. This is what gives a published skill an accurate install count. Turn it off in **Settings → Preferences**, by setting `telemetry.skillInstallReports.enabled: false`, or with `DO_NOT_TRACK=1` / `DISABLE_TELEMETRY=1` | | npm/`npx` fetch | During CLI installation and catalog-managed in-app agent startup, including package admission probes, package downloads, and cache revalidation | Your configured npm registry (the public npm registry by default); package names, version constraints, and configured registry credentials, without document content | | uv/`uvx` fetch | When starting a catalog-managed Python in-app agent, including resolution and tool installation | Your configured Python package index (PyPI by default); package names, version constraints, and configured index credentials, without document content | Local diagnostic logs and telemetry are scrubbed of credential-bearing attributes and never sent anywhere on their own. ## See also - [Configuration](https://openknowledge.ai/docs/reference/configuration): Every config key and environment variable, including the telemetry and semantic-search settings referenced here. - [CLI & web app](https://openknowledge.ai/docs/reference/cli): Install the CLI, run `ok init` / `ok start`, and the commands behind these writes. - [Ignore patterns](https://openknowledge.ai/docs/features/ignore-patterns): Control which files the editor, search, and agents can see. - [Core Concepts](https://openknowledge.ai/docs/reference/core-concepts): Why the file system is the database, and how attribution works.