OpenKnowledge — Repository Analysis

Generated walkthrough of inkeep/open-knowledge — a local-first, collaborative WYSIWYG markdown editor and knowledge base that integrates into coding-agent harnesses (Claude Code, Codex, Cursor, OpenCode) via MCP, skills, and a CLI scaffolder. Studied from a shallow clone; line numbers match the tree at the time of writing and are not pinned to a release.

This directory is a layered tour. Start here for the map; later docs drill into each subsystem. The reading order that matches the owner's interest — harness bridges, MCP, skills, the desktop runtime — is 02 → 03 → 04 → 05 → 08.

1. Purpose & Problem

What it is. OpenKnowledge (OK) is "a beautiful, local-first WYSIWYG markdown editor with integrations for Claude, Codex, and other harnesses" (README.md:3). It edits plain .md files the way Notion or Google Docs edits rich text, keeps them in a git repo, and — the part worth studying — exposes that repo to coding agents as a first-class tool surface.

What it solves. Coding agents are great at writing files and terrible at curating a body of knowledge over time: they duplicate research, cite dead URLs, leave orphaned notes, and never promote a draft to a source of truth. OK gives agents (and the humans alongside them) a structured place to read, write, search, cross-link, and version knowledge — with the editor rendering every agent edit live, and git recording who (which agent, which session) changed what.

Who it's for. Three audiences named in the README (README.md:3): personal notes, team knowledge bases, and "LLM wikis" / agent second-brains. The last is the novel one — a knowledge base whose primary authors are agents and whose primary reviewers are humans.

License & shape. GPL-3.0-or-later (LICENSE). It is the public mirror of an internal monorepo (inkeep/agents-private), generated from an allowlist (AGENTS.md). Bun 1.3.13+ / Node 24+, turbo-driven monorepo.

2. What distinguishes it — the inversion vs. a meta-harness

The corpus already has Omnigent, a meta-harness that wraps Claude Code, Codex, and Cursor from above and owns the orchestration loop. OpenKnowledge is the mirror image: it ships no agent loop of its own and integrates from the side.

 Omnigent  ───────────────►  drives the agent's loop (tmux paste, app-server RPC, …)
 (above)                     the loop belongs to the harness; governance to Omnigent

 OpenKnowledge  ───────────►  is a tool + skill the agent loads
 (beside)                     the loop belongs to the harness; the *knowledge substrate*
                              belongs to OpenKnowledge

The consequence: OK never has to "support" an agent. It speaks the one protocol every modern harness already knows how to load — MCP — and ships a skill that teaches the agent how to use it. Adding a harness is adding an adapter that writes that harness's MCP config file, not reverse-engineering its internals.

What an agent gets when OK is wired in:

17 MCP tools for reading/writing/searching/versioning the knowledge base (exec, search, write, edit, checkpoint, links, workflow, …) — see 03_mcp_tools.md.
A knowledge-building workflow (discover → ingest → research → consolidate) delivered as instruction text the tool returns — see 04_knowledge_workflows.md.
Skills (SKILL.md) installed into the harness's own skill directory — see 05_skills.md.
A live editor where the agent's writes land in the same CRDT document a human is editing, with per-agent activity and rollback — see 06_collaboration_crdt.md.

3. Tech Stack

Layer	Choice	Why it matters
Editor	TipTap / ProseMirror + Yjs CRDT	WYSIWYG over markdown; agent + human co-edit the same doc
Markdown bridge	`@handlewithcare/remark-prosemirror` (patched)	round-trips `.md` ↔ rich text without corrupting source
Collaboration	Hocuspocus (Yjs WebSocket server)	real-time multi-client + multi-agent sync
Agent surface	Model Context Protocol (stdio)	the universal seam every harness loads
Search	Orama (BM25) + OpenAI embeddings, fused with RRF	lexical + semantic ranking, see `09_agentic_search.md`
Persistence	git shadow repo (`simple-git`)	every edit is an attributed commit, see `07_git_sync_audit.md`
Desktop	Electron + `node-pty` + `@napi-rs/keyring`	hosts a terminal (the "TUI") and native secret storage
Build	Bun + Turbo monorepo	6 packages + docs

4. Package map (monorepo)

Package	Responsibility	Deep-dive
`packages/app`	Web app + WYSIWYG editor UI (React + TipTap)	`06_collaboration_crdt.md`
`packages/cli`	The `ok` command — `init`, `start`, `mcp`, sync, …	`02_harness_integration.md`
`packages/core`	Shared domain logic, schema, search index	`01_architecture.md`, `09`
`packages/desktop`	Electron app, terminal, keyring, deep links	`08_desktop_runtime.md`
`packages/plugin`	Claude Code plugin manifest (declarative shim)	`03_mcp_tools.md`
`packages/server`	Hocuspocus collab server + MCP tool handlers + git sync	`03`, `06`, `07`
`docs/`	Fumadocs documentation site	—

5. Document index

00_overview.md — this file
01_architecture.md — monorepo, the CRDT document model, data flow
02_harness_integration.md — the bridges: EditorMcpTarget adapter, ok init, per-harness configs, "Open with AI" handoff
03_mcp_tools.md — the 17-tool MCP surface, schemas, result format
04_knowledge_workflows.md — the discover/ingest/research/consolidate pipeline (Karpathy three-layer wiki)
05_skills.md — SKILL.md skills, cross-harness install, skill packs
06_collaboration_crdt.md — TipTap + Yjs + Hocuspocus, the agent-as-collaborator seam
07_git_sync_audit.md — shadow repo, per-writer refs, attributed commits, GitHub sync
08_desktop_runtime.md — Electron, typed IPC, the node-pty terminal ("TUI"), keyring, deep links
09_agentic_search.md — hybrid lexical + BM25 + vector search, RRF fusion
10_llm_leverage_patterns.md — tool-as-prompt, human-in-loop gates, what distinguishes OK from "just ask Claude Code"
11_file_map.md — file → responsibility map