The browser app¶
vibe-sketch serve serves the app and the API it uses from one address,
http://127.0.0.1:8766/ by default, or the next free port when another
service has that one; the address is printed when it starts. The desktop
shell (electron/) shows the same app in a native window.
Documents¶
Each window works on one document held by the server. The address bar
carries its id (?doc=…), so a reload returns to it.
Action |
What happens |
|---|---|
New |
A new, empty document. |
Open… |
A new document from a QVF ( |
Import ▾ |
Adds structures to the current drawing, to the right of what is there: from SMILES, a name or a file. |
Save (Ctrl/Cmd+S) |
Downloads the document as QVF, the vibe family’s format (as |
Export ▾ |
SVG, PNG, MOL, SDF, RXN, SMILES, InChI or KET, rendered or written by the server. |
Save and Export first synchronize pending drawing edits with the server. If that update fails, the action stops with an error and keeps the local drawing. Retry Save or Export when the server recovers; it sends those edits again before producing a file. A revision conflict still reloads the newer server document and reports that the conflicting local change was not applied.
Drawing¶
The canvas is Ketcher’s, with its own palettes: bonds, chains, wedges and charges on the left, with the reaction plus, the arrows and text; elements and the periodic table on the right; rings and the structure library, with functional groups such as Et, OEt, Ph and Boc, along the bottom. The arrow menu has curved arrows for mechanisms, for an electron pair and, with the half head, for one electron.
If the canvas loads in a hidden pane, it fits the drawing when the pane first becomes visible. The zoom percentage follows that fit; later resizing keeps the zoom you choose.
Clean up (Ctrl/Cmd+Shift+L) gives every molecule standard bond lengths
and angles and keeps how it was drawn: where it sits, which way it points and
which way each chain turns. Wedges stay on the bonds they were drawn on where
that keeps the stereochemistry; a molecule whose stereochemistry would change
is left as drawn and named in a notice. Clean-up runs on the server, so the
CLI (vibe-sketch clean) and agents get the same result, and Undo takes it
back.
?palette=compact in the address shows vibe-sketch’s own small palette
instead of Ketcher’s.
What the server reads from the drawing¶
Every change you draw reaches the server half a second later, and the server derives the document’s species and reactions from it (see the document format):
Species are the distinct molecules, identified by InChIKey. A species keeps its id, compound number, name and multiplicity when you redraw it.
Charge is the sum of the formal charges. Multiplicity starts from the radicals you draw and is checked against the electron count; set it in the panel when the drawing cannot know it, for example for a metal centre.
Reactions come from the straight arrows, pointing any way. With one arrow, a molecule behind its tail is a reactant, one ahead of its head a product, and one beside it a reagent. With several, as in a mechanism, each arrow takes the nearest molecule behind its tail and ahead of its head, together with what a plus sign joins to it and what is drawn close beside it, such as a base next to the C–H it attacks; a molecule beside an arrow is that arrow’s reagent. Steps follow the molecules they share, then the reading order. Curved arrows (electron pushing) and crossed-out arrows are part of the drawing, not reactions. Text beside an arrow becomes its condition lines; a short number under a molecule becomes its compound number.
What cannot be a single structure, such as a polymer bracket or an R-group, stays in the drawing and is listed under Notes instead of being guessed.
Cleanup scope and vibe-view¶
vibe-sketch specialises in 2D molecular drawing and reaction graphics for papers. Basic geometry preparation stays here too: the existing 2D cleanup and 3D embedding are described on this page. Reference-database bond lengths and angles plus FIRE cleanup are planned extensions, not available controls yet. See the shared scope decision for the requirements and implementation status. Detailed 3D atom/group dragging and structure work belong in vibe-view; both programs retain input, drawing and calculation workflows.
3D structures¶
Each species card shows its 3D structure, if it has one. Generate 3D in the Species heading makes one for every species that has none; Generate or Redo on a card does it for that species. The geometry comes from RDKit’s ETKDG distance geometry and is optimised with MMFF94, or with UFF where MMFF94 has no parameters, and the lowest-energy result of several is kept in the document. It stays there while the structure, its charge and its multiplicity stay the same.
The drawn stereochemistry is checked on every structure: R/S and E/Z must come back from the 3D coordinates, or that structure is not used. A stereocentre the drawing leaves open is named in a notice, because the 3D structure has to pick one. A species no force field covers, as most metal complexes, keeps the distance-geometry structure with a warning: check its metal centres before using it.
In 3D, in vibe-view¶
With vibe-view at hand, each species card has a button that shows the species in vibe-view, the family’s 3D viewer, as a QVF of its own (its structure, charge and multiplicity), generating the 3D structure first when needed:
Send to vibe-view when vibe-view started vibe-sketch from its Sketch button: the structure goes back through vibe-view’s hand-off.
View in 3D when vibe-view is installed:
vibe-view openopens it.
The CLI does the same with vibe-sketch view DOC --species ID [--embed].
Inputs¶
The Inputs section under the species writes calculation inputs for the whole drawing: choose the program (ORCA, or a vibe-qc script), the task, the method, the dispersion correction, the basis set, RIJCOSX, a solvent and the resources, tick the species, and press Write inputs. Species without a 3D structure get one first, kept in the document; then the server’s writer makes one input per species and the browser downloads it, or a zip of them all. A species the writer refuses, such as the proton in a mechanism, is named in a notice with the reason. The form remembers its settings in this browser. See input writers for what each field may hold.
Submit to vibe-queue sends the same inputs to vibe-queue instead of
downloading them, when it is installed (the queue extra), its daemon runs
(vq daemon run in a terminal, or its installed service) and it can run the program: ORCA registered with
vibe-queue as the program orca (an absolute path to the binary), vibe-qc as
a program vibeqc (its venv) or importable beside vibe-sketch. The jobs and
their runs are recorded in the document, so a saved file knows its
calculations. The Calculations section lists each run with its state,
refreshed every few seconds while any is running, and cancels a run that has
not finished.
Names¶
Names come from vibe-qc’s naming engine, which vibe-sketch checks before showing: it maps the engine’s name back to a structure, through the engine’s 3D structure for the name and through its SMILES, and compares the result with the drawing.
Shown |
Meaning |
|---|---|
name with verified |
The name maps back to the drawn structure. Names carry no R/S or E/Z yet. |
engine suggests: … |
The engine cannot map its name back, so the name is unchecked. It is a suggestion, not the species’ name. |
no name: did not match |
The engine’s name describes a different structure and is withheld. |
no name: ions and radicals |
The engine takes no charge or spin yet. |
name with yours |
A name you gave through the API. |
Working with an agent¶
See also working with agents for the MCP tools.
An agent can edit the document you have open through the REST API, for example importing a structure or setting a compound number. The app picks up the change within a few seconds and says who made it. Every write names the revision it is based on, so neither side silently overwrites the other: a write based on an old revision is refused, and the app reloads the document.