flowgo

Start Workspace

Create a new in-memory workspace for this session and return its workspace_id. All subsequent tool calls in this session must include workspace_id.

Share

Persist the current workspace as an immutable snapshot via the configured webhook. Returns { id, url } the agent should hand to a human.

Create Map

One-shot: turn complete .flowgo text into a public share URL. Use this when you already have (or can write) the full map in one go — skip start_workspace/add_*/share entirely. Returns { id, url }. The text must be valid .flowgo syntax (see flowgo://about); reach for the granular tools instead if you want to build a map up incrementally or read back state.

Authenticate

Link this session to the human's flowgo account, so maps you share or create are saved to it instead of being anonymous. First call returns a URL for them to open and approve in a browser; call it again afterwards to confirm, or any time to check who this session is signed in as. Reach for it when the user asks to save a map to their account, see it in "my maps", or sign in.

Get State

Read and return the entire flowgo graph (every map with its nodes, edges, texts, lines, and strokes). Call once at session start to learn what exists; for edits prefer granular add_/update_/delete_ tools over a get/mutate/set round-trip.

Set State

Replace the entire graph with the supplied object. Heavy and validation-strict — use for bulk imports or wholesale layout swaps, not for tweaking single items. Shape: { maps: [{ path, boxes, edges, texts, lines, strokes }] } (the boxes array holds the nodes — historical field name). Entity fields match the granular add_* / update_* tools. See flowgo://about for the full field reference.

Add Box

Add a node to the map at the given path. Returns the assigned id. Space nodes by at least 200px x / 80px y to avoid overlap. (Nodes were formerly called boxes — the tool name is historical.)

Update Box

Update a node's label, position, color, font size, shape, anchor flag, or explicit size. Pass 1 for palette or font to reset to default. Pass w=0 and h=0 to restore auto-sizing.

Set Default Shape

Set the document-level default shape (the `defaultshape <n>` directive): the shape a canvas double-click creates in this file. 0=rectangle, 1=hexagon, 2=circle, 3=triangle. Document-scoped — there is no path parameter.

Delete Box

Delete a node (and all incident edges plus its submap subtree).

Add Edge

Add an undirected edge between two nodes in the same map. Replaces any prior edge between the same pair. Edges only connect nodes — not text, lines, or strokes. Pass 'label' to name the relationship the edge represents.

Update Edge

Update the edge between two nodes: re-aim a handle, set the palette, or set/clear the midpoint label. Identify the edge by 'from'/'to' in either order (edges are undirected); handle args are interpreted relative to the args' direction.

Delete Edge

Delete the edge between two node ids in the same map.

Add Text

Add a free-floating text annotation (header, callout, label). Use a node instead if the item should connect to other items via edges.

Update Text

Update a text label's content, position, color, or font size. Pass 1 for palette or font to reset to default.

Delete Text

Delete a free-floating text label.

Add Line

Add a static line segment (arrow, divider, geometric shape). Use 'mids' for a polyline through control points. Use edges (not lines) to connect boxes.

Update Line

Update a line's endpoints, color, render style, or control points. Pass 1 for palette/style to reset to default. Pass null for 'mids' to clear all control points.

Delete Line

Delete a static line segment.

Add Stroke

Add a freehand brush stroke (sketchy annotation). Provide at least two [x, y] points. Prefer 'line' for structured geometry; reach for stroke only when you want a hand-drawn look.

Update Stroke

Update a stroke's color or replace its full point list (useful for translating the whole stroke).

Delete Stroke

Delete a freehand brush stroke.