JetBrains / Using it
Settings in the IDE
What Penstock adds to the IDE's Settings, including the AI agents page, which inspections it brings, how to bind a shortcut to its actions, and the notifications it shows.
The settings of a project are in penstock.yaml, so they travel with the repository and the command line reads them too. They are described once in penstock.yaml. This page is about the places in the IDE's own Settings where Penstock appears.
Settings | Tools | Penstock
The page has four groups. It holds no project settings: those are in penstock.yaml. What it does hold is yours, and is kept in ~/.penstock/preferences.json.
| About: Version | The version of the plugin that is running. A build that is not a release says development. |
| About: Documentation | A link that opens this guide in your browser. |
| About: Open source licenses | A link that opens the notices of the bundled open-source components in an editor tab. The same text is on the third-party notices page. |
| Editor: Suggest the next element at dead ends | On by default. Draws the element most likely to come next as a faint ghost beside a dead end of a flow. Tab adds it, Esc dismisses it. It is free. See Suggestions. |
| Editor: Suggest names, sources and expressions for fields | On by default. Shows the name, source or expression most likely for a field of the properties panel as faint text after the caret. Tab accepts it, Esc dismisses it and Alt+Shift+E explains it. It speaks only when it is confident, and it is free. |
| Command line: Penstock command line | The penstock command that reads the Python, Go, C# and Scala workers. Empty finds it on the PATH, then in the project's node_modules once the project is trusted, then in the plugin. |
| Trusted projects | The projects Penstock has been told to trust, each with a Remove button. On IDE 2025.2 and later the list is empty by design: the page says the IDE decides, with its own Trust Project action, so Penstock keeps no list of its own. Before 2025.2 the list is Penstock's own record, kept in ~/.penstock/trusted-projects.json. |
Three things run code that a project supplies, so each asks for trust first: a deploy hook from penstock.yaml, the project's Penstock command line, and the project's own bpmnlint bundle. The question is described in Security and privacy. The command line keeps the same record, and penstock trust reads and changes it.
Settings | Tools | Penstock | AI agents
A page of its own under the Penstock page. It is the agents screen, one screen in every tool, drawn by the editor's page inside the IDE: a search field, General, On and All agents (the ACP Registry) on the left, and the agent you select on the right with its version, description, licence and website, and the actions Install, Turn on, Update and Uninstall, and the models it offers with Refresh models. It has nothing to apply: a change is kept as you make it.
| General: AI chat | One control with three choices: Off, At the bottom of the editor and In the sidebar. It applies to every editor and every tool at once, and Off removes the input, the chats, the Chat tab, the toolbar button and the agent process. |
| Other ways in | Manage agents… in the settings form of the chat input, and the gear in the heading of the Chats section of the tool window, open the same page. |
| Where it is kept | In ~/.penstock/preferences.json (aiChat, agentsEnabled, agentSelected, agentOptions), so it holds across IDEs and restarts and is never in penstock.yaml. |
The page needs the IDE's embedded browser; without it the page says so. What an agent is, how to install one and how the registry works is in AI agents, and what you do with the chat is in AI chat. Sending a message needs Pro.
Settings | Editor | Inspections | Penstock
Penstock adds five inspections in one group. Each can be switched off, and each has a quick fix where one makes sense.
| Inspection | Default level | What it reports | Needs |
|---|---|---|---|
| Diagram findings from the check | Error | What the check found in a .bpmn, .dmn or .form file: shapes drawn on top of each other, a connection through a shape, the bpmnlint rules, a decision table with no rule for some input, two form fields writing one variable. It runs in the background on the file as it is on disk, so no diagram has to be open. The file is marked in the Project view, and the findings are in the IDE's Problems window and in Code | Inspect Code. Turning it off hides the findings from the IDE and leaves them in the editor. | Free |
| Unknown process, element, job type, message, decision or error code | Weak warning | A name in code that no diagram in the project has, where the code hands it to Camunda: starting a process, asserting in a test, a @JobWorker or external task subscription, correlating a message, evaluating a decision, throwing a BPMN error. A name that differs only in case is pointed out, with a fix. | Pro |
| Diagram element a comment or a string names, and the project does not have | Weak warning | A reference such as order.bpmn#ServiceTask_charge in a comment or a string, whose element is not there. A near id is offered as a fix. | Pro |
| Variable the worker's code reads or writes | Weak warning | A variable that a worker reads and no step before it sets, one it does not fetch and so gets as null, and one it writes that no later step reads, on the line that reads or writes it. Works in any language. | Pro |
| Job type taken from the method name | Weak warning | A @JobWorker without a type whose method name is a job type the diagrams use, so renaming the method silently stops the worker. The fix writes the job type into the annotation. | Pro |
The unknown name, the variable and the job type inspections need the IDE's Java support to read code. See Code links in the IDE.
Settings | Keymap
Every action of the editor is an IDE action under Tools | Penstock, in the groups Check & run, Layout & convert, Deploy & share, View, File, Edit and Help. Search the keymap for the name, or press the key you want, to bind it. The same actions are in Find Action. They work while a Penstock editor has the focus, and there they come before the IDE's own actions that use the same keys. The four that have a default key are in Shortcuts.
Settings | Editor | File Types
Penstock registers three file types: BPMN (bpmn, bpmn.xml, bpmn20.xml), DMN (dmn) and Camunda Form (a .form file that is a Camunda Form). If a file opens as plain XML, check that its pattern is still under the right type. See The editor in the IDE.
Run | Edit Configurations
The configuration type Penstock test cases runs Camunda test-case files against an engine. It is created for you when you run a test-case file, and it has three fields: the test-case file or folder, the name of one test case to run, and the engine profile. See Tests in the IDE.
Three more configuration types are created for you from a script or an expression tab, and are run from the Run menu or the right-click menu of that tab:
- Penstock script runs a Camunda script of a diagram in its own process, with the variables it reads set to the values you give. Run script and Debug script start it under the IDE's own debugger.
- FEEL expression evaluates a FEEL expression of a diagram on the sample values you give. Run expression starts it, and a marker in the gutter of the expression does the same.
- FEEL expression debug steps through a FEEL expression sub-expression by sub-expression, with the value of each one shown beside it, and stops at a FEEL breakpoint. Debug expression starts it.
Notifications
Penstock shows balloon notifications, all in one group. These are the ones it can show.
| Notification | When |
|---|---|
| Penstock updated to the new version, with What's new | The first time the IDE starts after an update. Never after a fresh install. The button opens the changelog in an editor tab. |
| Penstock settings can live in the project, with Create penstock.yaml | Once for a project that still keeps its engine in the IDE's own project settings and has no penstock.yaml. |
| penstock.yaml could not be read | When the file has a syntax error or a setting of the wrong type. Until it is fixed, Penstock uses the IDE's settings, and the notification says why. |
| This project's lint rules are not loaded until you trust the project, with Trust project... | When lint.clientBundlePath names a bundle and the project is not trusted. The editors reload when you trust it. On IDE 2025.2 and later the message tells you to use the IDE's Trust Project action instead. |
| Running Penstock requires trusting this project first | When a Run Penstock action is started in a project that is not trusted. |
| Penstock could not start | When the command line cannot be started. It needs Node.js on the PATH, the same as the command line itself. |
| The result of a deployment | After Deploy, whether the engine took it or not. |
| An offer to rename the places that still hold an old name | After you change a job type, topic, class, bean, message or process id in the properties panel. See Rename in the IDE. |
| An offer to buy Penstock | When a paid feature is used without the licence, and when the trial ends. See Licence in the IDE. |
The schema for penstock.yaml
The plugin registers a schema for penstock.yaml, penstock.yml, penstock.json and their .local versions, so completion, validation and hover help work with no setup and no network. The files have their own icons in the Project view, and so has .bpmnlintrc.
Common problems
- The Trusted projects group is empty.
- On IDE 2025.2 and later it always is. Use the IDE's own Trust Project action.
- I turned the check inspection off and still see findings.
- That is meant. The editor keeps showing its own findings. Only the IDE's Problems window and Inspect Code stop listing them.
- An inspection of the group is missing from the list.
- Three of them, unknown name, variable and job type from the method name, need the IDE's Java support to read code, which IntelliJ IDEA has and some other IDEs do not.