Penstock

Guide / Draw and edit

AI chat

Ask an AI agent about the diagram you have open, or give it a task, from an input at the foot of the editor. The agent runs on your own account, reads your project through Penstock, and every change it wants to make is shown to you before it happens.

Pro An AI agent signed in to your own account. Team in a pipeline.

What it is

The AI chat is a conversation with an agent, inside the BPMN, DMN and form editors. Penstock does not bring a model of its own. It starts the agent you choose, such as Claude Code, Codex, Gemini CLI or OpenCode, and talks to it over the Agent Client Protocol. The agent runs on your machine and on your own account. Penstock gives it its MCP server, penstock mcp, so the agent can read diagrams, the rules that check them, the scenarios and the links to your code, the way the command line does. See The MCP server.

The agent does not write to your project behind your back. When it wants to change a file, it asks. A change to a diagram is drawn on the canvas first, and you accept or reject it. See Review the changes an agent proposes. Which agents there are, and how to install and turn them on, is on AI agents.

The chat is part of Penstock Pro, and Team in a pipeline. The input and the chats are shown to everyone. When you send a message without the licence, you get the usual offer at that moment: what the AI chat does, and the choice to buy Pro or to enter a licence key. Nothing is added to the chat. See Plans and licence.

Where the AI chat is, by tool

JetBrains

In a JetBrains IDE from 2023.1 the input is at the foot of every BPMN, DMN and form editor, and the chats are listed in a Chats section under the tree of the Penstock tool window. The agents screen is the page Settings | Tools | Penstock | AI agents. Sending a message needs Pro. See The Penstock tool window.

VS Code

The input is at the foot of every BPMN, DMN and form editor, and the chats are in the Chats view of Penstock. The agents screen is the command Penstock: AI agents. Sending a message needs Pro.

Command line

Not available on the command line. The command line has no editor to hold the input. An agent you run yourself can still read the project through penstock mcp. See the MCP server page.

Ask a question

  1. Open a diagram, a decision or a form. The input is at the foot of the editor, in the middle of the canvas.
  2. Click it and write what you want to know or have done: Ask about this or give the agent a task. Select an element first if the question is about one.
  3. Press Enter. Shift+Enter starts a new line.
  4. The answer appears in a card just above the input, with the agent's work folded into one row while it runs. When the agent has something to change, it asks you first.
  5. Write the next message in the same input. The conversation goes on in the same chat.
The BPMN editor with the user task Approve order selected. Above the input at the foot of the canvas an answer card is open. It is headed with the chat title, What happens if the credit check fails?, and the agent name, with three buttons at the right. It holds the question and an answer that names Order received, Check customer credit and Set credit limit as chips. Below it the input shows two chips, Approve order and order-to-cash.bpmn, the placeholder text and the settings button
A question asked about the selected task. The answer card sits right above the input, and the names in the answer are chips.

If the agent is not signed in or not installed yet, the card says so and offers the next step. See When the agent cannot answer.

Where the chat lives

One preference, AI chat, decides where the conversation is shown. It is in the agents screen, under General, and is the same in every tool. See AI agents.

SettingWhat you get
At the bottom of the editorThe default. The input sits at the foot of every editor, with the conversation in a card above it. The sidebar has a Chat tab as well.
In the sidebarThe conversation lives in the Chat tab of the sidebar, and no input sits at the foot of the editor.
OffNo input, no chats and no agent process. The agent is not started, and the Chat tab and the toolbar button are gone.

The choice is kept in ~/.penstock/preferences.json as aiChat, with the values off, bottom and sidebar. A value Penstock does not know is read as bottom.

The input

The input is the same in the three editors. From top to bottom it holds the messages that wait, what the message is about, the text, and a row of controls.

The textOne line to six, then it scrolls. Enter sends. Shift+Enter is a new line.
ChipsWhat the message is about. The file you are in is always there. The elements you have selected on the canvas are added by themselves, and each has an x that takes it out of the message. Past four elements the row says how many more there are. The agent is told the file and the selected elements.
+Attach a file or mention an element. Opens a list of the elements of the diagram and the files of the project, with a search field. A pick becomes a chip.
The chat titleA button at the left of the row. It lists the chats of the project to switch to, and New chat at its top.
The settings buttonShows the agent's logo and what is set, such as the model and its level. It opens the settings of the next message. See below.
Send, or StopSend is in the accent colour and disabled while the text is empty. While the agent works it becomes Stop, a neutral square.
The input of the AI chat, opened. Two chips at the top name what the message is about, the selected task Approve order with an x, and the file order-to-cash.bpmn. Below them the text of the message, then a row with the chat button, a plus, the settings button with the agent logo and the model Opus 5.5 High, the key hints Enter send and Shift Enter newline, and the round Send button in the accent colour
The input with a message typed. The chips say what the message is about, and the row below holds the controls.

An input that is empty and not in use rests as one line, with the placeholder and the send button. Clicking it or typing in it opens the full row, and clearing it and leaving it rests it again. When the row is short, the chat title becomes an icon first, then the key hints go. On a canvas too narrow for the input, it is one button, Ask the agent, at the foot. It shows a spinner while the agent works and a hand while a question waits, and opens the whole input over the canvas.

While the agent is working

Agent, model, thought level and mode

The settings button shows the agent's logo, the model's name and the level, such as Opus 5.5 High, and the mode after a dot only when it is not the agent's default. Pressing it opens a small form above the button.

The settings form of the AI chat, open above the settings button. It has one row each for Agent, Model and Thought level, with the current values, and Manage agents at the foot. The input with its chips and text is just below it
The settings form opens above its button. Agent and Model are lists, and the thought level is a short row of values.
AgentThe agent for this chat. Pick one from the list.
ModelThe model the agent offers.
Thought level, ModeShown when the agent offers them. A few short values appear side by side. A longer list opens inside the same form, with a description under each value and a ‹ to go back.
Manage agents…At the foot. Opens the agents screen.

The arrow keys move, Enter picks, and Esc goes back from a list, or closes the form from the rows. A change made while the agent works applies from the next message. The model and the level are remembered for each agent. Changing the agent of a chat that already has messages starts a new chat, and the list says so.

The card and the Chat tab

The card is the conversation, right above the input. It scrolls inside and opens at the latest message. Its header has the chat's title and three buttons: New chat, which is off while the agent works or a question waits, Open the chat in the sidebar, and Fold the chat.

The Chat tab of the sidebar holds the same conversation, with the same chips, work rows and questions, and an input of its own at its foot. The expand button and the AI chat button on the toolbar open it. While it is shown, the input at the foot of the editor is hidden. Leave the tab and the card comes back, with the same chat. A question that waits opens the Chat tab when the chat is in the sidebar.

The verification receipt

When an agent changes project files, the chat shows a card under the answer, for example Verified: 0 new problems, 3 scenarios pass, with chips. The Chat tab shows the full receipt. The verdict and the counts are free; auto-repair, which hands new Check errors back to the agent in the same turn, is Pro. See AI receipt and auto-repair.

Questions

When the agent wants to write to a file, it stops and asks. The card shows one sentence, Apply 3 changes to order-process.bpmn?, the changes as a list (+ added, ~ changed, - removed), and, for a diagram, what Penstock checked: Check is clean, or how many problems to look at. Then you choose.

DenyRefuses the write. It holds the focus, and Enter does not press it.
AllowLets the agent write. The note beside it says that undo takes it back.
Show on canvasFolds the card and shows the proposal on the diagram, where each change can be accepted or rejected. See Review the changes an agent proposes.

A write is never remembered: the answer holds for that one question, and there is no Always. A question that waits sets a warning dot on the toolbar button and, with the chat in the sidebar, opens the Chat tab. A question nobody answers is cancelled after a while, and the turn is stopped.

The AI chat button and the shortcut

The toolbar has an AI chat button, an icon with a tooltip, pinned by default. It opens the Chat tab, stays pressed while the tab is shown, and a second press returns to the tab you had before. It is also in the More menu and the command palette. Its shortcut is in the sheet of keyboard shortcuts and on the shortcuts page of your tool. See The toolbar and the More menu.

Chats belong to the project

A task often spans a process, a decision and the code of its workers, so chats belong to the project and not to a file. Each editor has its own current chat. It opens on the latest chat its file took part in. With none, your first message starts a new one, so two diagrams never mix their conversations. The title of a chat is the first line of its first message until you rename it.

The window of Penstock Web. The title bar has the Penstock name, the project switcher and the open file. The sidebar island at the left has the Actions Check, Scenarios, Monitor, Debug and Auto layout, the Project tree and, below it, the Chats section with one chat, working or idle. The BPMN editor with the AI chat at the foot is at the right
The sidebar of Penstock Web: the actions, the project tree and the Chats section under it, with the editor and its AI chat at the right.

The chats are listed with their state, in the place each tool has for them:

ToolWhere the chats are
The side panel of your toolA Chats section under the project tree. Where it is, by tool.
VS CodeThe Chats view of Penstock.
Penstock WebThe Chats section of the sidebar, under the project tree.

Each row has the title, on at most two lines, and one word of state: a spinner and working, a warning dot and waiting for you, the time when it is idle, or the reason when it stopped with an error. The + in the heading starts a new chat, and the gear opens the agents screen. A right click, or the menu key, offers Rename and Delete. F2 renames and Delete deletes. Deleting asks first, and removes the chat and its messages from the project. Choosing a chat opens it in the Chat tab of the active editor.

There is one agent session per project, for every window and every tool. A chat that works in one window shows as busy in the others, and a message typed there queues behind it. A chat made or changed in one tool appears in the others within a second. Only the text you have not sent yet belongs to one editor.

When the agent cannot answer

The card says what is wrong in a sentence, with at most two buttons.

You seeWhat it means
No agent found. No agent is installed on this machine. with an install command and a copy buttonInstall an agent with the command, or press Choose another agent or Agent settings. See AI agents.
The agent is not signed inSign in to the agent in its own app, then press Try again. When the agent offers a sign-in, a Sign in button starts it.
The agent has endedThe agent stopped without an answer. The reason from the agent is shown. Press Try again.
Unable to reach the agent serviceThe editor could not reach the part of Penstock that runs the agents. Press Try again.

What you see

Common problems

Sending asks me to buy Pro.
The AI chat is part of Pro on your machine and Team in a pipeline. The offer shows what it does and lets you buy Pro or enter a licence key. See Plans and licence.
There is no input at the foot of the editor.
AI chat is set to Off or In the sidebar. Change it under General in the agents screen. See AI agents.
It says Penstock needs Node.js with npm to start the agent service.
The chats of a project are served by penstock agent serve from the command line, one for every window. Install Node.js with npm, and try again.
The agent answers, but I cannot find where it changed the diagram.
A change waits for your answer. Press Show on canvas in the question, or open the Chat tab. See Review the changes an agent proposes.
I cannot start a new chat.
New chat is off while the agent works or a question waits, because it would drop the question. Answer it, or press Stop.