Penstock

Guide / Draw and edit

Suggestions

Penstock suggests the element that most likely comes next, as a ghost beside a dead end, and a name, a source or an expression for a field of the properties panel, as faint text after the caret. It works from your diagram and your project, and it keeps quiet when it is not sure.

Free

What it is

Two small helpers sit in the editor. Both are suggestions, never changes: nothing happens to the diagram until you press Tab, and Esc sends the suggestion away.

Neither one asks a language model. The answer is worked out from the open diagram, the elements around the place you are at and the names used in the other files of the project, and a small ranker that ships with Penstock puts the candidates in order. When no candidate is good enough, nothing is shown. A quiet editor is the normal case, not a fault. Both are free.

These are not the AI chat. The chat talks to an agent you chose. The suggestions are part of the editor and work without an agent.

The next element

  1. Select one element that has no way out yet: a task, a gateway or an event that is not an end event, with nothing leaving it.
  2. Wait a moment, without typing, dragging or moving the canvas. If Penstock is confident, a ghost of the next element appears beside the one you selected, with a label such as Next: … · Tab to add, naming the kind of element.
  3. Press Tab to add it. The element and its flow are added in one step, so one undo takes them back, and the new element is selected.
  4. Press Esc to dismiss it. Penstock does not offer it again for that element.

Typing in a field, a drag, a zoom or a pan puts the ghost away, and a selection of more than one element, or of a flow, shows none. The suggestion follows the engine of the folder, so a Camunda 8 diagram gets Camunda 8 elements, and it follows the modelling conventions of the project. A screen reader hears Suggested next: …. Press Tab to add it, Escape to dismiss.

Ghost text in a field

Click into one of these fields of the properties panel. After a moment a faint suggestion appears after the caret.

FieldWhat is suggested
A result variable, an output mapping target, an output parameter name, a data output nameA name for the variable the step writes.
The source of an input mapping on Camunda 8, or of a call activity's in-mappingA variable that the step can read. On Camunda 8 it can also be an expression, when the names point to a conversion.
The source expression of a call activity's in-mappingAn expression for the value that the target name asks for.

Press Tab to take it and Esc to leave it. Keep typing and it adjusts or goes away.

Press Alt+Shift+E to see Why this suggestion: the value, where it came from, its likelihood in percent, and the reasons in words, such as shares its words with the name or read by a later element. Where it comes from is one of:

A fact of the codeA name or a type the code of a worker or a delegate tells. See Code links.
Found in the projectA name another diagram or file of the project already uses.
Composed from the names of the diagramBuilt from the words of the element and its neighbours.
An expression, checked on the sample valuesA conversion the names point to: a unit change such as dollars to cents, a whole number of minor units, an ISO 8601 duration, a number read from text or a text written from a value. It is tried on sample values before it is offered.

Turn them off

Each helper has its own switch in the editor's settings: Suggest the next element and Suggest names, sources and expressions. Some tools add at dead ends and for fields to the labels. They are kept in ~/.penstock/preferences.json as suggestNextBlock and suggestions, which are on unless set to false. With the first off, Penstock draws nothing and does not read the other diagrams of the project to find a next element. With the second off, nothing is asked for a field. In VS Code each one is also a command in the command palette, Stop suggesting the next element at dead ends and Stop suggesting names, sources and expressions for fields. The switches belong to you, not to the project.

What you see

Common problems

No ghost appears beside a dead end.
Penstock is not sure enough, or the element is an end event, already has a flow out, or you are still moving. A diagram with few elements and a project with no similar diagrams gives it little to go on. It also needs the helper to be on, in the settings.
No text appears in a field.
The field is not one of those in the table, Penstock has nothing it is sure of, or the suggestions are off.
I pressed Tab and the focus moved on.
There was no suggestion to take. Tab adds a suggestion only while one is shown. On the canvas it needs the canvas to have the focus, not a field.
I want a bigger change than one element.
Ask the AI chat. Its proposed changes are drawn on the canvas as ghosts that you accept or reject.