Flowcharts (visual flowchart editor)
A standalone visual flowchart editor that opens as a virtual project in the sidebar: draw boxes and connectors on a canvas, organise them into swimlanes, keep a saved library of charts, and describe a chart in words to have an AI build it.
On this page
What it is
Flowcharts is a standalone visual flowchart editor inside Agent Mission Control, surfaced as a virtual project in the sidebar (it mounts the same way Decks does — a docked panel beside the projects sidebar, not a full-screen view). You draw boxes and connectors on a React Flow canvas, drop shapes from a palette, organise them into swimlanes, and keep a saved library of charts. Editing is fast: quick-connect (drag a connector onto empty canvas to spawn a connected shape), snap + alignment guides while dragging, multi-select align / distribute, and smart connectors that route orthogonally around other shapes (see Editing below). AI sessions can read and draw on the open board from a built-in Sessions tab, and a "Build with AI" on-ramp turns a one-line description into a whole chart (see Build with AI below).
A flowchart is a single graph blob: { nodes, edges, lanes }. Each chart is one
row in the flowcharts SQLite table; the whole graph is stored as one JSON
data column (charts are small, so a single-column blob is the simplest reliable
shape — it mirrors the mindmaps table).
Where to find it
How it is gated
Flowcharts is an in-development feature registered as 'flowchart' in
src/shared/unreleased-features.ts (settingKey: 'flowchartEnabled',
envVar: AMC_SHOW_FLOWCHART, status: 'in-development').
It is visible when any one of the following is true:
- The feature is marked
'shipped'in the registry (releases to everyone). - Omniscio is launched with
AMC_SHOW_FLOWCHART=1. - The user flips the Settings → Lab → Flowcharts toggle on.
No code reads settings.flowchartEnabled directly to decide visibility — the
sidebar row gate goes through isUnreleasedFeatureVisibleInRenderer('flowchart', …)
in project-visibility.ts (UNRELEASED_PROJECT_GATES), and the main-process
handlers gate on isUnreleasedFeatureEnabled('flowchart'). Doing otherwise
bypasses the env reveal path and fails the gating lint test.
Discoverability on enable
Flipping the toggle on reveals the Flowcharts sidebar row reactively — the
projects sidebar re-filters on the settings change (Dashboard's useMemo keyed on
settings), so no app refresh is needed. Omniscio also points the user to the new
row: the flowchart entry declares
sidebarLaunch: { viewId: 'flowchart', label: 'Flowcharts' }, so enabling it
fires the standard Lab-feature flash + toast, with an Open action that routes
to the __flowchart__ virtual project via the registry-driven resolver
(virtualProjectPathForSidebarLaunchViewId in useAppCustomEvents.ts). Every
gated sidebar built-in must carry such a pointer — locked by invariant J in
unreleased-feature-gating-contract.md
(guard: gated-builtin-discoverability-pointer.test.ts).
How it is mounted
Flowcharts is an amc-builtin virtual project (__flowchart__) defined once in
src/shared/integrations/flowchart.ts and assembled into the registry by
npm run integrations:reindex. Its UI manifest in
src/renderer/src/integrations/ui-registry.ts carries:
panelComponent: FlowchartEditor— the full editor shell.panelOwnsLayout: true— the panel renders its own multi-pane layout, so Omniscio suppresses the default emptySessionsSidebarfallback (same as Decks / Writer).mobilePrefersPanel: true— on a phone (Web Access mode) the panel renders in the'sessions'slot, so tapping the row lands on the editor (its internal Charts/Sessions tabs reach everything) rather than an empty session list.
FlowchartEditor assembles its own left sub-sidebar (FlowchartSidebarTabs — a
Charts | Sessions tablist), a toolbar, the React Flow canvas (wrapped in
one ReactFlowProvider), and a shape palette. Light/dark colorMode follows the
app theme via useIsDarkMode() (the dark class on <html> is the single source
of truth); the flowchart data model carries no per-chart theme override.
How it behaves
AI sessions on the board
The editor's Sessions tab is the stock session-host sidebar
(SessionHostSidebar + useFlowchartSessionHost). The SAME __flowchart__
project hosts those sessions: it is spawnable + resolver-mapped to
<userData>/flowchart-agent (SPAWNABLE_VIRTUAL_PROJECT_SENTINELS +
resolveProjectWorkDir). Selecting a session reveals its chat inside the
editor (source 'flowchart-session') rather than ejecting the user out of the
panel — mirroring the mind map's reveal. A spawned flowchart agent reads and edits
the open board through the CLI control server's flowchart routes
(cli-server-flowchart-routes.ts); an external edit emits the flowchart:changed
push so the renderer refreshes the list and reloads the open chart (preserving
undo).
It is deliberately NOT in SESSION_HOSTING_VIRTUAL_PROJECT_PATHS — that set drives
Ctrl+T / auto-select for sidebar-SELECTED virtual projects, and the Flowchart owns
its own session-open path.
Build with AI (describe → flowchart)
The headline differentiator: type a one-line description and an AI session builds the whole chart. It is NOT a bespoke generation engine — it is a regular Omniscio session (your normal per-session model picker applies) given CLI access to build the chart, so quality/cost follow your model choice and there is no separate billing path.
- On-ramp — a "Build with AI" button on the Charts empty-state + the Charts header
(
FlowchartListSidebar) opens a small "Describe your flowchart" dialog (BuildWithAiModal— aDialogShell+ aFormFieldtextarea; Ctrl/Cmd+Enter submits). - What Build does (
useFlowchartAiBuild) —createFlowchart()a fresh chart, thenlaunchSessioninto__flowchart__with the description asdraftText(pre-filled in the composer) and a BUILD primer asfirstSendPrefix(hidden setup context). It usesfirstSendPrefix, NOTinitialPrompt, so the session opens ready with the model picker — you pick a model and send, which is what preserves your model choice. The session chat reveals in place over the editor (source'flowchart-session'). A failed spawn soft-deletes the just-created blank chart (no orphan). - The build primer (
buildFlowchartBuildPromptinflowchart-spawn-prompt.ts) hands the agent the full/flowchartsCLI verb set (list / create / replace / rename / delete — "make whatever you need"), the 19FLOWCHART_NODE_TYPES, when to use swimlanes, and the validate-and-retry-on-400 loop — and tells it to set every node tox:0, y:0and let Omniscio arrange, so it spends its effort on the LOGICAL graph (nodes + edges + labels). - Auto-arrange — an LLM can't run the renderer-side elk layout, so it drops every node
on one point.
flowchart-unlaid-out.tsowns that sentinel — the geometry, the phrase the primer writes from it, and theisUnlaidOutdetector (2+ nodes coincident) — so the instruction and the trigger cannot drift. When a chart arrives unlaid-out, the store'sarrangeIfUnlaidOut(inflowchart-store-layout.ts, the one module allowed to import the engine) dynamic-importsflowchart-layout.ts(keeping its heavy elk dep out of the always-on startup bundle — thelayout-lazy-loadedinvariant), runsautoLayoutFlowchart(elk) once andmergeNodePositionsthe result, folded into ONE undo entry and persisted. It fires on the liveFLOWCHART_CHANGEDreload AND on chart open (so an agent-built chart tidies even if it wasn't open at build time); an elk OR layout-load failure falls back to the manual Auto-layout button.
Locked by the ai-build-via-session invariant in the
flowchart-feature-contract:
"describe → flowchart" stays a regular session over the CLI — never a bespoke generation /
fixed-model / cost-cap path — and the primer's 0,0 sentinel stays in lock-step with the
isUnlaidOut detector.
Ask AI on the canvas (describe, edit, pasted notes)
A second, lighter AI entry sits IN the editor: the prompt bar over the canvas
(FlowchartAiBar), opened from its button or with Alt+/ when the canvas has focus and
you are not typing in a field. It asks one model one question and applies the answer as a
single undoable change — it is a proposer, never a writer: nothing goes through the CLI
routes, nothing is pushed, and a cancelled, failed or rejected answer changes nothing.
It answers three asks:
- Describe (nothing selected) — a short description of the whole chart. The reply is a graph, laid out by the same layout pass the Build-with-AI path uses, then placed beside whatever is already on the canvas (or filling an empty one).
- Edit (shapes selected) — the reply changes only those shapes and the connectors that touch them. Existing shapes keep their position, size, colour and lane.
- Notes (the Notes source button, nothing selected) — paste meeting notes, a document or a process description and the whole text is turned into a chart. The field grows into a large box; the note body is capped at 20,000 characters and going over the cap is answered with one plain sentence under the box rather than a silent truncation. When the canvas is empty the model may group steps into swimlanes, and the generated shapes are packed inside their lane bands; with content already on the canvas the chart arrives lane-free and beside it, because lanes are only ever drawn into an empty chart.
Everything else is shared by all three asks: one model call from the main process
through the app's normal chat chokepoint (feature spend label flowchart-ai, shown in the
cost rollup as "Flowcharts AI"), a model picked from the model-registry tier, a Zod-checked
input behind the Flowcharts gate with a rate limit and a deadline, and a daily spend ceiling
checked before paying. The reply is parsed into a closed vocabulary and validated before it
reaches the canvas, so nothing partial is ever applied — an unusable answer asks you to try
again with your text kept. One Undo restores the chart exactly as it was, offered right
in the bar.
What you paste and what the chart says are data, never instructions: labels are neutralised and scrubbed before they leave the renderer, the note body is carried only inside a JSON block the system prompt declares to be data, and real shape ids never cross (only generated refs). Notes mode never edits: with shapes selected the bar stays on the edit ask. Not yet supported — recolouring, moving a shape between lanes, and restyling; those stay manual.
Locked by ai-prompt-bar-proposes-the-canvas-commits,
notes-become-a-chart-through-the-same-one-call, a-length-cap-is-a-sentence-not-a-truncation
and the rest of the prompt-bar rules in the
flowchart-feature-contract.
Editing — quick-connect, snap, align, smart routing
Four interactions make the canvas fast, each backed by a PURE, unit-tested module (no
React / store / React Flow). FlowchartCanvas.tsx is composition only: one hook per job
wires them — useFlowchartCanvasDrag (snap + drag-stop write-back), useFlowchartCanvasEdges
(the route memo), useFlowchartCanvasConnect (handle drags + quick-connect),
useFlowchartCanvasDrop (palette drop + tap) and useFlowchartCanvasFocus (fit, focus,
Enter-to-edit, reveal) — over the pure geometry in flowchart-canvas-geometry.ts:
Quick-connect — drag a connector off a shape onto empty canvas and the store's
connectToNewNodecreates the node + edge in ONE commit (one undo step), opening it for rename. Wired viaonConnectStart/onConnectEnd; a drop inside a lane joins that lane.Snap + alignment guides —
flowchart-align-guides.tscomputeSnapsnaps the dragged node's edge/center to a nearby node's (8px threshold) and returns guide segments drawn as 1px accent SVG lines in a<ViewportPortal>(onNodeDrag).Multi-select align / distribute —
flowchart-align.tsalignNodes(6 modes) /distributeNodes(h/v) feed the store'salignSelected/distributeSelected, which bulk-apply viaapplyLayout(ONE undo step). The toolbar shows the cluster at ≥2 selected shapes (tracked in the transientselectedNodeIds).Smart connectors —
flowchart-edge-router.tsrouteOrthogonal(Hanan-grid A* with a turn penalty + an obstacle/size CAP →nullfallback to the simple path) routes each edge AROUND other shapes. Only the shapes in the CORRIDOR between the two ends are obstacles:corridorObstacleskeeps the candidates whose clearance box overlaps the box the two ends span, and a shape wholly outside that box cannot be crossed by a route that stays inside it. Without that filter every other shape on the chart was an obstacle for every connector, so on anything past a few dozen shapes the router hit its own cap and quietly fell back to the un-routed path — smart routing looked switched off exactly when a chart got big enough to need it. The maths behind it is split intoflowchart-edge-geometry.ts(boxes, facing sides, stub points, segment-vs-box) andflowchart-edge-search.ts(the grid, the A* walk, the polyline tidy-up); the entry point still exportsrouteOrthogonal,RectandPoint. Routes are DERIVED + TRANSIENT: computed in the canvas (a memo keyed on a committed-geometry signature that includes each connector's routing mode, recompute on drag-stop, never per frame) and injected onto the React Flow edgedata.routePoints— never persisted (model edges keep only theirroutingmode). An edge touching the dragging node drops its route to follow live.Connector attachment — a connector leaves and arrives on the two faces that point at each other, in every style:
facingSides(inflowchart-edge-geometry.ts) answers from the two shapes' positions, andflowchart-rf-adapter.tsedgeHandlesForturns that into the React FlowsourceHandle/targetHandle(s-bottom→t-topfor a shape below another,s-right→t-leftbeside it). Those are the same faces the router anchors its route on, so the drawn path and the smart route can never disagree — and the live drag preview, which rides the same handles, follows them too. Without an explicit handle the library picks the first one it finds, which attached every connector to the top of both shapes. The handles live on the rendered edge only; a saved chart still stores just the routing mode.Connector styles — the smart route is what an
orthogonalconnector draws; astraightconnector is a direct line and acurvedone a bezier, chosen per edge byflowchart-edge-path.tsedgePathFor. Select one or more connectors on the canvas and the toolbar shows the connector-style picker (straight / curved / right-angled); the mode the selection shares reads as pressed, and one click sets every selected connector in ONE undo step (setEdgesRouting). The choice saves with the chart like any other edit.Connector labels — double-click a connector to type its text in place. Enter or clicking away saves it, Escape cancels, and clearing the text removes the label. It is drawn at the point half way along the DRAWN path (not on a corner), so it reads as centred for straight, curved and right-angled connectors alike, and it saves with the chart like any other edit. One label is one undo step.
Shape and connector colours — select shapes and/or connectors and the toolbar shows a paintbrush. It opens one palette with a row per role: Fill and Border for shapes, Line for connectors, each taken from the app's own colour palette, plus a no-colour swatch that returns the item to its themed default. One pick colours everything selected in ONE undo step. The fill is painted as a tint so the shape's label stays readable in either theme; the chosen colour paints solid as the border or the connector's stroke (and its arrow).
Locked by the smart-routes-transient + snap-and-align-pure + commit-chokepoint +
connector-label-is-editable + colours-are-palette-values-validated-at-the-boundary +
a-style-change-is-one-commit-and-targets-the-selection invariants in the
flowchart-feature-contract.
Keyboard shortcuts and clipboard
The canvas handles the shortcuts every flowchart user expects, and nothing else.
| Key (Cmd on macOS) | What it does |
|---|---|
| Ctrl+Z | Undo |
| Ctrl+Y, Ctrl+Shift+Z | Redo |
| Ctrl+C / Ctrl+X | Copy / cut the selected shapes and the connectors between them |
| Ctrl+V | Paste them, each paste nudged further down and to the right |
| Ctrl+D | Duplicate the selection in place |
| Ctrl+A | Select every shape |
| ? | Open the "Flowchart Shortcuts" sheet |
- The clipboard is the topology, not a picture. A copy takes the selected shapes plus only the connectors with BOTH ends selected; pasting mints fresh ids, rewires those connectors onto the new shapes, drops any connector that would point at a shape outside the copy, and carries a swim-lane membership only when that lane exists on the board being pasted into. The clipboard lives in the store and survives a chart switch, so a copy can be pasted into another chart. Each paste, cut and duplicate is ONE undo step.
- Typing wins. A shape label is edited in a text field that owns its keystrokes, so none of these fire mid-word, native text undo included.
- Why the shortcuts live on the canvas. They are a fixed local keymap
(
flowchart-keymap.ts), like the mind map's — not entries in the app-wide rebindable registry — so?opens a flowchart-specific sheet listing them (FlowchartShortcutsOverlay) rather than the global shortcuts overlay. The app-wide keyboard router listens on the window in the CAPTURE phase, so the canvas is registered as a pre-lookup surface owner for exactly the chords its keymap maps; every other chord (Ctrl+K search, Ctrl+1 inbox) still belongs to the app.
When someone else edits the same chart
The editor autosaves a moment after each change, and every save names the version of the chart it was edited from. If an agent or another window changed the chart first, the save is refused instead of overwriting their change: the canvas reloads to their version, a one-time notice appears, and what you had drawn stays one Undo away. The next edit you make saves on top of their version. A second change already waiting behind the refused save is refused the same way, so it cannot overwrite them either.
The autosave indicator is one polite live region: a successful save reads Saved (or Saving…), and a failed one names what happened and what to do about it rather than a bare "Save failed", so a screen-reader user learns both that the save failed and that their chart is safe to retry.
Importing a pasted Mermaid diagram
The clipboard-paste button in the saved-charts header opens Import Mermaid. Paste a
flowchart / graph diagram, optionally name the chart, and Import creates the chart,
stores it and opens it laid out — positions come from the ordinary arrange pass, exactly as
for an AI-built chart.
What it keeps: each shape's label and closest shape type, each connector's direction and label, and each subgraph as a swimlane. What it cannot keep it reports by line number in the dialog — connector line styles, arrowhead variants, undirected links, layout direction, colours and other styling, and nested grouping. Nothing is dropped silently.
The person's door and the agent's (POST /flowcharts/import) call the same main-process
service, so the same text always produces the same chart. The paste is capped at
MAX_MERMAID_CHARS (500,000) and the parsed shape/connector counts obey the validator's
own caps.
Exporting the chart, and the starting size of a new shape
The toolbar's Export menu offers four formats. JSON is the lossless graph and Mermaid is the diagram text (lossy — see the import section above). PNG and SVG are images of the chart itself.
An image export is framed on the whole chart, never on the camera: chartExportBounds
unions every shape box with every swimlane rectangle, exportImageFrame adds 40 px of
padding around that union and turns it into the image size plus the viewport transform that
puts the union in frame, and exportBackground paints the image with the nearest opaque
background-color above the canvas — the app's own page colour, so a dark-mode chart
exports dark labels on a dark page instead of light labels on a white one. The framing is
independent of the person's current pan and zoom: a shape scrolled off screen is still in the
file. A chart larger than 8192 px on its longest side is scaled down to that limit rather
than rasterised unbounded, and an empty chart reports "Nothing to export yet." instead of
downloading a blank image.
Both surfaces name the file with the same shared slugify: the editor through
sanitizeExportFilename, the CLI through GET /flowcharts/:id/export. A non-Latin title
therefore exports under the same deterministic hash-derived slug from either door, never as
flowchart from one and a hash from the other.
A shape dropped from the palette is created at the size flowchart-node-defaults.ts
gives its type — 160x96 for a decision, 64x64 for a connector, 140x64 for a plain box, and so
on — and the drop point is that shape's centre. The canvas reads the same table to centre the
drop, so what is stored and where it lands always agree.
Status
In-development (default-hidden). Ships the data model, the IPC + CLI-route
surface, the React Flow editor (canvas, toolbar, shape palette, swimlanes, saved
library) with quick-connect / snap + alignment guides / multi-select align-distribute /
smart obstacle-avoiding connectors, keyboard shortcuts with copy / cut / paste /
duplicate over shapes AND their connectors (one undo step each), Mermaid export
(lossy) and Mermaid import from a pasted diagram, AI sessions on
the board (the Sessions tab spawning into __flowchart__), and "Build with AI"
(describe → a regular session builds the chart via the CLI, auto-arranged). Reveal via
Settings → Lab toggle or AMC_SHOW_FLOWCHART=1.
Related
- Decks — mounts the same way: a docked panel beside the projects sidebar rather than a full-screen view, and the closest sibling in the sidebar.
Last verified 2026-11-07