Editor

The Open Knowledge editor. WYSIWYG markdown, source toggle, content blocks, inline frontmatter, and the file sidebar.

The editor is where you read, write, and collaborate on your docs, and where AI agents land when they edit. WYSIWYG by default with a source-mode toggle, a frontmatter properties pane, real-time CRDT collaboration, and a file sidebar that organizes the project.

Document body

Open any doc from the sidebar. The body renders as WYSIWYG markdown with familiar conventions: bold / italic / headings / lists / tables / code fences / links / images. Toggle to source mode from the editor controls to edit the raw markdown directly; both views are bound to the same CRDT document, so they stay in sync across users and AI agents.

A backslash command (/) opens an insert menu for headings, lists, code blocks, callouts, and the other content shapes the editor supports.

Edit with AI

Select text in the WYSIWYG editor to hand that exact passage to an installed agent. The selection bubble menu shows an Edit with AI button alongside the formatting controls. Clicking it opens a popover with an instruction field and your installed-agent list (Claude, Codex, or Cursor). Type what you want done (the instruction is optional), pick an agent, and it opens with the project as its working directory and a prompt naming the doc, your instruction, and the selected passage.

The passage travels one of two ways, chosen automatically:

Mode	When	What the agent gets
Inline	The selection fits the agent's deep-link URL budget (the common case)	The passage inlined in a fenced block, plus the doc path and your instruction
Locus	The selection is too large to inline	A short quote of the passage's opening plus a directive to read the full passage from the doc via the Open Knowledge MCP; nothing is truncated

This is the selection-scoped sibling of the sidebar's Open with AI, which hands off a whole file, folder, or project. Like the native handoff it's macOS-only, and unlike Open with AI it has no claude.ai web fallback: selected content stays local, dispatched only to agents installed on your machine. Install detection governs which agents appear, the same as Open with AI. Text selections only for now; selecting an image or other non-text node doesn't show the affordance.

Properties

Every doc can carry a bit of structured information at the top: a status, an owner, a tags list, a date. Open Knowledge calls these its properties.

In the raw markdown file, these properties live in a fenced block at the very top of the file, between two --- lines. Markdown tools call that block frontmatter: it's just a small chunk of YAML, the doc's "labels." You never have to write it by hand: the Properties panel on the right of the editor shows each field as an ordinary form input (text, number, checkbox, date, or list) and saves your changes back into the file. Edit the panel or the raw block in source mode; changes propagate live either way.

A folder can describe itself (its own properties, just like a doc's) and offer templates that give new docs their starting properties. See Folders and templates for how that works.

File sidebar

The sidebar lists every doc in your project that isn't excluded by .gitignore or .okignore. Folder rows expand and collapse; file rows open in a tab on click. The toolbar at the top of the sidebar has buttons to create files, create folders, and search.

Right-click context menus

Right-click anywhere in the sidebar to get a context-aware menu. Three shapes share consistent ordering so the muscle memory carries across surfaces:

Item	Empty space	Folder row	File row
New File	yes	yes	no
New from template	yes	yes	no
New Folder	yes	yes	no
Reveal in Finder	yes (project root)	yes	yes
Open with AI ▸	yes (project scope)	yes (folder scope)	yes (file scope)
Open in Terminal	yes (project root)	yes (folder)	yes (parent dir)
Copy full path / Copy Path ▸	yes (full path of project root)	yes (Full / Relative)	yes (Full / Relative)
Show Hidden Files	yes	yes	no
Show all files	yes	yes	no
Expand all / Collapse all	yes (tree-scoped)	yes (subtree-scoped)	no
Rename	no	yes	yes
Hide folder / Hide this file	no	yes	yes
Delete	no	yes	yes

Items that depend on the desktop app (Reveal in Finder, Open in Terminal, Delete via Trash) are hidden in the web build. Asset rows (images, PDFs, other non-markdown files) suppress Rename, Open with AI, Hide, and Delete; they show Reveal, Open in Terminal (parent dir), and Copy Path only.

Expand all and Collapse all only appear when they have work to do: Expand all is hidden when no folder is collapsed; Collapse all is hidden when no folder is expanded.

Creating files and folders

Pick New File, New from template, or New Folder from any of the three menus. The sidebar shows an inline rename field at the target location; type a name and press Enter. New from template opens the template picker (the same dialog the toolbar's create buttons use) and respects the folder's templates_available cascade.

Right-click on empty space drops the new item at the project root. Right-click on a folder drops it inside that folder.

Hiding files and folders

Hide this file on a file row, or Hide folder on a folder row, appends a matching pattern to .okignore. See Ignore patterns for the full pattern syntax. The item disappears from the tree, search, and the agent's MCP tools immediately; nothing is deleted on disk.

Show Hidden Files / Show all files

Two toggle items on the empty-space and folder menus surface the corresponding file-tree visibility modes. They persist per-project per-machine in .ok/local/config.yml under appearance.sidebar. The toggles also live in the macOS View menu.

Toggle	Effect
Show Hidden Files	Stops the client from hiding paths that start with `.` (recovers allowed dotfiles like `brain/.archived/note.md`). Server filters still apply, so `.git/`, `.ok/`, and `node_modules/` stay hidden.
Show all files	Bypasses every filter (client dot-segment drop AND the server's `.gitignore` / `.okignore` / built-in exclusions). Surfaces literally everything on disk under the content directory, except synthetic system docs. Useful for one-off triage; flip it back off once you've found what you needed. On very large trees the walk is capped, and the sidebar shows a notice telling you the list is partial so you can use search to find the rest.
When both are on, Show all files supersedes.

Deleting via Trash

Delete moves the item to the system Trash via the same shell.trashItem call VS Code and Finder use: recoverable, not destructive.

Open with AI

Open with AI ▸ dispatches the project, the folder, or the file to one of your installed agent apps (Claude, Codex, or Cursor). The agent receives a short text prompt asking it to open the target in the Open Knowledge web preview, then grounds the rest of the conversation via the Open Knowledge MCP. Three scopes, three prompt shapes:

Scope	Triggered from	Prompt template
Project	Empty-space menu · sparkle icon (no doc / folder active)	`Let's work on this project using Open Knowledge. Open the OK editor in web view.`
Folder	Folder row menu · sparkle icon (folder view active)	Let's work on the `<folder>` folder using Open Knowledge. Open the OK editor in web view.
File	File row menu · sparkle icon (doc active)	Let's work on `<path>` using Open Knowledge. Open the OK editor in web view.

The trailing Open the OK editor in web view. directive is dropped when the appearance.preview.autoOpen preference is off, so the receiving agent honors the same "leave my preview alone" choice on its first turn; only the Let's work on … using Open Knowledge. opener is sent.

The same submenu is mounted on the sparkle icon in the editor header; it picks the scope to dispatch from whichever target is currently active in the editor.

Install detection filters the submenu to just the agents you have. When the server and your browser are on the same machine (localhost), the filter is accurate. When you're running the server elsewhere (a hosted preview, SSH tunnel, remote dev), the submenu lists every supported agent and lets your browser's OS protocol-dispatch dialog be the truth signal.

The Claude claude.ai web fallback row appears on file-scope dispatches only; the cloud agent has no project-root parameter, so folder and project dispatches hide it rather than send a context-less prompt.

See the per-integration pages for what each agent receives once dispatched.

Open in Terminal

Spawns open -a Terminal.app <dir> at the right path: the folder for a folder row, the file's parent for a file row, the project root for the empty-space menu, the parent dir for an asset row. Terminal.app is hardcoded for v1; user-configurable terminal preference is on the roadmap.

Sidebars and window width

The editor has two sidebars: the file sidebar on the left and the document panel on the right (Outline, Links, Properties, Timeline). Both adapt to the window:

At comfortable widths (about 1024px and up) both sidebars open by default.
Below that, both default to collapsed so the editor canvas isn't squeezed off-screen.
When Open Knowledge is opened inside an AI editor's webview (Cursor, Codex, Claude Desktop), both sidebars start collapsed regardless of width; the embedded view is for reading the content you were sent, not for file management.

The defaults only apply until you toggle. Open Knowledge remembers your most recent Show / Hide for each sidebar in your browser and survives reloads. When you come back to the same layout context (narrow window, comfortable window, or embedded view) you used last, your toggle is what you'll see. Toggling in a different context replaces that memory; only your most recent choice sticks, so a stale preference from a wide-monitor session can't quietly override what you just chose on a narrow screen.

Keyboard shortcuts (use Ctrl on Windows / Linux in place of Cmd):

Shortcut	Action
`Cmd+Option+S`	Show / Hide the file sidebar (left). Matches Apple's standard sidebar accelerator.
`Cmd+Option+B`	Show / Hide the document panel (right). Matches VS Code's Secondary Side Bar accelerator.

In the desktop app the same actions live in the View menu (see below) and each menu label flips between Show … and Hide … based on current state, matching Finder.

Inside an AI editor's embedded view, the Open with AI menus, the editor header's sparkle dropdown, and the empty-state agent grid are hidden; you're already inside an agent, so the handoff would loop back into the same surface. Open Knowledge's MCP tools and the document itself stay fully available; only the launchers are gone.

macOS application menus

The Open Knowledge desktop app keeps its menu bar in sync with the active editor target: File menu items enable / disable based on whether a doc, folder, or nothing is currently selected.

Below the project navigation items (Switch Project, Open Folder, Open Recent, CLI Tools, Configure AI, Close), the File menu surfaces the most-used sidebar affordances so they're reachable from the keyboard:

Item	Accelerator	Behavior
New File	`Cmd+N`	Creates a new file at the project root (or under the active folder if one is selected).
New Folder	`Cmd+Shift+N`	Creates a new folder.
New from Template…	(none)	Opens the template picker.
Rename	(none)	Inline-renames the active file or folder. Disabled when nothing is selected.
Move to Trash	`Cmd+Delete`	Sends the active file or folder to Trash (with the same confirm modal as the sidebar). Disabled when nothing is selected.
Reveal in Finder	(none)	Reveals the active target in Finder. Empty selection reveals the project root.
Open in Terminal	(none)	Opens Terminal.app at the active target's directory.
Open with AI ▸	(none)	Same submenu as the sidebar / sparkle icon, dispatched at the active scope.
Copy Path ▸	(none)	Full / Relative path of the active target.

Switch Project… moved to Cmd+Shift+P. The old Cmd+Shift+N binding now creates a new folder, matching macOS Finder, VS Code, and the broader convention.

Before the existing Zoom and Toggle Fullscreen items, the View menu gets:

Item	Accelerator	Bound to
Show / Hide Sidebar	`Cmd+Option+S`	Toggles the file sidebar (left). Label flips between Show and Hide based on current state, matching Finder.
Show / Hide Document Panel	`Cmd+Option+B`	Toggles the document panel (right).
Show Hidden Files	(none)	`appearance.sidebar.showHiddenFiles`; same toggle as the sidebar's right-click menu.
Show All Files	(none)	`appearance.sidebar.showAllFiles`.
Expand All	(none)	Expands every folder in the tree. Hidden when nothing is collapsed.
Collapse All	(none)	Collapses every folder in the tree. Hidden when nothing is expanded.

Toggling the menu checkboxes flips the underlying config field, which propagates back to the sidebar via the standard CRDT subscription; both surfaces stay synchronized.

Real-time collaboration

Everything in the editor (body, frontmatter, sidebar toggles) is backed by a CRDT. You and multiple AI agents writing through MCP can edit the same doc concurrently. Per-user presence is shown in the editor header; the agent activity view (Agent activity) groups every burst of agent edits with per-burst diffs and selective undo.

For recovery + history, see Timeline and recovery.