---
title: Editor
icon: LuPenLine
description: The OpenKnowledge 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.

## Open a single file

Want the editor on one loose markdown file without setting up a project? Run `ok <file>`:

```bash
ok notes.md            # open a single file in the editor
ok ./specs/foo/SPEC.md # a file inside a project opens that project, focused on the doc
```

When the file is inside an existing OpenKnowledge project, this opens that project focused on the doc. When it's a loose file, it opens an **ephemeral single-file session**: a throwaway editor scoped to just that one file, with no project scaffolding, no agents, and no git. Your edits save straight back to the original file, and **nothing is written into the file's directory** — all session state lives in a temporary directory that's removed when you close the window. Opening a file you don't edit leaves it byte-for-byte unchanged.

It opens in the desktop app when it's installed, and falls back to your browser otherwise (press Ctrl-C in the terminal to end a browser session). Single-file sessions show just the file and the editor — no sidebar, tabs, or project switcher. Discover it any time with `ok --help`.

## 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.

## Right-click menu and spell check

In the desktop app, right-clicking editable text opens a native context menu. Any editable field gets **Cut / Copy / Paste / Select All**; when there's a selection or a flagged word under the cursor, **Look Up** (the macOS dictionary panel) and **Search with Google** join it.

Spell checking uses the native macOS spellchecker (language follows your macOS settings), so misspelled words get the familiar red underline. Right-clicking a flagged word adds the spelling section:

| Item | Behavior |
| --- | --- |
| *Suggestions* | The spellchecker's corrections, one row each; pick one to replace the word. |
| **Add to Dictionary** | Teaches the macOS system dictionary the word — persistent, and shared with your other Mac apps (Safari, Notes). |
| **Disable Spell Check** | Turns spell checking off app-wide. The choice persists across relaunches. |

While spell check is off, right-clicking any editable text offers **Enable Spell Check**, and the menu bar carries the same toggle as **Edit ▸ Check Spelling While Typing** (see [Edit menu](#edit-menu)) — flip either to bring the squiggles back.

Surfaces with their own specialized right-click menus — asset and wiki-link chips, the [file sidebar](#right-click-context-menus), editor tabs — keep them; the editor menu never doubles up on top. In the web build the browser's own context menu fills this role.

## Ask AI

A persistent **Ask AI** composer is docked at the bottom of the editor in the desktop app, above the status bar and above the terminal dock (it's pushed up when the terminal expands). It's a slim, single-line entry field — always present when a doc is open — that expands as you type to accept a fuller prompt (and `@`-mentions). Type an instruction — "condense this doc", "research X", "make a spec from this user story" — and press Enter to hand it to an agent. `Shift+Enter` inserts a newline; the field clears once the prompt is sent.

It's the primary in-editor way to hand work to an agent, and the freetext companion to the menu-driven [Open with AI](#open-with-ai) (whole file / folder / project). Submitting dispatches the typed prompt to your **default agent** — the first one installed, in Claude → Codex → Cursor order — scoped to the current doc, which the agent receives as an `@`-mention. The agent picker beside the field overrides the default per send (its targets include Claude, Codex, Cursor, and the Terminal CLI), and your choice is remembered on that machine. Success and failure use the same handoff toast as Open with AI.

The composer is desktop-only and stays out of the way where it doesn't belong: it's hidden inside an AI editor's embedded view, on the web build, and when no doc is open (the empty state already offers project handoff). Like the other handoffs it dispatches only to agents installed on your machine; when none are installed, the field is disabled.

### From a text selection

Select text in the WYSIWYG editor and the selection bubble menu shows an **Ask AI** button (Sparkles icon) alongside the formatting controls. Clicking it — or pressing the selection shortcut — opens and focuses the bottom Ask AI composer with the selected passage pinned as a removable context pill, so the exact text rides along as context. Type your instruction, pick an agent, and send. (macOS desktop only; 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. OpenKnowledge 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](/docs/advanced/folders-and-templates#folder-properties) for how that works.

## File sidebar

The sidebar lists every file in your project on disk, including files excluded by `.gitignore` / `.okignore`, except dot-prefixed entries and tooling internals (`.git/`, `.ok/`, `node_modules/`). Turn on **Show Hidden Files** to reveal the dot-prefixed entries. 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 |
| 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](/docs/advanced/folders-and-templates#templates) (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](/docs/features/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

The sidebar always lists every file on disk under the content directory (including files excluded by `.gitignore` / `.okignore`), except synthetic system docs. A single **Show Hidden Files** toggle on the empty-space and folder menus controls whether dot-prefixed entries are shown. It persists per-project per-machine in `.ok/local/config.yml` under `appearance.sidebar`, and also lives in the macOS **View** menu.

| Toggle | Effect |
| --- | --- |
| **Show Hidden Files** | Off by default. When on, stops the client from hiding paths that start with `.` (recovers allowed dotfiles like `brain/.archived/note.md`). Tooling internals (`.git/`, `.ok/`, `node_modules/`) stay hidden in every mode. |

On very large trees the disk walk is capped per level, and the sidebar shows a notice telling you the list is partial.

### 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 OpenKnowledge web preview, then grounds the rest of the conversation via the [OpenKnowledge MCP](/docs/reference/mcp). Three scopes, three prompt shapes:

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

The trailing `Open the OK editor in web view.` directive is dropped when the [`appearance.preview.autoOpen`](/docs/reference/configuration) 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 OpenKnowledge.` opener is sent.

To send your own freetext instruction along with the handoff, use the bottom [Ask AI](#ask-ai) composer (or the empty-state create composer on a fresh project) rather than these one-click submenus.

**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](/docs/integrations/claude-code) for what each agent receives once dispatched.

The menu is organized into two sections. **Desktop** lists the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. **Terminal** (desktop app only) adds a row for each CLI — **Claude**, **Codex**, and **Cursor** — that runs the corresponding CLI (`claude`, `codex`, `cursor`) in OpenKnowledge's docked terminal with the same scoped prompt. Because both sections can list the same name, a Desktop **Claude** (the app) and a Terminal **Claude** (the CLI) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name (and likewise "Codex CLI" / "Cursor CLI"). Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target.

The empty-state create composer on a fresh project carries the same Desktop / Terminal split: its Desktop rows pick the default agent the **Create** button uses, while its Terminal **Claude** row (desktop only, disabled until the workspace resolves) launches the `claude` CLI with the brief you typed.

### 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. This is distinct from the **Terminal** section inside **Open with AI**, which runs a CLI (`claude`, `codex`, or `cursor`) in OpenKnowledge's docked terminal rather than opening Terminal.app.

## 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 OpenKnowledge 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. OpenKnowledge 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 bottom Ask AI composer, and the empty-state agent grid are hidden; you're already inside an agent, so the handoff would loop back into the same surface. OpenKnowledge's MCP tools and the document itself stay fully available; only the launchers are gone.

## macOS application menus

The OpenKnowledge 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.

### File menu

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, 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.

### Edit menu

Alongside the standard Undo / Redo / Cut / Copy / Paste / Select All items:

| Item | Accelerator | Behavior |
| --- | --- | --- |
| **Check Spelling While Typing** | (none) | Checkbox reflecting whether spell check is on. Toggling applies app-wide and persists across relaunches — it's the same switch the editor right-click menu's Disable / Enable Spell Check rows flip (see [Right-click menu and spell check](#right-click-menu-and-spell-check)). |

### View menu

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. |
| **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](/docs/features/agent-activity)) groups every burst of agent edits with per-burst diffs and selective undo.

For recovery + history, see [Timeline and recovery](/docs/features/timeline-and-recovery).

## See also

- [Ignore patterns](/docs/features/ignore-patterns): `.okignore` syntax and Hide-from-tree mechanics
- [Configuration reference](/docs/reference/configuration): `.ok/config.yml` schema including `appearance.sidebar.*`
- [Agent activity](/docs/features/agent-activity): review and undo per-session agent edits
- [Timeline and recovery](/docs/features/timeline-and-recovery): version history and restore

