Appearance
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 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).
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. - 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).
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
baselineis what was last loaded or saved;currentis what the user is typing. Dirty state iscurrent !== baseline. - A small amber dot in the header signals unsaved changes.
- Save with
Ctrl/Cmd+Sor the toolbar icon. Save is fire-and-forget on the wire - the daemon answers withproject_file_saved(success) orproject_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 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-splitinlocalStorage). - 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 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>whosesrcis adata:<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.