The browser app¶
vibe-sketcher 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 while that server session
is running. This is not a saved-file address: save or download the document
before stopping the server. A newly opened browser file is uploaded into the
session; ordinary browser Save downloads a copy rather than overwriting the
file you selected in the browser’s file picker.
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. The server prepares the export; for scheme PNG, the browser rasterizes the server’s SVG. |
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.
Files in the desktop app¶
File → Open, Open Recent, the app’s Open… button, dropping a file on the window or Dock icon, and opening a file from the operating system all use the same import path. QVF files from other vibe programs work too. Recent files and the window title update after the document opens successfully.
Desktop Save (Ctrl/Cmd+S) writes back to the opened file in its existing format. Save As… (Ctrl/Cmd+Shift+S) chooses another destination; a new sketch asks for one on its first save. QVF is the default when qvf-writer is available, otherwise VSK. Both retain the whole document. Structure formats such as MOL and SDF retain only what those formats can represent; use Save As to keep jobs and other sketch metadata in QVF or VSK. Save never writes CDXML or XYZ back, so a ChemDraw original is not replaced by what vibe-sketcher read of it; Save As keeps the imported document as QVF (the native format). Export ▸ CDXML writes a copy for other drawing programs.
If the file changed outside vibe-sketcher since it was opened or last saved, Save is refused and the file keeps the other program’s change; reopen it, or download this version under another name (see Security and input bounds).
For imported QVF results, Save automatically opens Save Sketch Copy
with a different suggested filename, such as result-sketch.qvf. The sketch
keeps their structures, but does not retain calculation payloads such as
wavefunctions, frequencies or trajectories. Choosing the original result in
the dialog still refuses to replace it. After saving a copy, subsequent saves
use that copy. Cancelling keeps the original destination and unsaved revision.
Native sketch QVF files can be saved in
place; archives with unknown data, additional metadata or damage are protected
and require another destination.
Saving through a symbolic link preserves the link and uses the format selected
by its filename. QVF overwrite protection applies if either the selected name
or the link’s target has a .qvf extension.
The desktop waits for drawing synchronization and saves a fixed revision. If the file changes outside the app, saving refuses to overwrite that change: reopen it or use Save As. Failed exports and cancelled dialogs leave the existing file and save destination intact. An unsaved revision is shown beside the filename, and opening another file asks before leaving unsaved changes. File errors appear in the app. Ordinary browser sessions retain their download behavior; desktop filesystem paths never become HTTP API inputs.
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. The compact palette has the rectangle, ellipse and line shapes too; see shapes and TLC plates.
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-sketcher clean) and agents get the same result, and Undo takes it
back.
Each reaction card can map its atoms for a reaction path: the reaction centre is marked on the canvas, an ambiguous mapping offers its equally cheap pairings, a pair selected on the canvas can be pinned, and Write NEB inputs downloads ORCA or vibe-qc inputs. See reaction paths.
Tidy scheme lays the whole reaction scheme out the way papers draw it: molecules cleaned and centred on their arrows’ line, reagents above each arrow, conditions below, compound numbers under their structures, the steps in the order you drew them. A long sequence turns down and runs back. It is never automatic, it keeps every reaction, and Undo takes it back; a scheme it cannot lay out is left as drawn with a notice saying why. See Tidy scheme. The cleanup guide describes the reference conventions, quality checks and fallback limits.
?palette=compact in the address shows vibe-sketcher’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.
Two drawn copies of the same molecule can share one species card. Selecting all species for input generation therefore does not create a calculation for every visual copy. Repeated fragments also do not define reaction coefficients. Check the panel’s actual species and roles before preparing inputs.
Removing a species removes jobs that refer to it from the sketch, with a warning; it does not stop already submitted calculations. Save a copy before making chemical changes when you need to preserve the original job history. See species identity.
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. Figures still draw a repeat unit, copolymer or other bracketed group in its brackets, and an R-group core with its definitions; see polymer repeat units and R-groups. A contracted abbreviation such as Ph or Boc is still one structure with all its atoms; see abbreviations.
Cleanup scope and vibe-viewer¶
vibe-sketcher 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-viewer; both programs retain input, drawing and calculation workflows.
Stereodescriptors¶
Each species card lists its CIP descriptors, for example
stereo (R) at C2, (E) at C4=C5, with atoms numbered in the species’ own
order. They come from RDKit’s implementation of the revised CIP rules
(Hanson et al., J. Chem. Inf. Model. 2018), not its older approximation, so
pseudo-asymmetric centres are r/s and the drawing, figures and every
interface agree. A stereocentre or double bond drawn without a
configuration, or drawn as “either” on purpose, is listed as undefined:
a check, not an error, since a racemate or an unknown geometry is drawn so.
Enhanced-stereo groups (AND, OR) are listed with their atoms.
Label R/S, E/Z in the Species heading writes the descriptors into the drawing, where the canvas shows them as “(R)” and “(E)”; Clear labels removes them. The labels are a snapshot: after an edit that changes a structure’s stereochemistry, its card warns that the labels no longer match until you label again. Figures never use these stored labels; see stereodescriptors in a figure.
vibe-sketcher stereo scheme.vsk
vibe-sketcher stereo-labels scheme.vsk # --clear removes them
The SDK is vibesketch.chem.cip.stereo_labels and
vibesketch.document.stereo (stereo_report, with_stereo_labels,
stale_labels).
Stoichiometry¶
Each forward or equilibrium reaction card has Amounts: a row per participant where you enter, as in a lab notebook, one of an amount in mmol, a mass in mg, or a volume in mL together with a density (g/mL) or a solution’s concentration (mol/L); or equiv alone. A stoichiometric coef. other than one goes in its own column. Save amounts stores what you entered in the document, and the table under it shows what follows:
n = m / M for a mass, n = V·ρ / M for a neat liquid and n = V·c for a solution, in mmol, with the molar mass of the species card;
the reference, the first reactant with an amount, and every participant’s equivalents n / n(reference); equivalents entered alone give n = equivalents × n(reference), and a density or concentration given with them gives the volume to measure out;
the limiting reactant, the smallest n / coefficient among the reactants (reagents drawn at the arrow are not consumed);
for each product, the theoretical amount and mass, and with an entered amount the isolated yield;
for a half-reaction, its electrons: their amount from the limiting reactant and the charge passed, Q = n(e⁻)·F (electrode reactions).
A coefficient drawn before a participant, as in 2 H₂O, is used unless you enter one other than one.
Nothing is read from the drawing: a participant you leave empty stays empty. Redrawing keeps the amounts of the species still in the reaction and notes any that were dropped. Table downloads the worked table as CSV (full precision, units in the column names), Markdown or a booktabs LaTeX fragment (three significant figures).
vibe-sketcher amounts notebook.vsk r1 --amount m1:mass_mg=2000 \
--amount m2:volume_ml=5,density_g_ml=1.08
vibe-sketcher stoichiometry notebook.vsk r1 --format markdown
The SDK is vibesketch.document.stoichiometry (with_amounts,
stoichiometry, stoichiometry_table); REST and MCP are listed with the
other commands.
Elemental analysis and descriptors¶
Each species card shows its elemental analysis as the line for an
experimental section, Anal. Calcd for C9H8O4: C, 60.00; H, 4.48., and a
row of calculated estimates: Crippen logP and molar refractivity (Wildman
and Crippen, 1999), the topological polar surface area (Ertl, Rohde and
Selzer, 2000; N and O only), hydrogen-bond donors and acceptors as Lipinski
counts them, and the rotatable bonds. These are RDKit’s values and are
estimates, not measurements.
The analysis line gives carbon, hydrogen, nitrogen and sulfur, the elements
a combustion (CHNS) analyser reports, to two decimals; the full mass percent
of every element, in Hill order, is in the species report and the CSV
table. Percentages use standard atomic weights, and an isotope label’s own
mass, which the formula then shows ([13C]H4O). For an ion the formula and
percentages are the ion’s: draw the counter-ion as well to get the salt’s.
Place beside the analysis puts the formula, the molar mass and the analysis line as text under the structure, and under its compound number if it has one; the structure does not move, and the text is an ordinary text in the drawing that you can move, edit or delete. Property table under the species downloads every species’ formula, masses, analysis and descriptors as CSV (full precision, with the mass percent per element as JSON), as Markdown, or as a booktabs LaTeX fragment.
vibe-sketcher properties scheme.vsk --format markdown
vibe-sketcher property-text scheme.vsk --species m1 --field formula --field analysis
property-text takes --field from formula, mass, analysis, logp
and tpsa. The SDK is vibesketch.chem.analysis (elemental_analysis,
descriptors) and vibesketch.document.properties (property_table,
with_property_text); REST and MCP are listed with the other
commands.
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-viewer¶
With vibe-viewer at hand, each species card has a button that shows the species in vibe-viewer, 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-viewer when vibe-viewer started vibe-sketcher from its Sketch button: the structure goes back through vibe-viewer’s hand-off.
View in 3D when vibe-viewer is installed:
vibe-viewer openopens it.
The CLI does the same with vibe-sketcher view DOC --species ID [--embed].
Standalone launches use a free loopback port, so an existing viewer can stay
open. The action waits up to 45 seconds for the new viewer’s ready message.
If it exits or times out, the error includes the startup diagnostics and a
local .launch.log path beside the exported structure in the cache. Only a
failed new process is stopped; existing viewers and the handoff are preserved.
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-scheduler sends the same inputs to vibe-scheduler 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-scheduler 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. Choose submit scope to compute the checked species, one
reaction, or the whole scheme. Reaction and scheme submissions include each
distinct participant once, including reagents; they ignore the species
checkboxes. Write inputs continues to use the checked species.
The Calculations section groups runs by submission, showing the group ID, the number finished and the count in each state, alongside the individual runs. It refreshes every few seconds while any run is unfinished. Cancel group cancels that group’s unfinished runs; completed, failed and other terminal runs remain untouched. Runs whose queue status is unknown are left unchanged. Individual runs can still be cancelled. Older runs without a group appear under Ungrouped runs with individual cancellation only. A finished group can contain failed or killed runs: its state counts distinguish these from successful completion.
The Submit button follows the selected program: changing from ORCA to vibe-qc, or back, updates its availability immediately. When disabled, its hint explains whether the daemon is stopped or the selected program needs to be registered.
For verified output import, explicit coefficients and energy figures, see Results and reaction energies.
Names¶
Names come from the optional standalone vibeqc-naming package; the
quantum-chemistry core is not required. The adapter supplies the drawing’s
explicit bonds, hydrogens and RDKit-assigned stereo descriptors to the naming
engine. It then checks the suggested name by mapping it back through the
engine’s SMILES and 3D-structure lookup and comparing with the drawing.
R/S and E/Z names are supported within the engine’s vocabulary. For a drawing with specified stereochemistry, matching connectivity alone is insufficient: the returned structure must match its full stereochemical identity to verify the name. See naming setup.
Shown |
Meaning |
|---|---|
name with verified |
The name maps back to the drawn structure, including specified stereochemistry. |
engine suggests: … |
The name could not be fully verified, including when only connectivity matches a stereo-defined drawing. It remains an unchecked suggestion. |
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. |
no name: not installed |
The naming engine is missing; hover over the text for how to add it. The self-contained desktop app cannot name species (see what the app leaves out). |
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. Drawing and species edits name the revision they are based on. An edit based on an old revision is refused, and the app reloads the document; read the notice before reapplying your change. See REST revisions for the precise contract, including save and close operations.
Named reactions¶
See the compound, fragment and named-reaction library for the searchable picker, editable examples, explicit unfinished scaffolds, source coverage and matching SDK, CLI, REST and MCP operations.