Penstock

JetBrains / Using it

The Penstock tool window

The Penstock tool window shows your project as a tree of processes, workers, messages, decisions and forms, lists the chats of the AI agent under it, and runs the command line for you.

Free Some parts need Pro

What the tree contains is described once, for every tool, in Your project as a model. This page is about the IDE: where it is and what its buttons do.

Open it

  1. Click Penstock in the tool window bar on the left of the IDE.
  2. The tree lists your project. Double-click a node to open it. On a diagram element, it selects the element on the canvas.
  3. Right-click a node for its actions. The menu always starts with Open, and ends with the command-line actions.
  4. Type to search the tree.

When the project has no diagrams the tree says No diagrams in this project and offers Start from an example. See The example project.

The window is anchored to the left stripe of the IDE. The first-run tour points it out. Its icon is a rounded diamond with a plus, drawn at the stroke of the IDE's own tool window icons in both the compact and the standard mode, light and dark.

What the tree holds

Each node below is shown only when the project has something to put in it. Opening a node selects the element on the canvas, or opens the code.

Start from an exampleOnly in a project with no diagrams. Camunda 8 order process and Camunda 7 order process. A confirmation dialog, then the files are written, and a notification says where.
DebugWhile the debugger is stopped in a worker, a delegate or a listener: Paused at the task, and Active for the other active elements of that instance. It empties when the program resumes. Pro.
CodeWith Pro, what the code links give. Without it, a line that offers Buy or Sign In….
Migrate to Camunda 8Every file with its status (ready, converts, needs work, blocked), its findings, and the Java code with what each class becomes. It comes first when the project has Camunda 7 files to migrate.
ProcessesEach process with its elements, the processes it calls and the ones that call it, and its tests with how much of it they cover. A process that has scripts or expressions in its elements has a Scripts branch, with a count: each script or expression by the element that holds it. Opening one opens it in its own tab. See Scripts in their own tab.
TestsEvery process test, by class. Run or debug any of them, a class or all.
WorkersEach job type, topic, class and bean, with the code that implements it. A worker nothing implements is marked, once the project implements any of them. Check Workers on… is on this node.
Element TemplatesThe element templates of the project, with the worker each came from. A template whose variables no longer match its worker is marked. Each offers Create Job Worker… (Spring), Create Node Worker… and Create Python Worker….
VariablesEach variable, who sets it and who reads it, in the diagrams and in the code. A name nothing sets is marked, and so is one a letter away from a name that is set.
MessagesEach message name and the elements that send and catch it.
ErrorsEach error code, who throws it and who catches it. One that is thrown and not caught, or caught and never thrown, is marked.
DecisionsEach decision, with the tasks that call it. A decision a task names and the project does not have is listed as missing.
FormsEach form, with the tasks that use it. A form that is named and not in the project is listed as missing.
DeploymentThe profiles, with the address of each and when you last deployed to it.
FilesEvery diagram file, by folder or in a flat list.

Group by Files turns the tree round: file by file, each with its processes, decisions and forms, then Deployment. The nodes for code, tests and workers are only in the other view.

The toolbar

Run PenstockA menu of command-line actions: Check, Scenarios, JUnit Tests, Code, Docs, Format, Diff Since…, Export… and Doctor. Each runs penstock on the selected file or folder and shows the output in the Run window. Scenarios lists the ways through each process (scenarios list). Format rewrites the files (fmt --write), as do JUnit Tests and Docs, which write what they generate. Diff Since… asks for a commit, branch or tag to compare with. Export… asks for a folder and a format, SVG or PNG; SVG needs nothing and PNG needs puppeteer in the project. It uses the project's penstockw when there is one, and npx @kern0x1b/penstock-cli when there is none, which downloads the command the first time. It runs only in a trusted project. Scenarios, JUnit Tests, Code and Docs need Pro.
Reload from DiskRe-reads the project from disk. The tree also refreshes by itself when a file changes.
Run All Process TestsRuns every process test. Shown when process tests exist. Pro.
Group by FilesTurns the tree round: file by file, with each process's elements and what runs them. A toggle.
Show FoldersSwitches between a tree of folders and a flat list. A toggle.
Open penstock.yamlOpens the project's configuration, or creates it when there is none.

Whether the view is grouped by files, and whether it shows folders, are kept in ~/.penstock/preferences.json.

Chats

When the AI chat is on, a Chats section sits under the tree. It lists the chats of the project, the same ones in every editor, and each row shows the title and one word of state: working while the agent runs, waiting for you while it asks a question, the time when it is idle, or the reason when it failed. Clicking a row, or pressing Enter on it, opens the chat in the Chat tab of the Penstock editor you have open. With none open, Penstock opens the last diagram the chat took part in, and when there is none a notification says to open a diagram to continue the chat in its editor. The divider between the tree and the section can be dragged, and the IDE remembers where you left it.

New chatThe + in the heading of the section starts an empty chat.
AI agentsThe gear beside it opens Settings | Tools | Penstock | AI agents. See Settings in the IDE.
Rename, DeleteIn the right-click menu of a chat. Delete asks first and removes the chat with everything in it.

With AI chat set to Off the section is gone. What a chat is, and what the agent can do, is described once in AI chat.

Right-click actions

What you see

Common problems

The tree is empty.
The project has no .bpmn, .dmn or .form files that Penstock can see. Build folders are skipped. Press Reload from Disk.
The Run Penstock actions do nothing, or an error says the project is not trusted.
Trust the project. See Troubleshooting in the IDE.
The first command is slow.
Without a penstockw in the project, Penstock runs npx @kern0x1b/penstock-cli and downloads the command line the first time. penstock init adds the wrapper, which pins a version.
There is no Chats section.
The AI chat is off. Turn it on under General in Settings | Tools | Penstock | AI agents.
There is no Go to Implementation.
Code links are a Pro feature, and nothing in the project implements this worker.