Omniscio

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 empty SessionsSidebar fallback (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 — a DialogShell + a FormField textarea; Ctrl/Cmd+Enter submits).
  • What Build does (useFlowchartAiBuild) — createFlowchart() a fresh chart, then launchSession into __flowchart__ with the description as draftText (pre-filled in the composer) and a BUILD primer as firstSendPrefix (hidden setup context). It uses firstSendPrefix, NOT initialPrompt, 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 (buildFlowchartBuildPrompt in flowchart-spawn-prompt.ts) hands the agent the full /flowcharts CLI verb set (list / create / replace / rename / delete — "make whatever you need"), the 19 FLOWCHART_NODE_TYPES, when to use swimlanes, and the validate-and-retry-on-400 loop — and tells it to set every node to x:0, y:0 and 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.ts owns that sentinel — the geometry, the phrase the primer writes from it, and the isUnlaidOut detector (2+ nodes coincident) — so the instruction and the trigger cannot drift. When a chart arrives unlaid-out, the store's arrangeIfUnlaidOut (in flowchart-store-layout.ts, the one module allowed to import the engine) dynamic-imports flowchart-layout.ts (keeping its heavy elk dep out of the always-on startup bundle — the layout-lazy-loaded invariant), runs autoLayoutFlowchart (elk) once and mergeNodePositions the result, folded into ONE undo entry and persisted. It fires on the live FLOWCHART_CHANGED reload 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 connectToNewNode creates the node + edge in ONE commit (one undo step), opening it for rename. Wired via onConnectStart / onConnectEnd; a drop inside a lane joins that lane.

  • Snap + alignment guides — flowchart-align-guides.ts computeSnap snaps 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.ts alignNodes (6 modes) / distributeNodes (h/v) feed the store's alignSelected / distributeSelected, which bulk-apply via applyLayout (ONE undo step). The toolbar shows the cluster at ≥2 selected shapes (tracked in the transient selectedNodeIds).

  • Smart connectors — flowchart-edge-router.ts routeOrthogonal (Hanan-grid A* with a turn penalty + an obstacle/size CAP → null fallback to the simple path) routes each edge AROUND other shapes. Only the shapes in the CORRIDOR between the two ends are obstacles: corridorObstacles keeps 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 into flowchart-edge-geometry.ts (boxes, facing sides, stub points, segment-vs-box) and flowchart-edge-search.ts (the grid, the A* walk, the polyline tidy-up); the entry point still exports routeOrthogonal, Rect and Point. 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 edge data.routePoints — never persisted (model edges keep only their routing mode). 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 (in flowchart-edge-geometry.ts) answers from the two shapes' positions, and flowchart-rf-adapter.ts edgeHandlesFor turns that into the React Flow sourceHandle / targetHandle (s-bottom → t-top for a shape below another, s-right → t-left beside 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 orthogonal connector draws; a straight connector is a direct line and a curved one a bezier, chosen per edge by flowchart-edge-path.ts edgePathFor. 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.

  • 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