Graph & code views

Open any .aether file and the flow editor gives you three tabs above the canvas. All three look at the same file; pick whichever fits the task.

Graph

The default view: your flow as cards connected by edges.

• Reading a node. The colored stripe on its left edge tells you the type (every node type has its own color), and the card shows a summary: method + URL for a request, the first line of code for a script, and so on.
• Reading the rings: after a run, a green ring means passed, a red ring means failed; a pulsing node is currently running. A brass ring just means it’s selected.
• Badges. ⤓ name marks a node that captures a variable; ⚠ marks a node that references a variable with no value yet (see Variables & environments).
• Select a node by clicking it, and the inspector on the right fills with its details.
• Move a node by dragging. The position is stored in the file (under the node’s ui.position), so the layout travels with the flow and survives commits.
• Add nodes from the right-click menu. Pick a type and it arrives prefilled with a working template. Choosing Subflow… opens a picker listing every .aether file in the workspace.
• Pan and zoom with the mouse. Tidy re-lays every node out left to right; if you didn’t want that, an Undo tidy button appears in the corner and puts the positions back.
• Opening a flow selects the start node and, if it’s off screen, brings it into view. The card carries a Start badge, so “where does this begin” is answered before you’ve clicked anything.
• Edges come from each node’s routing fields (next, then/else, body, branches). Condition branches are labeled true/false, loop bodies loop body with an after loop edge, parallel fan-outs branch with a join edge after them. Edges run straight when the two ports line up and step around each other when they don’t.

The canvas controls

A labelled control cluster sits in the corner: zoom in and out, zoom to fit, zoom to selection, reset to 100%, and a zoom percentage you can type into. Beside them are five toggles, remembered per machine rather than written into the flow:

The outline is worth knowing about even if you never turn it on by choice: a minimap is a picture of positions, which is worth nothing to a screen reader, so the outline is the canvas’s non-pointer overview.

Box select does not have to be on. Shift and drag draws a marquee in either mode, and Space and drag pans in either mode, so neither gesture is ever unreachable.

Dragging a single card shows alignment guides against the cards it lines up with, with a soft snap onto them. Dragging a multi-card selection does not, because snapping one card of a group would shear the group apart.

Finding a node in a large flow

• The filter (the / key, or its button on the canvas) dims everything that does not match rather than hiding it, so the shape of the flow stays readable while you search inside it.
• F4 jumps to the next failed node after a run, ⇧F4 to the previous one.
• ⌘⇧O opens a node picker for the active flow.
• The breadcrumb trail under the tab strip tracks the selected node.

The canvas is also fully keyboard drivable, with the arrow keys moving between cards spatially. The full list is in keyboard shortcuts.

Editing the topology on the graph

You can wire the flow with the mouse. The routing fields in the YAML are what actually change, so the file stays the single source of truth and the canvas redraws from it.

• Connect two nodes by dragging from a port on the right edge of one card onto another card. Most node types have one port (next). The branching types have two, each labeled, and the port you drag from decides which field gets written:

  Node type	Ports	Writes
  condition	T / F	then / else
  loop	body / after	body (the per-item subgraph) / next (after the loop)
  parallel	branch / join	appends to branches / next (the join)
  everything else	one unlabeled port	next

  Dragging a new edge from a single-target port replaces what was there; branches appends. Connecting a node to itself, or re-making an edge that already exists, is refused at the gesture.

• Delete a selected node or edge with Backspace or Delete. A confirm names exactly what’s going: “Delete node “login” and 2 connections? Anything routing to a deleted node is re-linked to what it pointed at. Nothing is written to disk until you save.” Re-linking is the part worth knowing, because deleting a middle step doesn’t strand the ones after it. A flow must keep at least one node, so deleting the last one is refused.

• Duplicate a node from its right-click menu. The copy gets a fresh id, a … copy label, and lands offset from the original with no routing attached; a copy that inherited next would silently run twice.

• The same right-click menu also has ▶ From here, ▶ Only this node, breakpoint toggle, Reveal in Code, and Copy node id.

• Undo any of the above. A delete, connect or duplicate drops an Undo delete / Undo connect / Undo duplicate button in the corner, separate from Tidy’s own undo, so you don’t have to close the file unsaved to get back to where you were.

Everything here is an edit to the .aether file like any other. Nothing reaches disk until you press ⌘S, so a wrong drag costs you a close-without-saving at worst, or you can undo it on the spot. Switch to the Code tab to see exactly which line changed.

Code

The whole file in a full-featured code editor: syntax highlighting, the works. Anything you can do on the graph you can do here, plus things the graph has no gesture for (reordering nodes in the file, copy-pasting a node between flows).

One caveat worth knowing before you rely on it. Comments you write here survive saving from the Code tab, but a structured edit made anywhere else rewrites the file from the parsed flow, so comments, YAML anchors and your own key order are lost at that point. That means any edit on the graph, and any change made through the node inspector’s fields. If you keep notes in a flow, keep them somewhere the round trip cannot reach, such as a description: on the node or a README beside the file. Preserving comments through a structured edit is planned and not yet built.

If you type something the parser can’t read, a red banner appears with the error, and Run and Heal… are disabled until it’s fixed. The graph never renders a guess.

Mid-edit, YAML is invalid more often than it’s valid, so the canvas keeps the last version that parsed rather than blanking. It dims and takes a Stale badge saying it’s showing the last graph that parsed, and the banner adds that the graph below can’t be edited until the error is fixed.

While it’s stale you can still pan, zoom, select nodes and set breakpoints; what’s switched off is anything that writes: dragging nodes, connecting, deleting, Duplicate, Tidy. The file is the only writer, so a gesture derived from a stale parse would overwrite whatever you were typing. Fix the error and the graph goes live again.

Parsing while you type is debounced by about a third of a second, so the graph doesn’t flicker between valid and invalid on every keystroke. Anything that replaces the whole file (opening it, a change on disk, a graph edit being written back) parses immediately.

Completions

The editor completes the two things it can only learn from the file in front of it.

Type next:, then:, else:, body:, or an item under branches, and you get the ids of every node declared in the buffer, including one you’re still typing. Type ${{ and you get env. and variables.; pick one and the list reopens with the names under it. Under env. that’s the keys in your workspace .env plus anything the flow already references, and each entry says which it is, so a name that shows up as referenced in this flow rather than .env is usually a typo you haven’t noticed yet.

Completions are scoped to .aether files. A plain .yaml in another tab never gets them, and a GitHub Actions workflow is the reason why: that format has its own ${{ }} and its own env, so offering flow variables inside one would be actively wrong. Where nothing file-aware applies, the editor’s ordinary word suggestions take over rather than a guess.

Separately, there’s optional AI ghost text: a dimmed suggestion inline as you type, accepted with Tab. It’s off by default, behind ai.inlineCompletion in settings.json. While it’s off nothing leaves the process, not one character. Turned on, it sends a few KB of buffer around your cursor to whichever provider you’ve configured, on a pause in typing, billed to your own key. What crosses the network boundary and when is listed in full on the security page.

Split

Graph and Code side by side over the same file; drag the divider to rebalance. Edit the YAML on one side and the graph redraws on the other as you type. Handy when you’re wiring routing by hand but want to keep an eye on the shape of the flow.

Want it distraction-free? The ⤢ button in the tab strip toggles Zen mode, which hides the toolbar and the inspector and leaves just the Graph/Code/Split switcher and the canvas. Esc brings the chrome back.

Run results aren’t a tab: nodes light up on the graph as they run (see Reading the rings above), a selected node’s outcome lands in the inspector’s Result sub-tab, and older runs live in the History tab of the bottom panel.

The toolbar

Above the tabs: Save (⌘S; the dot on the tab marks unsaved changes), Heal… (check the flow against your OpenAPI spec), and the brass ▶ Run button (⌘⏎ or F5).

If the file changes on disk while you have unsaved edits (a git pull, another editor), a banner offers Reload or Keep my edits. Nothing is overwritten without asking.

Working with tabs

Every open file is a tab. ⌃Tab/⌃⇧Tab or ⌘⌥→/⌘⌥← cycle through them, ⌘1 to ⌘9 jump by position (9 = last), and ⌘W closes the active one.

Next: Run a flow and debug failures covers what happens when you press Run. For the YAML the Code tab is showing you, read the .aether file; for the panel on the right, the node inspector.