---
url: https://clusto.app/docs/editor.md
description: >-
  Edit project text files with Clusto's built-in CodeMirror editor and conflict
  handling.
---

# Built-in Editor

The built-in editor opens any text file in the active project's working
directory in a CodeMirror 6 buffer, shown as a tab on a terminal's workspace
pane, with explicit save and optimistic concurrency against the on-disk file.

Image, audio, and video files in the same tree open in a read-only media
viewer in the same tab - see [Media viewer](#media-viewer) below.

## Where files come from

* Click any file in the right sidebar's **Files** tab.
* Click **Open in editor** in the header of a diff tab (see
  [Git panel](/git-panel#diffs-open-as-a-tab)).

In the Terminals workspace a file opens as a **tab on the pane of the focused
terminal**. The pane gets a tab strip: the terminal first (labelled with the
session name), then its file and diff tabs. The strip appears only while there
are tabs. Opening a file that is already open shows its existing tab instead of
a second copy, and you can keep several files open as tabs at once.

* The terminal keeps running under a file tab. Click the terminal tab to see it
  again unchanged.
* Tabs belong to the terminal session (or to the chat, when a pane shows a
  chat), not to the pane. They follow the session into another layout, come
  back after an app restart, and are removed when the session is killed or the
  chat is deleted.
* Close a tab with the X on the tab, a middle-click, or the X in the file
  header. Closing asks first when the file has unsaved edits. Closing the last
  tab hides the strip.
* On phones the tabs work the same way and the strip scrolls sideways.
* Drag a tab within the strip to reorder it, or onto another pane's tab strip to
  move it there. A tab can also move into its own split pane (a file pane): drag
  it onto the edge of a pane, use the split button at the right end of the strip,
  or press `Ctrl+Alt+Shift+Arrow`. See
  [Drag and drop panes and tabs](/terminal-workspace#drag-and-drop-panes-and-tabs).
* In the Chats view a selected file opens as a tab on the chat's pane, for
  project files and for chats in any other folder (read and written by absolute
  path on the node). PDFs open in the file preview card (see
  [Chats](/chats#files-for-a-chat)).

Press **F1** to run these tab commands from the palette: **Show terminal or
chat of focused pane**, **Next tab in focused pane**, **Close file tab in
focused pane** and **Move file tab to new pane on the right/left/below/above**.

## Editing model

* The buffer's `baseline` is what was last loaded or saved; `current` is
  what the user is typing. Dirty state is `current !== baseline`.
* A small amber dot in the header signals unsaved changes.
* **Save** with `Ctrl/Cmd+S` or the toolbar icon. Save is fire-and-forget
  on the wire - the daemon answers with `project_file_saved` (success) or
  `project_file_write_conflict` (sha256 mismatch).
* **Revert** discards local edits and re-loads from disk.
* **Close** removes the file tab; with unsaved changes the user is prompted.

There is **no autosave**. Read-only buffers are not implemented yet - if
the file is read-only on disk, the daemon's write fails with a clear
error.

## Markdown preview and split view

Opening a Markdown file (`.md`, `.markdown`, `.mdown`, `.mkd`, `.mdx`) adds a
three-way view toggle to the editor header, the same one the
[Notes](/notes) editor uses:

* **Source only** - the plain CodeMirror buffer (default).
* **Split** - source on the left, live preview on the right, with a
  draggable divider. The two panes scroll in sync by scroll fraction, and
  the ratio is persisted (`clusto-editor-split` in `localStorage`).
* **Preview only** - rendered output, full width.

The chosen mode is remembered across files and restarts
(`clusto-editor-view-mode`); non-Markdown files always show the source pane
and no toggle. The preview runs the notes Markdown pipeline - GitHub
Markdown plus callouts, KaTeX math, mermaid diagrams and highlighted code
blocks. Vault-only syntax (`[[wikilinks]]`, `![[embeds]]`) has nothing to
resolve against outside the notes vault, so it renders inert. The same safety
rules apply as in Notes: raw HTML in the file shows as text, and links stay
live only when they are relative or use `http`, `https`, `mailto`, or `tel`. Mermaid loads lazily on the first diagram.

## Languages and theming

Syntax highlighting is picked from the file name. CSS (`.css`, `.scss`,
`.less`) is bundled and highlights immediately; every other language
CodeMirror knows (Rust, TypeScript, Python, Markdown and many more) loads
lazily the first time a matching file opens. Files with no matching
language open as plain text.

The editor now reads its palette from the app's CSS custom properties, the
same way the rest of the UI and the terminal do:

* Surface variables: `--editor-bg`, `--editor-foreground`,
  `--editor-gutter-*`, `--editor-border`, `--editor-active-line-*`,
  `--editor-selection-bg`, `--editor-cursor`
* Search / bracket variables: `--editor-search-match-*`,
  `--editor-bracket-match-*`

Because the editor theme is CSS-variable driven, theme toggles and custom CSS
edits update already-open editors live without recreating them.

## Wire protocol

### `WriteProjectFile`

```jsonc
// client → daemon
{
  "type": "write_project_file",
  "project_id": "<uuid>",
  "path": "src/lib.rs",
  "content": "fn main() {}\n",
  "base_sha256": "abc123…"   // omit / null to force-write a new file
}
```

The daemon validates the path (canonicalize the parent directory and
ensure it stays inside the project's `working_dir`), enforces a 1 MiB
write cap, performs an optimistic concurrency check when `base_sha256` is
provided, and writes atomically: bytes go to a `<name>.<uuid>.tmp` file
in the same directory, the file's existing mode is preserved on Unix,
then a `rename` swaps it into place. The temp file is removed on rename
failure.

### `ProjectFileSaved`

```jsonc
{
  "type": "project_file_saved",
  "project_id": "<uuid>",
  "path": "src/lib.rs",
  "sha256": "def456…"
}
```

The new sha256 is the digest the editor should treat as its base for the
next save.

### `ProjectFileWriteConflict`

```jsonc
{
  "type": "project_file_write_conflict",
  "project_id": "<uuid>",
  "path": "src/lib.rs",
  "current_sha256": "ff00ff00…"
}
```

Returned when `base_sha256` was provided and the on-disk file's current
digest differs (or the file no longer exists). The editor shows an inline
banner with **Reload** (re-baseline against disk, lose edits) and
**Overwrite** (force-write, discarding the other side's changes).
Genuine errors (path traversal, oversized payload, parent missing) come
back as `project_file_error` instead.

## Run-as-user

Writes happen as the daemon's own user, like reads. The path
containment check is the security boundary. On Unix, saving an existing
file preserves its mode and owner; a new file keeps the umask-derived mode
and, when the daemon runs as root, takes its directory's owner.

## Limitations

* No autosave; explicit `Ctrl/Cmd+S`.
* No diff-against-saved view (the [Git panel](/git-panel) diff tab covers
  worktree vs index).
* 1 MiB write cap, matching the read cap, so the editor's round-trip can't
  silently grow past what it can load back.

## Media viewer

Image, audio, and video files use the same open-file flow as text - clicking
one in the **Files** tab opens it as a tab - but render in a
read-only viewer instead of CodeMirror.

* **Detection.** By file extension. Image: `png`, `jpg`/`jpeg`, `gif`, `webp`,
  `avif`, `bmp`, `ico`, `svg`. Audio: `mp3`, `wav`, `ogg`/`oga`, `flac`,
  `m4a`, `aac`, `opus`. Video: `mp4`/`m4v`, `webm`, `mov`, `mkv`, `ogv`.
* **Rendering.** `<img>`, `<audio controls>`, or `<video controls>` whose
  `src` is a `data:<mime>;base64,<bytes>` URL built from the daemon's
  response.
* **Toolbar.** Save and Revert are hidden; only Close is available.
* **Size cap.** 25 MiB per file (vs 1 MiB for text). Bytes are base64-
  encoded into a single WebSocket frame, so larger files are rejected
  with `project_file_error`.

### `ReadProjectFileBinary`

```jsonc
// client → daemon
{
  "type": "read_project_file_binary",
  "project_id": "<uuid>",
  "path": "assets/logo.png"
}
```

The daemon validates the path (same containment check as the text reader),
enforces the 25 MiB cap, reads the file, derives a MIME type from the
extension, and responds with:

### `ProjectFileBinary`

```jsonc
{
  "type": "project_file_binary",
  "project_id": "<uuid>",
  "path": "assets/logo.png",
  "data": "<base64>",     // raw bytes, base64-encoded by serde
  "mime": "image/png",
  "sha256": "abc123…"
}
```

Failures (path traversal, oversize, missing file) come back as the same
`project_file_error` variant the text reader uses. There is no write
counterpart - media files are read-only in the viewer.
