Module: editor / notes buffers
The emacs-like editing core: markdown/text buffers with command-palette-driven editing. Also the rendering target other modules use to open text (file explorer opens files into editor buffers).
Status: buffer panel + source model implemented (C1). The editor.buffer
panel (CodeMirror 6) and the URI source model ship; openBuffer(source) opens (or
focuses) a buffer for a note:/workspace-file: source, loading via the backend
and saving back (notes carry the revision for conflict detection). The public
command surface and the keybinding-service keymap (C3), agent tools (C4), and the
editor.recentNotes dashboard widget (C5) all ship.
Engine: CodeMirror 6. Lean, extensible, and emacs-friendly — code-aware (syntax highlighting, markdown) without pulling in a full IDE. IntelliSense ships: the layered completion stack below (LSP spine + DB symbol index + curated imports) plus hover, diagnostics, go-to-definition, rename, and references. The CM6 keymap is exposed through the shell keybinding service so bindings stay rebindable — editing key handlers are never hardcoded in the component.
Contributions to the layout shell
-
Panels:
editor.buffer(one panel instance per open buffer, each in a window; merge windows to tab them). The shell owns tab UX, the editor owns content. The pane receives itssourcevia pane params (usePaneParams); the instance id is derived from the source so reopening the same file/note focuses the existing buffer (generic windowing support added withopenPanel(id, { instanceId, params })). -
Commands (C3):
editor.newNote(create + open a note,/new),editor.newBuffer(an untitled scratch file,/scratch— see Untitled buffers),editor.save(/save),editor.saveAs(/save-as),editor.saveAll(/save-all),editor.visualizeBuffer(open the active buffer in the visualizer, inferring the engine from its language). The/…names are the minibuffer slash forms (see windowing.mdx) — and because Save As is adialogs.prompt(), it asks for the path in the minibuffer rather than a modal.editor.saveAsreaches the live CodeMirror view through a module-levelsetActiveSaveAspublished by the focusedBufferView, the same pattern the browser uses for its URL-bar focuser.mod+sis a default keybinding →editor.saverouted through the shell keybinding service — the buffer has no hardcoded save handler, so the key stays rebindable. (editor.openquick-open is still to come.)ctrl+shift+space→editor.toggleSuggestionsopens the completion popup, or closes it if it is open — a shell binding rather than a CodeMirror keymap so it is rebindable and listed with the rest, scopedwhen: textInputand acting on whichever view holds the caret (a buffer or a notebook cell). App-level keys route through the shell service; editor-internal keys are CodeMirror keymaps scoped to the view (they act on cursor/selection state, so a global command can't express them): Tab accepts an open completion popup, else opens one where completions could plausibly come from, else indents (Shift-Tab dedents); F12 go-to-definition and F2 rename (see the LSP section); Tab/Esc accept/dismiss inline autosuggest at higher precedence. Binding Tab is deliberate —basicSetupleaves it unbound for accessibility, which made it escape to the browser's focus traversal instead of indenting. -
Services for other modules:
editor.openBuffer(source, { language? })is the public way any module shows editable text. Sources are URIs (note:,workspace-file:,gdrive:,github:,osfile:on desktop) so the buffer layer doesn't care where content lives; an optionallanguageparam highlights extensionless sources (notes). Reopening a source focuses its existing buffer rather than duplicating it (the pane's instance id is derived from the source URI), and opening from a blank, unmodified buffer reuses that pane in place — a placeholder editor holds nothing worth preserving, so notes opened from the Recent-notes region land in the editor you are looking at instead of splitting off a second one. Reuse goes through the frame engine'sretargetPane(see windowing), which keeps the pane's area, tab position, and region strips. When there is nothing to reuse but the editor is already on screen, the new buffer opens as another tab in that same area (areaHostingView+openPaneInArea) — role-routedopenPanewould split off a fresh area instead, which meant every file clicked in the tree carved the frame up further. Only a first editor buffer takes new space. For richer cross-module use, the editor also registers aneditorservice on the registry (registry.getService('editor'), fromservice.ts) —openBufferFromContent(materialize content as a note orscratch/file),getBufferContent(live, or the persisted bytes vialoadSourcewhen the tab is unmounted),peekBufferContent(sync, live-only),getBufferSelection(live-only by nature — a selection exists in a CodeMirror view and nowhere else, so this returns null for an unmounted tab rather than falling back to bytes),setBufferContent,getActiveBufferSource, andlistBuffers. The visualizer uses this to bridge templates ⇄ buffers (see visualizer › Editor integration), and llama.cpp uses it to trace the selection through a model.Note what the service cannot reach: an untitled buffer.
getActiveBufferSourceis keyed by source URI and an unsaved buffer has none, so it is invisible to every cross-module consumer until it is saved. Callers should say that specifically rather than reporting "no open buffer" about a buffer that is plainly open. -
Left region strip:
editor.recentNotes(embedded) — the most-recently-updated notes (GET /notes); click a row to open it as anote:buffer, with a "New note" affordance. Refreshes on window focus so notes created/saved elsewhere appear.
Untitled buffers and language detection
editor.newBuffer (/scratch) opens a buffer with no source — an unsaved file,
not a note. It appears as untitled.md, and editor.buffer supported this shape all
along (saveDir resolution, adoptSource retargeting on Save As); nothing opened it.
One resolver, editor/language.ts, answers "what language is this?" for both the
grammar and the LSP. It used to be two maps that disagreed: a regex over the tab title
chose the highlighting (JS/TS, Python, else Markdown — so a .rs or .cpp file
rendered as Markdown and nothing said so), and a separate extension switch chose the
LSP language id. Filename matching now comes from @codemirror/language-data, so the
grammar set is CodeMirror's rather than a table we maintain, and each grammar is a
dynamic import — nothing loads until a buffer needs it.
Precedence: a manual pin, then the opener's language hint, then the filename, then a
content sniff, then Markdown.
The sniff (sniffLanguage, pure and unit-tested) runs only for a sourceless
buffer. That gate is the whole design: a buffer with a name has already been told
what it is, and a .py file momentarily holding prose is still Python. A shebang is
decisive on its own; every other family needs two corroborating signals and a clear
winner, because a language that flickers mid-word under the cursor is worse than one
that arrives a beat late — import x alone is Python, JavaScript, Rust and Java at
once. It reads a debounced snapshot (600ms), not every keystroke.
Saving pins the answer: Save As proposes an extension from the resolved language (a
sniffed-Python scratch buffer offers .py), and once the file has a name the name
decides. The buffer header carries a compact language control that reports the resolved
language and lets you override it — the answer is sometimes a guess now, and a buffer
silently highlighting as the wrong language with the wrong completions is exactly what
saying so out loud prevents.
Adding a language is now two places, not three: language.ts and LSP_SERVERS in
backend/modules/lsp/manager.py (which gained cpp and clangd).
Completion is no longer gated on the language server
autocompletion() used to be configured in exactly one place — inside lspExtension —
which meant only a workspace-file: in one of five languages had any completion
source. A note, an unsaved buffer, a .json, a Drive file had none, even though the
code_symbols index that would serve them was already built.
editor/completion.ts owns the stack instead, and the language server is one optional
source among several. BufferView mounts it through its own compartment for buffers
with no server; lspExtension calls the same builder with the server's source added.
autocompletion() at a time, swapped in one transactionCodeMirror merges configuration across live instances, but override is a
replacing field it has no combiner for: two live instances that both set it do not
degrade quietly, they make the dispatch throw
Config merge conflict for field override. The LSP compartment and the standalone
compartment are therefore configured from one predicate (usesLanguageServer) and are
never both non-empty.
That predicate is not enough on its own, because the two compartments live in one
buffer and a compartment is only as exclusive as the moment it is reconfigured. They
must swap in the same transaction. They used to be reconfigured from two separate
effects — the LSP one when the content arrived, the standalone one when the resolved
language changed — and between the two, the stack resolved while the tab title was
still the … placeholder (no language, so: standalone) was live alongside the one
resolved from the loaded filename (gqa.py → python, so: LSP). The throw landed
inside the load's .then, so the buffer's own .catch swallowed it into the status
bar and the content transaction was rolled back with it: every source file opened
from the Explorer came up blank.
Hence the load applies content on its own transaction first and reconfigures second, guarded — a buffer that loaded is more use with no completions than one that shows nothing.
Completing an import statement
from <Tab> and from vllm import <Tab> ask questions the identifier prefix query
cannot answer: the first has no prefix at all, the second wants one module's importable
names rather than a global scan. editor/importContext.ts classifies the cursor
(importContextAt, pure) and queries two routes:
| Route | Answers |
|---|---|
GET /api/editor/complete/modules | Module names for a from / import statement. |
GET /api/editor/complete/members | The names importable from one module. |
Both accept an empty prefix — unlike /complete, whose "no prefix, no rows" fast
path is correct for the hot identifier lookup and would be the exact bug here. With no
prefix the module query returns top-level modules only; listing every dotted submodule
of every indexed package is thousands of rows and none of them is the question.
Two rules do real work:
-
The member query filters on
imp, notmodule. For a method,moduleholds the class it belongs to (extract_packagesstoresmember_of or module), so filtering onmodulewould answerfrom vllm import …withLLM's methods and miss the package's own names.impis by construction "the module this symbol can be imported from", and is empty for methods. -
A member completion applies as a bare name, never through
applyImport. We are already inside the import statement; routing through it would insert a secondfrom vllm import LLMline above the one being typed. -
A package with no rows of its own falls back to its submodules.
impis where a symbol is defined, never where it is re-exported from —transformersre-exportsAutoModelout oftransformers.models.auto— so the exact match answeredfrom transformers import <Tab>with nothing while the index held 530 transformers symbols. Same for numpy and torch: for every package that assembles its public surface in__init__.py, which is most large ones. Only packages that define their names directly there (huggingface_hub, sympy) ever worked, which is what made this read as a flaky index rather than a structural miss.The fallback fires only when the exact match is empty, and that is the whole of its safety.
vllmreally does defineLLMand really does not re-exportLoRARequest, so blending submodule names into a package the index already describes correctly would offer an import that fails. Where there is nothing to be wrong about a guess costs nothing; where there is, the precise answer stands alone. Fallback rows carry their defining module indetail, so the guess is legible as one.
Modules rank by import depth first, so vllm beats vllm.lora.request — the same
rationale that tiers the identifier query.
Opening the popup: three gestures, and why it needed all three
An empty prefix is the case this whole path exists for, and it is also the one nothing
can auto-trigger on — there is no word to match. So it is answered when the user asks
(explicit), or at the one moment they are unambiguously waiting to be told:
- Typing the space after the keyword.
importContextAtreportsjustOpenedwhen the cursor sits directly afterimport,from, a comma or an open paren, and one space at most. That is where VS Code opens its suggest widget, and where a person reaches for it. A second space, or a space following a half-typed name, is not that moment — opening on every space in the statement is what the empty-prefix guard originally prevented, and still does. - Tab — see below.
ctrl+shift+space, theeditor.toggleSuggestionscommand. Deliberately not CodeMirror's ownctrl+space:keymap/reserved.tslists that as the IME toggle on Windows and the input-source switch on macOS, bothpreventable: false. It is exactly the shape of binding that table exists to catch — it never reaches the page, and nothing says why. Toggling rather than only opening, because the same key then dismisses; a popup you can summon but must reach for Escape to close is half a binding.when: textInputscopes it to a focused editor surface, andfocusedEditorView()resolves which one viaEditorView.findFromDOM— a notebook has one view per cell, and the only one the command can mean is the one holding the caret.
Tab opens the popup
Tab accepts an open popup, then tries to open one, then indents. The middle rung is the
whole design risk: startCompletion returns true whether or not it finds anything, so
calling it unconditionally would swallow indentation everywhere. tabStartCompletion
therefore declines — falling through to indentWithTab — unless the selection is empty,
the text before the cursor on this line is not entirely whitespace (that is
indentation, unambiguously), and either a word character precedes the cursor or the
cursor is in an import context. Ghost-text autosuggest keeps its Prec.highest Tab, so
an inline suggestion is still accepted ahead of all of it.
Notebook cells get the same stack
They did not. buildCompletion only ran inside lspExtension, and the Tab keymap was
added by BufferView alone — so a notebook cell had no completion source unless a
language server was attached, and no cell ever had the keymap. The visible symptom was
the one this section is about: from transformers import in a cell offered nothing,
Tab escaped to browser focus traversal instead of asking, and ctrl+space was eaten by
the IME. Three separate gaps, one indistinguishable outcome.
Both halves now reach a cell, and which one is a real decision:
- With a server,
NotebookLspDoc.cellExtensionreturns the LSP extension pluscompletionKeymap. - Without one,
EditorService.bareCompletion('python')returns the standalone stack plus the same keymap — that is every cell on a node with no Python server, every cell of a notebook opened before its absolute path resolves, and every cell during the seconds a cold server takes to come up.
They are alternatives and never both, for the reason in the caution above: two live
autocompletion() instances make the dispatch that installs the second one throw.
useNotebookLsp picks one and the cell's compartment swaps between them.
bareCompletion is on EditorService rather than deep-imported because the notebook
kit is domain-neutral — it knows this contract and nothing else about this module.
bareCompletion and openNotebookLsp both return a promise. Their
implementations are CodeMirror, and the service is registered at boot, so a static
import in service.ts put all of CodeMirror (1.7 MB) on the boot path of every
session, notebook or not. They import it on first use instead; useNotebookLsp hands
a cell [] for the few milliseconds that takes, and disposes a handle that resolves
after its effect was cleaned up.
Backend surface
backend/modules/notes/ — note storage implemented: CRUD + search over
backend-owned notes (GET/POST /notes, GET/PUT/DELETE /notes/{id},
GET /notes/search). Notes are identical everywhere; the editor opens them as
note:<id> buffers. Autosave and conflict handling share one path: a save
sends the base_revision the editor loaded, and a stale save returns 409 with
the current note ({message, current}) so the client reconciles. Workspace-file
read/write is the file explorer's GET /files/read /
PUT /files/write (workspace-file: buffers), so the editor's buffer layer is
URI-agnostic.
Read-only sources
Some sources can be read but not written back. loadSource sets readOnly on the
result and BufferView reconfigures a CodeMirror Compartment to
EditorState.readOnly, replacing the Save button with a Read-only badge — so the
absence of Save reads as a property of the source rather than a missing control.
saveSource also throws for them, as a backstop against a caller going around the
editor.
Enforcing it in the editor rather than at each call site is the point: a read-only buffer can never go dirty, so the close guard, the dirty marker, and the autosave path all no-op without needing to know about any particular provider.
| Scheme | Backed by | Notes |
|---|---|---|
gdrive:/<fileId> | GET /files/read via the Drive virtual root | Docs exported to text, PDFs extracted; the title arrives with the content, since the path is an id |
github:<owner>/<repo>@<ref>/<path> | GET /connectors/github/…/file | opened from the GitHub viewer |
Both inherit tabs, splits, find, and CodeMirror syntax highlighting, which is why neither the Drive mount nor the GitHub viewer ships a file viewer of its own.
Unsaved-changes guard on close
Closing a buffer with unsaved edits prompts before discarding them, VS Code-style.
The mechanism is a generic pane close guard in the frame engine
(layout/close-guards.ts): a pane registers registerCloseGuard(instanceId, fn),
and every close path — the group header's ✕, a tab's middle-click, the status bar, and
LayoutController.closePane (so agent-driven closes are covered too) — routes
through closePaneGuarded, which runs the guard and only dispatches REMOVE_PANE
when it resolves true. BufferView registers a guard that, when the buffer is
dirty, shows a dialogs.choice(...) prompt mirroring VS Code's exactly — "Do you
want to save the changes you made to {title}?" / "Your changes will be lost
if you don't save." — with Save (default) / Don't Save / Cancel. The save
must succeed for the close to proceed; a failed or cancelled save keeps the buffer
open. Like VS Code there's no separate "Save As…" button: a sourceless (untitled)
buffer has nowhere to write, so its Save falls through to the Save As flow.
dialogs.choice is the general multi-button dialog kind (alongside
prompt/confirm); the <Dialogs /> component renders it.
Save As writes a file, not a note
saveAs() always writes a workspace-file: — an untitled buffer is an unsaved
file, and turning it into a note: (as this used to) put the work somewhere the
file tree, git, and every other tool couldn't see it. Notes remain a first-class
source; they're just something you open deliberately (/new), not what Save
silently produces.
Three consequences worth knowing:
- The destination is shown, not implied. The prompt is prefilled with the full
absolute path and names the directory a bare name would land in. That directory is
the first non-virtual workspace root, which is also what the backend anchors a
relative path to (
_resolve_relativeinbackend/modules/files/routes.py), so the path shown is the path written. The header carries the same information for every buffer: the file's full path, or — while untitled — the file it would become. With no workspace root configured at all (HORRIBLE_NO_DEFAULT_ROOT) Save says so instead of silently inventing a destination. - An untitled buffer adopts what it just wrote. It
retargetPanes onto the newworkspace-file:source, so the title bar, the tab, and every latermod+sfollow the file — the buffer stops being "Untitled" the moment it stops being untitled. Retargeting rather than reopening keeps the pane's area, tab position and region strips. If that file is already open in another buffer the retarget is refused and the save is simply reported. - A buffer that already has a source keeps it. Save As there writes a copy to the new path and leaves the buffer pointed at its own source — which is what the close prompt needs, since re-pointing a closing buffer would be meaningless.
Closing the whole tab/window is guarded separately: dirty buffers flag themselves
via setPaneDirty, and a beforeunload handler triggers the browser's native
unsaved-changes prompt when anyPaneDirty() — the async choice dialog can't run
during unload. (A native window-close confirmation in the desktop shell can gate on the same flag.)
Agent integration
Status: implemented (C4). Declared on the editor.buffer panel; a live buffer
controller registry (keyed by source URI) lets the type-level tools act on a
specific open buffer. Verified live: the agent replaced an open buffer's content
via editor.applyEdit. The editor exposes
agent tools & getAgentContext:
- Read (ungated): the active buffer's uri, full text, selection, dirty state,
and live LSP diagnostics via the pane's
getAgentContext()snapshot; plus theeditor.getDiagnostics(uri)andeditor.findReferences(...)read tools (the latter backed by LSPreferences). - Gated:
editor.proposeEdit(uri, content),editor.applyEdit(uri, content),editor.rename(...)(LSP symbol rename, applied across files), andeditor.save(uri), matched by the same filesystemEdit/files.writerules the tree uses. All auto-allow under theacceptEditsmode (Claude Code parity). See the permission system.
Because sources are URIs, the agent (like any module) shows editable text through
the single editor.openBuffer(source) seam regardless of where the content lives.
Accept/decline proposed edits
For any code change (format, rewrite, fix) the agent is steered to
editor.proposeEdit rather than editor.applyEdit: instead of replacing the
content outright, the buffer enters a diff/review state (a @codemirror/merge
unifiedMergeView, original vs proposed, with per-chunk accept/reject in the
gutter) and shows an Accept / Decline bar. Accept keeps the proposed content
and marks the buffer dirty; Decline restores the pre-proposal text. The tool is in
EDIT_SAFE_TOOLS because the in-editor review — not the permission gate — is the
real safety boundary. Buffer controllers gain a propose(content) method
(buffers.ts), driven from BufferView.tsx.
Inline autosuggest
Opt-in, off by default — the editor.autosuggest setting. When on, after a typing
pause the buffer shows ghost text at the cursor; Tab accepts, Esc
dismisses. The suggestion is a prefix lookup into the DB symbol index (the tail
of the single best-matching symbol for the token under the cursor — see
Completion is a database lookup), not a
model — so there's no round-trip latency and no hallucinated multi-line guesses.
In-flight requests are debounced and cancelled on further typing; suggestions are
suppressed while an edit proposal is under review. The CodeMirror extension is
autosuggest.ts (ghost-text rendering + Tab/Esc), its fetch wired to
dbGhostFetch in symbolCompletion.ts; toggled live via a compartment in
BufferView.tsx. (The old model path — POST /api/agent/complete via
providers.generate — is no longer in the completion loop; the model is reserved
for the agent/orchestrator's deliberate edits.)
Language intelligence (LSP) & deeper agent editing
Status: spine implemented (diagnostics, completion, hover, go-to-definition); the rest is design. The road from "buffer over a URI source" to a real code editor. The organizing idea is three stacked intelligence layers, each with a different latency and authority — they coexist (they don't replace one another), the way VS Code runs IntelliSense and Copilot side by side:
| Layer | Source | Provides | Latency |
|---|---|---|---|
| L1 local | CodeMirror in the browser | syntax, brackets, search/replace, multi-cursor, indentation | instant |
| L1.5 DB | backend symbol index (SQLite) | prefix completions (dropdown + ghost text) from a code_symbols table | sub-ms (indexed SQL) |
| L2 LSP | backend language-server process | diagnostics, type-aware/member completion, hover, go-to-def, references, rename, format | ~10–100 ms |
| L3 LLM | backend local model | agent/orchestrator edits (read, rename, alter, format selection) — not completion | ~0.1–n s |
L1 is mostly CodeMirror's basicSetup. L1.5 is the DB symbol lookup that backs
both completion surfaces (see below) —
enriched by symdex: the package-symbol harvest projects each
indexed API's signature and first docstring paragraph into code_symbols
(doc column, source pkg:<dist>), so suggestions for framework symbols show a
doc panel (info on the completion item) from the same single SQLite request —
no embedding lookup ever sits on the keystroke path. L2 (LSP) covers the
transport plus diagnostics, type-aware completion, hover,
go-to-definition, rename, and references — with formatting layering
onto the same pipe next. L3 (the model) is no longer in the completion loop:
it drives the agent/orchestrator's deliberate edits, not typeahead.
Where the LSP runs: the backend, over a /ws lsp channel (implemented)
Same rule as the agent orchestrator and the terminal PTY (see
windowing and terminal): the
browser can't spawn pylsp/typescript-language-server, both layouts must share
one path, and with a remote backend the server must run where the files are.
The key design choice: the backend is a dumb JSON-RPC pipe, and the frontend
is the LSP client. LspManager (backend/modules/lsp/manager.py, mirroring
terminal/manager.py) spawns one server per session — chosen from a fixed
languageId → command registry so the channel can't run arbitrary processes — and
translates LSP's Content-Length framing ↔ discrete lsp-channel messages
(start/rpc/stop ↔ started/rpc/exit/error). It never parses LSP
semantics, so every future capability flows through the one pipe with no backend
change. The server is spawned with a blocking subprocess.Popen and its stdio is
pumped on a per-session daemon thread (reads relayed to the socket via
run_coroutine_threadsafe), not asyncio.create_subprocess_exec — that asyncio
API needs the ProactorEventLoop, but uvicorn runs the app on the SelectorEventLoop
under --reload/--workers>1, where it raises NotImplementedError. The thread
approach is loop-agnostic, so servers spawn automatically regardless of how the
backend was launched (the terminal PTY is already loop-agnostic the same way — a PTY
library with blocking reads offloaded via asyncio.to_thread). The frontend client lives in editor/lsp.ts (a CodeMirror extension wired
through a compartment in BufferView.tsx): it renders publishDiagnostics via
@codemirror/lint, serves textDocument/completion as a @codemirror/autocomplete
source, shows textDocument/hover in a CodeMirror hover tooltip, binds F12
to textDocument/definition (same-file jumps move the cursor; cross-file jumps open
the target via the editor's openBuffer and reveal it in the tree), and binds F2
to textDocument/rename. Request-shaped
methods use JSON-RPC id correlation; same-file detection normalizes file:// URIs
(servers vary in drive-letter case).
IntelliSense depth (implemented). Completion is a full IDE experience, not a bare
name list: each item carries a documentation pane fetched lazily via
completionItem/resolve when it's focused, and function/snippet items expand their
placeholders (insertTextFormat: 2 → CodeMirror snippetCompletion). The list
auto-opens on the server's trigger characters (e.g. . for members — captured
from the initialize response's completionProvider.triggerCharacters), matching VS
Code rather than waiting for the next word character. Both the doc pane and the hover
tooltip render markdown (code blocks, bold, lists) through a small self-contained
renderMarkdown helper — HTML-escaped first, so a docstring can't inject markup.
Completion, resolve, and hover results are cached per document version and cleared
on every debounced didChange, so re-opening a dropdown or re-hovering the same spot
doesn't re-hit the server.
Servers spawn only when installed (else the editor silently degrades); each
language maps to an ordered list of candidate servers — the first whose executable
resolves wins. An executable resolves from the backend interpreter's own scripts
directory first, then PATH. The scripts directory is not optional: the desktop
supervisor launches .venv\Scripts\python.exe directly, which puts nothing on PATH,
so a PATH-only lookup never found the dev dependency basedpyright and silently
picked a globally installed pylsp instead — whose pyflakes reports !pip install in
a notebook cell as invalid syntax, where basedpyright understands IPython lines. Python prefers basedpyright (basedpyright-langserver --stdio;
MIT-licensed pyright fork with Pylance-grade completions, hover docstrings, and inlay
hints — install with uv add --dev basedpyright) and falls back to pylsp (needs
pyflakes/pycodestyle for diagnostics) when basedpyright isn't installed. Pylance
itself is not an option — its licence restricts it to official Microsoft VS Code
builds. typescript/javascript → typescript-language-server, and rust → rust-analyzer.
Which interpreter Python resolves against. stdlib (os., …) resolves from
basedpyright's bundled typeshed, but third-party imports (torch, numpy, …) only
complete when the server is pointed at a real interpreter whose site-packages holds
them. The client tells basedpyright which one by answering workspace/configuration
(it advertises workspace.configuration and replies with python.pythonPath +
analysis knobs; other server→client requests get a null ack so nothing stalls). The
path is resolved per file: the backend (backend/modules/lsp/pyenv.py,
resolve_python_interpreter) walks up from the file for a .venv/venv (the app's venv
convention, shared with training), else the system default interpreter (the py
launcher on Windows, python3/python elsewhere — never the backend's own venv), and
sends it on the started event. The editor.pythonPath setting overrides it. The
interpreter is resolved when a buffer opens; changing the setting (or adding a venv)
takes effect on reopen.
One shared server per interpreter+project. The frontend LSP client is pooled:
buffers with the same ${languageId}::${projectRoot}::${interpreter} key share a single
LspSession (editor/lsp.ts) — one start/sessionId, so the backend spawns one
basedpyright indexed once for the whole project rather than one per file. The session
owns the transport (a single JSON-RPC id space, workspace/configuration answering) and
a document registry, routing each publishDiagnostics to the owning buffer by URI; the
per-buffer plugin is a thin adapter (its own version/caches, diagnostics rendering, and
the completion/hover/rename logic) that delegates requests to the session. Sessions are
refcounted with a 60 s idle grace period, so switching tabs — which unmounts one
buffer and mounts another — reuses the already-indexed server instead of respawning it;
the server stops once no buffer has reused it. The project root and interpreter come from
GET /api/editor/python-env (below), so files anywhere under a project pool together.
Notebook cells get the same language server
Both notebook panes — the notebook module's and training's — attach a language
server to their code cells, so a fine-tuning notebook completes against the
torch/trl in its own project venv rather than against nothing.
A notebook is one document made of cells, not N little files: import torch in
cell 1 is what makes torch. complete in cell 7. That is exactly what LSP 3.17's
notebookDocument/* notifications describe, and basedpyright implements them, so
editor/notebook-lsp.ts is a coordinator rather than a second client. One
NotebookLspDoc per open notebook owns the session and the ordered cell array; each
cell's CodeMirror view gets an ordinary lspExtension whose DocumentBinding
routes sync through the notebook instead of through textDocument/*. Panes reach it
through EditorService.openNotebookLsp and the useNotebookLsp hook — the notebook
kit stays domain-neutral and never deep-imports the editor module.
Four things here are silent when wrong — the server stays up and answers, it just answers about a document that isn't yours. All four were measured against basedpyright 1.39.9 rather than read off the spec:
- A cell document must use the
vscode-notebook-cell:scheme. Underfile:with a#cell0fragment the server accepts the notebook and then resolves nothing: no diagnostics, empty completions, no error. The fragment itself is free-form, so it carries the nbformat cell id (stable across reordering). - A cell's edits must ride
notebookDocument/didChange. A plaintextDocument/didChangeaimed at a cell URI is accepted and discarded, leaving the server analyzing the text the cell was opened with — which reads as "completions are stale" rather than as a sync bug. - Only code cells belong to the array. A markdown cell shifts every later cell's index, so a structural edit would land in the wrong place.
didOpenmust carry the real cells.fetchPythonEnvis cached per directory, so on a second open the session is ready before React has run the effect that describes the cells; opening anyway sentcells: [], and a notebook the server believes is empty resolves nothing in any of it. The cells are the trigger fordidOpen, not the session.
The pane must also hand the coordinator an absolute path. Both modules address
notebooks relatively (to the notebook root, or to a training project), but the
interpreter and project root are resolved by walking up from the file — so each pane
joins its own root first. useNotebookLsp disables itself on a relative path rather
than resolving some unrelated directory's environment.
Cells deliberately get no F12/F2: a definition or rename can land in another cell, and jumping there means mapping a cell URI back to a mounted editor the coordinator does not own. A key that silently does nothing across cells is worse than no key, so cross-cell navigation waits for the panes to expose a "reveal cell" callback. Hover still works, and the cell's docs chain narrows to the kernel source — the one thing a language server cannot do is ask the live kernel what the object actually is.
Framework auto-imports. basedpyright only auto-imports stdlib and workspace
symbols — it never indexes installed third-party libraries (a documented limitation,
unlike Pylance), so torch/numpy/pandas/… symbols aren't offered in a file until
you've imported them. The editor ships a curated framework-import completion source
(editor/pythonImports.ts) to fill the gap: typing a known symbol or alias (np, pd,
plt, nn, DataFrame, Tensor, AutoModelForCausalLM, LLM, AsyncLLMEngine, …)
offers it in any .py buffer, and accepting inserts the symbol and prepends the matching import
(deduped, skipped when already imported). It merges into the same completion popup as
the LSP and DB-symbol results but ranks below them (boost: -99), works even when no
language server is running, and is toggled by the editor.frameworkImports setting
(on by default).
Those suggestions are gated to installed packages and annotated with the version: a
backend service (backend/modules/lsp/pyenv.py, GET /api/editor/python-env) resolves
the interpreter, project root, and the installed pip versions of the tracked
framework packages — cached per interpreter, so it's computed once and shared by every
buffer. Only installed packages are suggested, and the popup shows the version
(numpy 2.2.6). The Indexed packages settings section
(editor/IndexedPackages.tsx) lists those packages × versions for the active
interpreter and persists a version snapshot (editor.indexedPackages), flagging when
the installed versions drift from it — so it's clear which library versions intellisense
is running against.
Completion is a database lookup
Typeahead completion — both the dropdown popup and the inline ghost text — is a fast prefix lookup into a symbol database, never a model. The model (the agent/orchestrator) is reserved for deliberate edits (read editors, rename, alter code, format the selection); it is not in the completion loop, so completion has no model latency.
- The index. A
code_symbolstable (symbol, lang, kind, detail, module, source, freq, doc, imp) in the built-in.data/app.dbSQLite file — the same file the library catalog uses, so theappdatabase connection can browse it. Indexed on(lang, symbol)sosymbol LIKE 'req%'is sub-millisecond (backend/modules/lsp/symbol_store.py). - What's indexed. Three corpora, all
ast-parsed and never imported:- Python builtins + keywords, seeded once.
- The whole Python standard library and the installed framework packages,
harvested by symdex into sources
std:<module>/pkg:<dist>with a real signature and first docstring paragraph. This is what makespathlib.Path,json.dumps,torch.Tensor,trl.SFTTrainer, … complete with documentation offline. Built once in the background (see Triggers). - Each open buffer's own symbols — defs, classes, params, assigned names,
imported names (
backend/modules/lsp/symbol_index.py). The client pushes a buffer toPOST /api/editor/symbols/indexon open and on a debounced idle after edits; each push replaces that source's rows so its symbols never go stale. Rows for a file that no longer exists are purged at startup, so a deleted buffer's symbols don't linger.
- The lookup.
GET /api/editor/complete?lang=&prefix=&limit=runs the ranked prefix query. Ranking is tiered — your own buffers and the builtins first, then importable indexed symbols, then indexed methods (which a bare-prefix query is almost never after) — and within a tier prefers the shallowest import path, sojson.dumpsbeatsxmlrpc.client.dumpsandnumpy.arraybeatsnumpy.core.multiarray.array. Rows are grouped by(symbol, module), so thePathinpathliband thePathinfastapi.paramsstay separate suggestions instead of blending into one. - Accepting inserts the import. An indexed row carries
imp, the module the symbol is importable from (empty for methods, which aren't). Accepting such a completion inserts the symbol and itsfrom <module> import <name>line, deduped and placed after the docstring and existing imports — the sameapplyImportmechanism the curated framework source uses, now driven by the real index. - One merged source, deduped against the server. The LSP source and the offline
sources are composed into a single
@codemirror/autocompletesource (mergedSourceinlsp.ts) rather than registered in parallel. basedpyright ships typeshed, so once warm it already offers stdlib auto-imports; the merge lets the server win any label it provides and the indexed sources fill in only what it didn't, instead of listing every stdlib symbol twice.
Division of labor: L1.5 (DB) drives identifier-prefix completion + ghost text; L2 (LSP) drives type-aware / member completion; the framework-import source adds not-yet-imported library symbols; the model does none of it.
The cold start
Spawning a language server, running initialize, and indexing a project takes
seconds. Completion requests that arrive in that window used to return nothing, with
no retry — so a freshly-opened buffer felt like it had no intellisense at all. Two
things close that gap:
- A completion request waits for a still-warming server, bounded by
editor.completionWarmupMs(2000ms default, 0 to never wait). The offline sources have already resolved, so this only delays the server's contribution. - When the session finishes initializing, the client re-opens the completion list
if the buffer is focused and the cursor is mid-word (
session.onReadyinlsp.ts), so a popup dismissed during the cold start comes back with the full results.
Intellisense settings
Declared in the editor manifest and edited on the settings page. The language-server ones are captured when a buffer opens (the LSP extension lives in a compartment reconfigured on load), so a change takes effect for buffers opened after it. The last two below reach the live completion compartment instead and apply immediately.
| Setting | Default | What it does |
|---|---|---|
editor.indexedSymbols | true | Merge the indexed stdlib/package symbols into the popup, with signatures, docstrings, and automatic import insertion. |
editor.completionWarmupMs | 2000 | How long a completion request waits for a still-starting language server before falling back to the instant indexed results. 0 never waits. |
editor.changeDebounceMs | 300 | Wait after you stop typing before pushing the buffer to the server. Lower = fresher completions and diagnostics, more traffic. |
editor.diagnostics | true | Render server errors/warnings in the gutter. The agent's editor.getDiagnostics still sees them when this is off. |
editor.hover | true | Show the server's type/documentation tooltip on hover. |
editor.pythonPath | '' | Interpreter basedpyright analyzes against. Empty auto-detects a project .venv or system Python. |
editor.frameworkImports | true | The curated framework-import suggestions (see above). |
editor.autosuggest | false | Inline ghost-text completions from the local model. |
editor.completionTrigger | auto | When the popup opens. auto opens it as you type (and on Tab/Ctrl-Space); manual keeps the buffer quiet until you ask. Tab still indents wherever there is nothing to complete. Applies live. |
editor.importCompletions | true | Complete module names and members inside import statements, including on an empty prefix. Python only. Applies live. |
A small by-URI registry (editor/lsp-registry.ts, keyed by the buffer's
workspace-file: source URI — the same key the agent edit tools
use) is the seam the agent reaches LSP through without touching CodeMirror: the live
client records its latest diagnostics there and registers a handle exposing
rename, find-references, and ghost-text grounding. A rename's
WorkspaceEdit is applied across files — the live buffer is edited in place, other
open buffers update through their controller, and closed files are loaded, edited,
and saved.
The buffer — not the file on disk — is the source of truth while open, so the
document-sync lifecycle matters. To optimize WebSocket traffic, document updates (didChange) are debounced by 300ms. However, to prevent position mismatch errors, any LSP request (hover, completion, definition, rename, references, grounding) will synchronously flush pending changes to the server beforehand. Furthermore, to avoid race conditions when the server is spawning, didOpen fetches the document's content dynamically at the moment of initialization rather than caching a stale version.
workspace-file: URIs map directly to real paths the server roots on; note: and
osfile: get no LSP (only workspace-file: buffers with a known language do). Sync
is full-text didChange (debounced 300ms or flushed on demand) — simple and correct; incremental is
a later optimization. LSP capabilities map onto CodeMirror:
completion → autocomplete source, publishDiagnostics → linter, hover → tooltip,
definition → a jump that opens a workspace-file: buffer and reveals it in the tree.
Additionally, autocomplete requests include a completion context containing the trigger kind and trigger character (e.g. .) to help the language server filter candidates accurately.
Range edits replace full-content edits
editor.proposeEdit/applyEdit today take the whole new buffer. That doesn't
scale to real files: it blows a local model's context and forces it to reproduce
code verbatim. The plan is anchored, search/replace-style edits
(proposeEdit(uri, edits: {find, replace}[]), full-content kept as a fallback). The
existing accept/decline unifiedMergeView renders them per-chunk unchanged — only
the tool payload narrows from "whole doc" to surgical edits. This is what lets the
agent edit a large file with a small local model.
Ghost text (superseded: was LSP-grounded model, now a DB lookup)
Status: reworked. Ghost text used to be a model completion
(/agent/complete via providers.generate), grounded with LSP context to reduce
hallucination. It was too slow — a full model round-trip per suggestion. It is
now a prefix lookup into the DB symbol index (dbGhostFetch in
symbolCompletion.ts → GET /api/editor/complete): the tail of the single
best-matching symbol for the token at the cursor, or nothing when there's no
confident match. No model, no round-trip. See Completion is a database
lookup. The split is now: L1.5 (DB) drives
identifier completion + ghost text, L2 (LSP) drives type-aware/member completion,
and the model drives only the agent/orchestrator's deliberate edits (below). The
/agent/complete endpoint + _grounding remain in the agent module but are no
longer wired to the editor.
The agent reading & watching the buffer
- Passive (read) — implemented: the buffer's LSP diagnostics are in
getAgentContext(the buffer snapshot'sdiagnostics) and behind aeditor.getDiagnostics(uri)read tool, so the agent sees the errors it causes and self-corrects — the highest-leverage agent-editor upgrade. 1-based line/column, plain severity. - Agent-as-LSP-client tools — implemented:
editor.renameandeditor.findReferencesbacked by LSPrename/references— correct, scope-aware cross-file edits instead of regex. Both take asymbolname (first occurrence) or an explicit 1-basedline/column. Reads (getDiagnostics/findReferences) ungated;renameis gated likeapplyEdit(inEDIT_SAFE_TOOLS, so it auto-allows underacceptEdits) — it is a language-server symbol rename, a scoped refactor, not a filesystem rename.editor.format(LSPformatting) is the remaining one. - Proactive (opt-in) — design: an
editor.agentWatchmode where eachdidChange → publishDiagnosticswith errors pings the orchestrator with the diagnostic + surrounding code; it mayproposeEdita fix (suggest, never auto-apply). Gated, off by default.
Browser vs desktop
Editing notes and workspace files is identical in both layouts. The difference is which files you can reach:
| Concern | Browser | Desktop |
|---|---|---|
| Notes | full | full |
| Workspace files | full — read/write through the backend FS API | full — same path |
| Arbitrary OS files | no (fs.nativeDialogs absent; File System Access API deliberately not used for v1) | native open/save dialogs via the shell; opened as osfile: buffers |
| Drag a file onto app | imports content as a new note | opens the file as a buffer |
Remember the layout-shell rule: with a remote backend in the browser, "workspace files" are files on the backend host.