# OpenKnowledge: a local markdown IDE that wires Claude and Codex into your notes

> OpenKnowledge from inkeep is a GPL-3.0 TypeScript desktop and web editor for markdown folders, with MCP and skills so agents can search and write into the same files. The interesting part is the agent integration; the thin part is documentation for anyone who wants to run it as a server.

**inkeep/open-knowledge** — Beautiful, AI-native markdown IDE and LLM wiki. To get more complex, you can use the starter packs to create LLM Wikis, second brains, or more structured knowledge bases.

- Repository: https://github.com/inkeep/open-knowledge
- Website: https://openknowledge.ai
- Stars: 4,318 · Forks: 289
- Language: TypeScript
- License: GPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/inkeep-open-knowledge

## The problem: your notes and your agent do not share a filesystem

Most people who write with an LLM end up with two disconnected stores. The notes live in a folder of markdown files, edited in Obsidian, VS Code or a plain text editor. The conversation lives in a chat window that cannot see those files unless you paste them in, and anything the model writes has to be copied back by hand. OpenKnowledge targets that gap. The README describes it as "a beautiful markdown editor with integrations with Claude, Codex, and other harnesses" for "knowledge bases, LLM wikis, specs, and notes", and the pitch is explicitly local: private, local, and free. The intended user is someone who already has a folder of markdown or mdx files, whether that is an existing codebase, a wiki, or an Obsidian vault, and wants an editor that can hand those files to an agent. The README says the app can be used with existing codebases, wikis and Obsidian vaults, which tells you it does not impose a new storage format. That is the right call. A tool that asks you to migrate your notes before it is useful gets abandoned.

## What actually happens when you run ok init

The mechanism is scaffolding plus wiring, not a sync service. When you run `ok init` inside a project folder, the CLI scaffolds the project and connects the AI editors it finds on your machine. The README names the ones it looks for: Claude Code, Claude Desktop, Cursor, Codex, OpenCode and OpenClaw. The README also states that the app walks you through installing MCP and skills for detected harnesses, and that these are "designed to help agents with enriched search + authoring of documents". So the data flow is: your markdown files stay where they are on disk, the editor reads and writes them directly, and the agent talks to the same folder through an MCP server rather than through a copy pasted into a prompt. Git and GitHub based sync and sharing are described as optional, which means the default path is a local folder with no remote. The repository layout supports this reading. It is a pnpm workspace with packages for a server, a core library, a desktop app and an app package, plus a docs directory and a scripts directory full of drift checks. The `.env.example` file states that a fresh clone runs end-to-end with no .env file, and that all variables are optional. That is a deliberate design choice: no configuration required to start. The cost is that the project has no configuration surface to document either, which matters later.

## Installing OpenKnowledge and opening a real folder

There are two install paths. The desktop app ships as a DMG for Apple Silicon macOS, a per-user Setup installer for Windows 10+ on x64 or Arm64, and deb or rpm packages for Linux on x64 or arm64. The README says to download it from openknowledge.ai/download or from the latest release page. The macOS instructions are to open the DMG and drag OpenKnowledge to Applications; the Windows installer runs per-user with no admin prompt. The second path is the web app, which the README recommends for Intel Macs and servers, and which needs Node.js 24+ and git. Install the CLI globally, then scaffold and start from inside the folder you want to edit.

```bash
npm install -g @inkeep/open-knowledge
cd your-project
ok init          # scaffold the project + wire up your AI editors (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw)
ok start --open  # serve the web editor and open it in your browser
```

After `ok init` you should see the project scaffolded and any detected agent harnesses configured. After `ok start --open` the editor opens in your browser pointed at the folder you ran the command from. The README does not document a port flag for `ok start`; it says the CLI has its own port resolution, separate from the Vite dev server default of 5173 that `VITE_PORT` controls. If you are working on the project itself rather than using it, the `.env.example` file gives the contributor loop:

```bash
pnpm install
pnpm run check
pnpm --filter @inkeep/open-knowledge-app run dev
```

The workspace pins pnpm 10.33.0 and declares `"node": ">=24.2.0"` in the engines field, which is stricter than the Node.js 24+ the README asks for.

## WYSIWYG markdown is a real trade-off, not a free upgrade

The headline feature is full WYSIWYG editing, so that markdown files feel like a Google Doc or a Notion page. The README lists this first. Anyone who has edited markdown for years will read that claim with suspicion, and they should. A WYSIWYG layer over markdown has to decide what to do with constructs that have no visual equivalent: reference-style links, HTML blocks, footnotes, nested lists with mixed markers, and the exact whitespace that makes some markdown renderers behave. The README does not say how the editor round-trips those. It does say the app supports embeddable HTML and rich components for engineering specs and visualized reports, which means the editor is willing to write non-portable content into your files. If your markdown needs to render identically in GitHub, a static site generator and the editor, that is a risk you cannot evaluate from the README alone. The honest position is that WYSIWYG is the right default for prose and specs, and the wrong default for files that are consumed by a toolchain. Test one of your own files before you trust it.

## Where OpenKnowledge is the wrong tool

The README is clear that this is a local, folder-based editor, and that framing excludes a few use cases. It is not a hosted knowledge platform. Sync and sharing exist, but they are described as no-code team sharing and auto-sync powered by git and GitHub under the hood, and as optionally enabled. If your team needs permissions, audit logs or a server-side search index, git-backed sharing is a different product category. It is also not a replacement for a documentation build pipeline. The README does not describe a static site generator, a versioned docs build, or a publishing step. And it is not a general purpose agent runtime. The MCP and skills it installs are described as helping agents with search and authoring of documents, so the scope is your markdown folder, not arbitrary tasks. One more constraint worth naming: the project is pre-1.0. The most recent releases in the repository are v0.67.0-beta.2, v0.67.0-beta.1 and v0.66.2, all dated 2026-08-29. A beta series at 0.67 means the file format for project scaffolding and the agent wiring can change between releases. The README does not document a migration path for existing scaffolds.

## OpenKnowledge vs Obsidian: local markdown, different centre of gravity

The comparison people will make is Obsidian, and the search data shows it. Both edit a folder of markdown files on your disk, and the README explicitly says OpenKnowledge can be used with existing Obsidian vaults. The difference is what sits at the centre. Obsidian's model is plugins: a large community ecosystem that extends the editor itself, with sync and publish as paid add-ons. OpenKnowledge's model is agents. The README lists MCP, skills and agentic search as out-of-the-box features, and the AI editing is side-by-side with Claude, Codex, OpenCode and Pi, with the note that it can be used with any harness or agent via MCP or CLI. So the choice is roughly: pick Obsidian if you want the largest plugin ecosystem for editing and linking notes, and pick OpenKnowledge if you want the editor to be the place where an agent reads and writes your documents. They are not mutually exclusive in principle, since both operate on plain files, but running two editors over one folder invites conflicting writes. Pick one as the primary writer. Also note the licence difference in kind: OpenKnowledge is GPL-3.0-or-later, which is a copyleft licence, while Obsidian is proprietary but free to use.

## Licence, maintenance and what an upgrade costs you

OpenKnowledge is licensed under GNU General Public License v3.0 or later, and the package.json declares `"license": "GPL-3.0-or-later"`. GPL-3.0 is a copyleft licence. If you modify the code and distribute it, or distribute a derivative work, the licence's source disclosure terms apply to that distribution. Using the app to edit your own notes is not distribution, so the practical effect for most users is nil. The effect matters if you fork the editor, embed it in a product, or ship a modified build. That is a description of the licence's terms, not legal advice; if your situation involves redistribution, read the LICENSE file and get proper advice. On maintenance: the repository is not archived, and the last push was on 2026-08-29. The release cadence visible in the release list is rapid, with two beta tags and a patch release on the same day. Upgrades are the cost. The repository has a changesets directory and a set of drift checks, including `check:drift:guards` and a `check:no-major-changeset` script, which suggests the maintainers gate breaking changes deliberately. For a user, the upgrade risk is concentrated in two places: the scaffold that `ok init` writes, and the MCP and skill files it installs into your agent harnesses. Neither is covered by a documented rollback in the README.

## Conclusion

Adopt OpenKnowledge if you already keep notes, specs or a wiki as a folder of markdown files and you want an editor that hands those files to Claude, Codex, OpenCode or Pi through MCP and skills without a cloud round trip. Do not adopt it if you need a hosted, multi-tenant knowledge platform, or if you cannot accept GPL-3.0-or-later terms for whatever you build on top of it. Before you commit, verify two things: that the Node.js version on your machine satisfies the >=24.2.0 engine field in package.json, and that `ok init` detects the agent harnesses you actually use, since the README lists Claude Code, Claude Desktop, Cursor, Codex, OpenCode and OpenClaw as the ones it wires up. The repository's last push was on 2026-08-29.

## FAQ

### How do I install OpenKnowledge?

Download the desktop app from openknowledge.ai/download or the latest release for macOS, Windows or Linux, or install the CLI with npm install -g @inkeep/open-knowledge and run ok init followed by ok start --open. The web app path requires Node.js 24+ and git.

### What is OpenKnowledge used for?

The README describes it as a markdown editor for knowledge bases, LLM wikis, specs and notes, with side-by-side AI editing and out-of-the-box MCP, skills and agentic search. You open an existing folder of markdown or mdx files, including an Obsidian vault or a codebase.

### OpenKnowledge vs Obsidian: which should I use?

Both edit local markdown files, and the README says OpenKnowledge can open an existing Obsidian vault. Obsidian's extension model is plugins, while OpenKnowledge's is agent integrations through MCP and skills for Claude, Codex, OpenCode and Pi, so the choice comes down to whether you want plugins or agents at the centre.

### What licence does OpenKnowledge use?

It is licensed under GNU General Public License v3.0 or later, and package.json declares GPL-3.0-or-later. That is a copyleft licence, so the source disclosure terms apply if you distribute modified versions.

### Does OpenKnowledge work with Claude and Codex?

Yes. The README lists side-by-side AI editing with Claude, Codex, OpenCode and Pi, and says ok init wires up Claude Code, Claude Desktop, Cursor, Codex, OpenCode and OpenClaw for harnesses it detects. It also states the app can be used with any harness or agent via MCP or CLI.

## Sources

- [Official documentation](https://openknowledge.ai)
- [Official README](https://github.com/inkeep/open-knowledge#readme)
- [Project repository](https://github.com/inkeep/open-knowledge)
- [Release notes](https://github.com/inkeep/open-knowledge/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/inkeep-open-knowledge