# Overview

> Monorepo packages, runtime surfaces (desktop app, `ok` CLI web editor, MCP server), and the shortest path from install to first agent-driven edit.

- Repository: sashimikun/open-knowledge
- GitHub: https://github.com/sashimikun/open-knowledge
- Human docs: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt

## Source Files

- `README.md`
- `packages/cli/package.json`
- `packages/app/package.json`
- `packages/server/package.json`
- `packages/desktop/package.json`
- `packages/core/package.json`
- `docs/content/get-started/overview.mdx`

---

---
title: "Overview"
description: "Monorepo packages, runtime surfaces (desktop app, `ok` CLI web editor, MCP server), and the shortest path from install to first agent-driven edit."
---

OpenKnowledge is a Bun-workspaced monorepo that ships a local-first markdown knowledge base: the `@inkeep/open-knowledge` npm package exposes the `ok` CLI, which scaffolds a `.ok/` project, boots a Hocuspocus/Yjs collaboration server from `@inkeep/open-knowledge-server`, serves the Vite/React editor from `@inkeep/open-knowledge-app`, and registers an MCP stdio server named `open-knowledge` for any MCP-capable agent.

## Runtime surfaces

Three entry points share the same server and content directory. Pick one based on platform; all paths converge on the same project files and MCP toolset.

| Surface | How you launch it | Typical platform |
| --- | --- | --- |
| Desktop app | Download the arm64 DMG, drag **Open Knowledge** to **Applications**, launch | macOS Apple Silicon |
| CLI web editor | `npm install -g @inkeep/open-knowledge`, then `ok start --open` | Linux, Windows, Intel Mac |
| MCP stdio server | Registered by `ok init` as `open-knowledge`; agents invoke `ok mcp` (or the desktop bundle shim) | Any MCP client |

<Note>
Running bare `ok` with no subcommand launches the desktop app when it is installed; otherwise it falls back to `ok start`.
</Note>

The desktop shell (`@inkeep/open-knowledge-desktop`) embeds the same web app and boots `@inkeep/open-knowledge-server` in a utility process. The CLI bundles the built app assets under `dist/public` and can spawn a detached `ok ui` child for the browser UI.

## Three-layer model

OpenKnowledge separates editing, agent access, and persistence. All three operate on the same markdown files.

| Layer | Package / protocol | Responsibility |
| --- | --- | --- |
| Editor | `@inkeep/open-knowledge-app` | WYSIWYG and source-mode editing, backlinks, frontmatter, timeline, rich MDX embeds |
| Knowledge engine | MCP server `open-knowledge` in `@inkeep/open-knowledge-server` | Seventeen agent tools for read, write, search, links, history, conflicts, and workflows |
| Content | Files under the configured `content.dir` (default `.`) | Plain `.md`/`.mdx` on disk, version-controlled by git; no separate database |

Reads such as `exec` and `preview_url` can resolve against project files without a running collaboration server. Mutations (`write`, `edit`, `delete`, `move`, and related tools) route through the server so Yjs CRDT state, link indexes, and git attribution stay consistent.

## Monorepo packages

The root workspace (`open-knowledge`) uses Bun 1.3.13+ workspaces and Turbo for builds. Published consumers install only `@inkeep/open-knowledge`; contributors work across all packages.

:::files
open-knowledge/
├── packages/
│   ├── cli/          @inkeep/open-knowledge     CLI (`ok`), npm publish target
│   ├── app/          @inkeep/open-knowledge-app Web editor (Vite + React)
│   ├── server/       @inkeep/open-knowledge-server Hocuspocus server, HTTP API, MCP
│   ├── core/         @inkeep/open-knowledge-core Shared domain logic, config schema
│   ├── desktop/      @inkeep/open-knowledge-desktop Electron macOS app
│   └── plugin/       @inkeep/open-knowledge-plugin Claude plugin metadata
└── docs/             Documentation site
:::

| Package | npm name | Role |
| --- | --- | --- |
| `packages/cli` | `@inkeep/open-knowledge` | Commander-based CLI; bins `ok` and `open-knowledge`; Node.js ≥ 24 |
| `packages/app` | `@inkeep/open-knowledge-app` | Editor UI; connects to server via Hocuspocus provider |
| `packages/server` | `@inkeep/open-knowledge-server` | `bootServer()`, Yjs CRDT, REST/MCP HTTP routes, MCP tool registry |
| `packages/core` | `@inkeep/open-knowledge-core` | Markdown pipeline, config merge, shadow-repo layout, editor constants |
| `packages/desktop` | `@inkeep/open-knowledge-desktop` | Electron shell, auto-update, embedded server utility |
| `packages/plugin` | `@inkeep/open-knowledge-plugin` | Claude Code plugin descriptor |
| `docs` | — | Public docs site (Fumadocs-style MDX) |

<Info>
Agent integration is provider-neutral: the knowledge engine speaks MCP over stdio. Bring Claude Code, Cursor, Codex, or any other MCP client and the model credentials you already use (BYOC/BYOK). `ok init` detects installed editors and writes MCP entries; bundled skills ship inside the server package.
</Info>

## Architecture at runtime

```mermaid
flowchart TB
  subgraph surfaces["Runtime surfaces"]
    Desktop["@inkeep/open-knowledge-desktop"]
    CLI["ok start / ok ui"]
    MCP["ok mcp → open-knowledge"]
  end

  subgraph server_pkg["@inkeep/open-knowledge-server"]
    Hocus["Hocuspocus + Yjs CRDT"]
    HTTP["HTTP API /api/*"]
    MCPReg["MCP tool registry"]
  end

  subgraph app_pkg["@inkeep/open-knowledge-app"]
    Editor["React editor"]
  end

  subgraph core_pkg["@inkeep/open-knowledge-core"]
    Domain["Markdown, config, indexes"]
  end

  subgraph storage["Project on disk"]
    OK[".ok/ config + locks"]
    MD["content.dir markdown files"]
    Git["git + shadow repo"]
  end

  Desktop --> Hocus
  CLI --> Hocus
  MCP --> MCPReg
  Editor <-->|WebSocket| Hocus
  Hocus --> Domain
  MCPReg --> Domain
  HTTP --> Domain
  Domain --> MD
  Domain --> Git
  Hocus --> OK
```

## MCP tool surface

`registerAllTools()` in `@inkeep/open-knowledge-server` exposes seventeen tools. Agents use these instead of raw filesystem reads when a project has `.ok/`.

| Tool | Primary use |
| --- | --- |
| `exec` | Read-only shell allowlist (`cat`, `grep`, `find`, …) with per-file enrichment |
| `search` | Full-text and optional semantic search across the knowledge base |
| `links` | Link-graph views (`dead`, `orphans`, `hubs`, `suggest`, …) |
| `write` | Create documents, optionally from folder templates |
| `edit` | Patch existing document bodies or frontmatter |
| `delete` | Remove documents |
| `move` | Rename or relocate documents |
| `history` | Per-document edit bursts with attribution |
| `checkpoint` | Named save points on the shadow timeline |
| `restore_version` | Roll back to a prior burst |
| `conflicts` | List merge conflicts after git sync |
| `resolve_conflict` | Apply a resolution choice |
| `workflow` | Procedural guides (`ingest`, `research`, `consolidate`, `discover`) |
| `palette` | Authoring component catalog |
| `config` | Read project configuration slices |
| `preview_url` | Editor preview URL for a document path |
| `share_link` | Construct read-only share URLs |

The registered MCP server name is `open-knowledge`. Cursor and other clients may prompt you to approve it on first connect.

## Shortest path to a first agent-driven edit

<Steps>

<Step title="Install a runtime surface">

<Tabs>
<Tab title="macOS desktop">

Download the latest arm64 DMG from GitHub Releases, install **Open Knowledge** to **Applications**, and launch it. Git is required for timeline and recovery features.

</Tab>
<Tab title="CLI web editor">

```bash
npm install -g @inkeep/open-knowledge
```

Requires Node.js 24+ and git on your PATH.

</Tab>
</Tabs>

</Step>

<Step title="Initialize a project">

```bash
mkdir my-knowledge-base && cd my-knowledge-base
ok init
```

`ok init` scaffolds `.ok/` (including `config.yml`), ensures a git repository, installs bundled skills, and registers the `open-knowledge` MCP server for detected editors (Claude, Claude Desktop, Cursor, Codex). Use `--no-mcp` to scaffold without touching editor config, or `--scope user|project|both` to control where MCP entries are written.

</Step>

<Step title="Start the editor">

```bash
ok start --open
```

Starts the collaboration server, acquires per-project locks under `.ok/local/`, and opens the web editor in your default browser. Without `--open`, the CLI prints the local URL.

<Warning>
If `.ok/` is missing, `ok start` exits with guidance to run `ok init` first.
</Warning>

</Step>

<Step title="Connect your agent">

Open the project folder in your agent harness. If prompted, approve the `open-knowledge` MCP server. `ok init` should have already written the stdio entry; run `ok repair-skills` if tools are missing.

Send a prompt that exercises write tools, for example:

```text
Create a knowledge base about Large Language Models. Include an overview page and separate pages for three key concepts.
```

</Step>

<Step title="Verify the edit landed">

In the editor sidebar, confirm new `.md` files appear. Click the agent activity indicator (top right) to watch cross-file edits. Use the timeline panel on a document to see git-backed attribution for the agent burst.

</Step>

</Steps>

## Project scaffold in brief

Every initialized project carries an `.ok/` directory. The marker file `.ok/config.yml` defines the content root (`content.dir`, defaulting to `.`), sharing posture, and search settings. Machine-local state (server locks, embeddings keys, logs) lives under `.ok/local/`. See the dedicated scaffold and configuration pages for the full layout and precedence order across project, user (`~/.ok/global.yml`), and project-local scopes.

## What OpenKnowledge adds beyond plain markdown

- **Rich editing** — TipTap WYSIWYG with Mermaid, LaTeX, embeds, callouts, and source-mode CodeMirror 6.
- **Agent-consistent writes** — MCP tools maintain frontmatter, wikilinks, backlinks, and shadow-repo activity metadata.
- **Git-backed timeline** — Per-burst history with selective rollback, plus GitHub sync and conflict tools.
- **Starter workflows** — `ok seed` scaffolds Karpathy-style `external-sources/` → `research/` → `articles/` layouts; `workflow` MCP kinds guide ingest/research/consolidate passes.

## Prerequisites summary

| Audience | Requirement |
| --- | --- |
| End users (CLI path) | Node.js 24+, git |
| End users (desktop) | macOS Apple Silicon, git |
| Contributors | Bun 1.3.13+, Node.js 24+; `bun install` then `bun run check` |

License: GPL-3.0-or-later.

## Next

<CardGroup>
<Card title="Installation" href="/installation">
Install paths for the macOS DMG and the `@inkeep/open-knowledge` npm CLI, plus contributor toolchain prerequisites.
</Card>
<Card title="Quickstart" href="/quickstart">
Step-by-step `ok init`, `ok start --open`, editor verification, and MCP smoke checks.
</Card>
<Card title="Core concepts" href="/core-concepts">
Three-layer model, filesystem-as-database, link graph, and git-backed attribution.
</Card>
<Card title="Initialize a project" href="/initialize-project">
What `ok init` scaffolds, git initialization, skill install, and MCP registration scopes.
</Card>
<Card title="Wire agent editors" href="/wire-agent-editors">
Connect Claude Code, Cursor, and Codex; repair stale MCP configs and verify with `exec`.
</Card>
<Card title="Collaboration server" href="/collaboration-server">
Hocuspocus/Yjs lifecycle, `ok start` locks, and server-free versus server-routed MCP paths.
</Card>
<Card title="MCP tools reference" href="/mcp-tools-reference">
All seventeen tools, input nesting, preview envelopes, and conflict guards.
</Card>
<Card title="CLI reference" href="/cli-reference">
Every `ok` subcommand, global flags, and single-file dispatch (`ok notes.md`).
</Card>
</CardGroup>