Getting started

Initialize Open Knowledge on an existing project or clone a GitHub repo, start the editor, and connect AI agents.

Installed from the macOS DMG?

The desktop app launches a first-launch MCP consent dialog that writes user-level MCP entries to every detected editor — so your AI tools can already see Open Knowledge without any terminal commands. This guide covers the CLI-driven path for project-scoped scaffolding (.open-knowledge/, AGENTS.md, launch.json). The two paths coexist; run ok init on any project where you want that scaffolding landed.

Prerequisites

Bun >= 1.3.13 or Node.js >= 24
Git installed and on your PATH

Choose your starting point

There are two ways to get started:

Clone a GitHub repo -- start from an existing repository (public or private).
Initialize an existing project -- add Open Knowledge to a project already on disk.

Clone from GitHub

The fastest path from a GitHub URL to editing:

npx @inkeep/open-knowledge clone https://github.com/company/docs

This clones the repository, scaffolds .open-knowledge/, and starts the editor. Authentication is handled automatically -- if you have the GitHub CLI installed, its session is reused. Otherwise, you'll be prompted to sign in via Device Flow or paste a Personal Access Token.

After cloning, changes sync with the remote automatically. See GitHub Sync for details on auto-sync, conflict resolution, and configuration.

Initialize an existing project

Navigate to your project

cd your-project

Run the init command

npx @inkeep/open-knowledge init

When run interactively, init prompts you to select which editors you use. Based on your selection it:

Scaffolds .open-knowledge/ with AGENTS.md, config.yml, and .gitignore (no content subdirectories — content lives wherever config.yml points, defaulting to the repo root). If the project has no .git/ yet, init runs git init --initial-branch=main first so Open Knowledge's attribution journal has a parent repo to hang off of.
Registers the MCP server in each editor's config file at the correct per-editor path (table below).
Injects the Open Knowledge section into the editor's agent instruction file — CLAUDE.md for Claude Code, .cursorrules for [[Cursor]], .windsurfrules for [[Windsurf]] (VS Code has no standard agent rules file). This is what teaches the agent to use exec, write_document, and the other tools correctly.
Scaffolds .claude/launch.json (Claude Code only) so preview_start("open-knowledge") knows how to start the editor.
Prints a content preview showing which files the watcher will track.

init writes to the correct per-editor path for every editor whose config directory exists on your machine. Every editor uses a user-global config path — one entry applies across all your Open Knowledge projects:

Editor	Config file	Scope
Claude Code	`~/.claude.json`	User-global
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)	User-global
Cursor	`~/.cursor/mcp.json`	User-global
VS Code	`<App Support>/Code/User/mcp.json`	User-global
Codex	`~/.codex/config.toml`	User-global
Windsurf	`~/.codeium/windsurf/mcp_config.json`	User-global

Each MCP entry looks like this (using npx as the runner):

{
  "mcpServers": {
    "open-knowledge": {
      "command": "npx",
      "args": ["@inkeep/open-knowledge", "mcp"]
    }
  }
}

init also writes a .claude/launch.json so Claude Code's preview pane can spawn the editor via preview_start("open-knowledge") — runtimeArgs points at ['@inkeep/open-knowledge', 'ui'] with autoPort: true.

The command is idempotent — safe to run again without side effects. Flags:

--editor <name1,name2> or --editor all — override the detected set.
--force — overwrite existing entries (including the Open Knowledge section in AGENTS.md and per-editor instruction files).
--no-mcp — skip writing MCP config entries entirely.

Upgrading an existing project: if you ran init before, the AGENTS.md marker block is already present and init skips it by default. Run open-knowledge init --force to refresh the injected section with the latest agent instructions.

The editor starts automatically

You don't need to start the editor manually. When a connected agent is about to make edits, it calls preview_start("open-knowledge") — which starts the [[server]] and opens the browser for you. Changes stream live into the editor as the agent writes.

If you want to open the editor yourself:

npx @inkeep/open-knowledge start --open

ok start runs the Hocuspocus collab server on a kernel-allocated port and auto-spawns ok ui — a sibling process that serves the React editor at http://localhost:3000. The --open flag opens that UI in your default browser.

When you close your editor tab and stop editing, idle-shutdown tears both processes down after 30 minutes of zero WebSocket clients — you never have to run stop yourself, but it's there if you want it:

npx @inkeep/open-knowledge status   # Inspect both lockfiles
npx @inkeep/open-knowledge stop     # SIGTERM both siblings
npx @inkeep/open-knowledge clean    # Prune stale locks (if a process crashed)

See the Service Topology page for the full lifecycle model.

Starting the editor is optional. AI agents work without it — the MCP server operates in disk-only mode when no collab server is running, or detach-spawns ok start on demand when you call your first write-capable tool (opt-out via OK_MCP_AUTOSTART=0 env or mcp.autoStart: false config).

Platform support

macOS and Linux only. Windows has long-standing Node bugs with detached spawn that would break the ok mcp → ok start handoff.

The file sidebar offers several ways to create a new markdown file or folder:

Header + button -- opens a dropdown with "New file" and "New folder". Defaults to the active file's parent directory, or project root when no file is open.
Right-click a folder row -- "New file here" / "New folder here" targets that folder.
Cmd+Alt+N** (macOS) / Ctrl+Alt+N (Linux/Windows)** -- opens the new-file dialog with the active-directory default. The shortcut is ignored while focus is inside a text input, textarea, or content-editable element.
Empty workspace -- a "Create your first file" button appears when no files exist yet.
Drag and drop -- drag a file or folder row onto another folder (or onto the library root strip that appears while dragging) to move it. Invalid targets (for example, moving a folder into itself) are highlighted in red. Moves use the same server rename pipeline as other file operations.

New folders are always created with an initial file (default index.md) so they appear in the tree immediately. Filenames without a .md extension get one appended on submit.

Connect AI agents

Open your project in an MCP-compatible editor

Claude Code, Cursor, Codex, or Windsurf all support MCP servers.

Approve the MCP server

When prompted, approve the open-knowledge MCP server. The editor reads the .mcp.json entry created during init.

Use the workflow tools

The agent now has access to three workflow tools:

init-content -- Bootstrap articles from your existing codebase
ingest -- Capture external sources as reference material
research -- Gather sources and write structured findings

What got created

.open-knowledge/
  AGENTS.md          — Navigation guide for AI agents (tool usage, linking conventions)
  config.yml         — Workspace config (content dir, include/exclude globs, server port)
  .gitignore         — Excludes cache/
  cache/             — Derived data (gitignored)
.git/                — Initialized via `git init --initial-branch=main` if not already present
.git/open-knowledge/ — Attribution journal (bare git repo; see Service Topology)
AGENTS.md            — Root agent instructions with Open Knowledge section injected
.mcp.json            — MCP server entry for open-knowledge
.claude/
  launch.json        — Tells Claude Code how to start the editor via preview_start

Content directories (articles/, research/, etc.) are not pre-created — organize your knowledge wherever makes sense for the project. The agent creates files as it works.

Preview content scope

To see which files Open Knowledge will track -- without starting the server or changing anything -- run:

npx @inkeep/open-knowledge preview

This works before or after init and reflects the current state of your config. Useful after editing content.include or content.exclude in .open-knowledge/config.yml.