Helm and agent communication

Helm assistant

Ask Helm, the built-in assistant, to work in Orkestra for you, and read, steer and re-open its chats.

On this page

Purpose

Helm is the assistant that is built into Orkestra. You write a request in plain words. Helm does the work inside Orkestra, for example with tasks, terminals and worktrees. Use Helm when you want Orkestra to do something for you, or when you want an answer about the active project. Each project has its own Helm chats.

Where to find it

  • A round button with a sparkle icon (tooltip "Ask Helm (⌘J)") sits at the bottom centre of the workbench area. It is the closed state of Helm.
  • Press Ctrl+J (Cmd+J on macOS). On Windows and Linux the key does not reach Helm while the cursor is in a terminal: the terminal sends it to its program. Click outside the terminal first. The key opens Helm from the closed state. It closes Helm when Helm is open in any mode. See Keyboard shortcuts.
  • Helm has three modes: closed (the round button), the bottom bar (a floating panel at the bottom centre) and the side panel (a column at the right edge, 380 px wide). Orkestra keeps the mode and the height of the bottom bar when you restart the app.
  • Which engine Helm uses, and the rules for what Helm may do, are in Settings → Helm. See Settings: Helm.

What you see

Bottom bar and side panel (top to bottom)

  • Resize handle — a small bar at the top edge of the bottom bar (tooltip "Drag to resize — up to the top, down to collapse"). The side panel has no handle.
  • Header — the sparkle mark and the word Helm. A chat that came in through a remote connection, such as Telegram, also shows a small tag remote. At the right of the header are five icon buttons:
    • The + button (tooltip "New chat").
    • The history button (tooltip "History").
    • The archive button (tooltip "Memory"). It shows only while Helm memory is on. See Helm memory.
    • The panel button. In the bottom bar its tooltip is "Open in side panel". In the side panel its tooltip is "Switch to bottom bar".
    • The X button (tooltip "Minimize").
  • Transcript — the chat. It scrolls by itself to the newest entry. See the list below.
  • Input — one row at the bottom (see below).

Transcript entries

  • Helm messages — the word Helm with the sparkle mark, then the text. Orkestra shows the text as formatted text: paragraphs, lists, code, tables and links. Raw HTML in a reply shows as plain text. A link opens in your web browser.
  • Your messages — a coloured bubble with your text exactly as you typed it. Chips for your attachments show above the text.
  • Reasoning — a muted, slanted block with the label Reasoning. It shows the thoughts of Helm.
  • System activity — one folded block for a run of steps that Helm made (tool calls and policy notes). The header shows System activity and the count, for example "3 steps" or "1 step". Each step is one line: an icon, a title and a status word.
  • Plan — a card with the label Plan while Helm works through a plan. Each line shows the step, then the status ("Pending", "In progress" or "Completed") and the priority ("High", "Medium" or "Low"). When Helm runs on Claude Code, the card shows when Claude plans its work with its own task list. Orkestra switches that task list on for Helm chats, so you do not set anything up. To switch it off, see Turn the Plan card off for Claude Code.
  • Permission request — a card with a title, a line of detail and buttons. See Answer a permission request.
  • Working row — three moving dots and a short label at the end of the chat while a turn runs.

Input (left to right)

  • The + button inside the input (tooltip "Attach"). It opens the file picker.
  • The text field (hint "Ask Helm to do something…"). It grows with your text, up to 200 px.
  • The Stop button (square icon, tooltip "Stop"). It shows only while Helm works.
  • The Send button (arrow icon, tooltip "Send"). While Helm works its tooltip is "Send — queues behind the current turn".
  • Above the text field: one chip for each attachment that waits to be sent. A picture chip shows a small preview and the file name. A file chip shows an icon, the file name and the size. Each chip has an x button (tooltip "Remove").
  • Under the input: a red line when an attachment was refused.

History menu

  • A list of the chats of the active project. Each row shows the history icon, the chat title, the age ("just now", "5m ago", "2h ago", "3d ago") and the tag remote for a chat from a remote connection. A check mark shows the chat that is open now.

How to

Open Helm

  1. Click the round button with the sparkle (tooltip "Ask Helm (⌘J)").

Result: the bottom bar opens. If the open chat has no message yet, it opens as a one-row input. If the chat has messages, it opens 360 px high with the chat above the input. The key Ctrl+J (Cmd+J on macOS) does the same.

Ask Helm to do something

  1. Click the text field (hint "Ask Helm to do something…").
  2. Type your request. Press Shift+Enter for a new line.
  3. Press Enter, or click Send.

Result: your message shows in the chat. The working row shows. Helm writes its answer, and the system activity block lists the steps. If the panel is a one-row input, it grows to 360 px when the first part of the answer arrives.

Send another message while Helm works

  1. Type your next request in the text field.
  2. Click Send (tooltip "Send — queues behind the current turn").

Result: your message shows in the chat as a paler bubble. Helm answers it after the current turn.

Stop a running turn

  1. Click Stop (square icon, tooltip "Stop").

Result: the working row goes away and the turn ends. Messages that wait in the queue are dropped. A permission request that still waits for your answer changes to the line Cancelled — stopped. and you cannot answer it any more.

You can also click Stop before the answer starts, while Helm still prepares the turn (for example while it applies the model or effort of a Claude Code or Codex engine). Orkestra then drops that turn and it never starts.

Attach a file or a picture

  1. Click the + button inside the input (tooltip "Attach").
  2. Choose one or more files in the file picker.
  3. Check the chips above the text field.
  4. Press Enter, or click Send.

Result: Helm gets your text and the files. A text file arrives together with its file name. You can send files without any text. After the send, the chips stay on your message as an icon and a name only. Orkestra does not keep the file content in the chat.

Paste a picture or a file

  1. Copy a picture or a file. For example, take a screenshot, or copy a file in the Files panel or in your file manager.
  2. Click the text field.
  3. Press Ctrl+V (Cmd+V on macOS).

Result: a chip for each picture or file shows above the text field. Pasted text still goes into the field as text.

Remove an attachment before you send

  1. Click the x button on the chip (tooltip "Remove").

Result: the chip goes away. The red error line also goes away.

Insert a file, task, worktree or session into your message

  1. Open Files, ToDo, Worktrees or Session history in the left sidebar.
  2. Press the mouse button on the row of the item. For a worktree, press its name.
  3. Drag the item onto the input of Helm.
  4. Release the mouse button.

Result: Orkestra inserts text at the cursor. A file or a folder gives its full path. A task, a worktree or a session gives one line with its kind, its name and an address that starts with "orkestra://". Orkestra does not send the message. See Terminal windows for the same drop.

Answer a permission request

Before you start, wait for a card with a title and buttons in the chat.

  1. Read the title and the detail line of the card.
  2. Click one button, for example Allow or Deny.

Result: the card shrinks to one line with the title and your choice. Helm gets your answer and goes on.

Read the steps of Helm

  1. Click the System activity header in the chat.

Result: the block opens and lists each step with its status. Click the header again to fold it. A block that holds a running step is open and you cannot fold it.

Turn the Plan card off for Claude Code

Before you start, check that Helm runs on the launcher Claude Code (the list Engine in Settings: Helm).

  1. Click the Settings gear button in the top bar, then click Engines in the list on the left.
  2. In the group Launchers, click the arrow button of the launcher Claude Code.
  3. Click Add variable.
  4. Type CLAUDE_CODE_ENABLE_TODO_TOOLS in the field "KEY".
  5. Type false in the field "value".
  6. Click OK.

Result: the next message you send to Helm starts its Claude program again with the task list switched off, so Claude has no plan to show and the Plan card does not appear in new turns. The variable belongs to the launcher, so a terminal that you start from the launcher Claude Code also has it. To get the card back, click the close icon button of the line (tooltip "remove environment variable") and click OK. See Settings: task defaults and engines.

Start a new chat

  1. Click the + button in the header (tooltip "New chat").

Result: an empty chat opens for the active project. It starts with the greeting "Hi — I'm Helm. Tell me what to do and I'll run it inside Orkestra." The old chat stays in History. After your first message with text, Helm gives the chat a short title.

Open an earlier chat

  1. Click the history button in the header (tooltip "History").
  2. Click a chat in the list.

Result: the menu closes and the chat opens. Click outside the menu, or press Escape, to close it without a choice.

Move Helm to the side panel

  1. Click the panel button in the header (tooltip "Open in side panel").

Result: Helm shows as a column at the right edge. The workbench area gets narrower.

Move Helm back to the bottom bar

  1. Click the panel button in the header (tooltip "Switch to bottom bar").

Result: Helm shows again as the floating bottom bar. Your draft text and your waiting attachments stay.

Resize the bottom bar

  1. Point at the Resize handle at the top edge of the bottom bar.
  2. Press the mouse button.
  3. Drag up to make the bar higher.
  4. Release the mouse button.

Result: the bar keeps its new height. The highest size is the window height minus 24 px, and at most 980 px. A drag down to under 150 px folds the bar to a one-row input, without header and chat. Drag up again to bring them back.

Minimize Helm

  1. Click the X button in the header (tooltip "Minimize").

Result: Helm goes back to the round button. The chat stays, and a running turn goes on.

States and messages

  • Empty chat — a project without a chat shows an empty transcript. Orkestra creates the chat when you send the first message. History then shows "No previous chats" until a chat exists.
  • Loading — the transcript shows no text while Orkestra reads a chat from disk. The chat fills in when the read ends.
  • Working… — the working row label while Helm works. It changes to "Thinking…" while Helm reasons. It shows the title of a step while that step runs.
  • running… and queued… — the status of a step that is not done yet, in an open System activity block. Finished steps show done, failed, or a short detail from the step.
  • Send is grey — the field is empty and no attachment waits, or Helm is still starting a turn.
  • Paler bubble — your message waits behind a running turn.
  • Awaiting — session not live. — a permission card has no buttons because Helm is not running. This happens after a restart, for example.
  • Expired — this session is no longer live. and Expired — Interrupted — the app closed during this run. — a permission request that nobody answered before Helm stopped. You cannot answer it any more.
  • Cancelled — stopped. — a permission request that was still open when you clicked Stop. You cannot answer it any more.
  • Cancelled — turn ended without a decision. — a permission request that was still open when the turn ended or failed, for example when nobody answered it in time. You cannot answer it any more.
  • Cancelled — session closed. — a permission request that was still open when the program of the chat (for example Claude Code or Codex) stopped. You cannot answer it any more.
  • Interrupted — the app closed during this run. — a red line in System activity. You closed Orkestra while Helm worked.
  • Blocked … lines in System activity — Helm tried a step that your Helm settings do not allow. See Settings: Helm.
  • This chat's transcript could not be restored. It opened empty; new messages are still safe. — a yellow note above the chat. Orkestra could not restore the old messages.
  • This chat's transcript could not be read because of a filesystem error. New messages will not be saved until it is readable again. — a yellow note above the chat.
  • Errors from Helm — a failed turn adds a Helm message with the error text, for example 'Helm engine "<name>" failed to start: …'. When the Claude Code or Codex program stops while Helm starts it, the text can include its last error lines when Orkestra can safely show them. For Claude Code it can read like "…; Claude Code stderr: …". If those details cannot be safely prepared, Orkestra omits them; the error can say "Native engine failure details omitted." or "Codex app-server operation failed; diagnostic details omitted." Known sign-in and setup instructions still appear when available.
  • Helm engine "<name>" closed: … and Helm session on "<name>" failed: … — the Claude Code or Codex program stopped while the chat was idle (the second text: only the session of this chat ended). In the first text the cause can include the last lines that the Codex program printed, when Orkestra can safely show them. The text ends with "Send a message to continue in a fresh session." Your next message starts a fresh session.
  • Codex authentication failed; run codex login or set an API key, then retry. — a turn on a Codex engine failed because Codex is not signed in. The text can go on with "Codex reported: …" and what Codex said. Sign in with codex login in a terminal, or set an API key for Codex, then send again. The same chat works afterwards.
  • Codex model list is unavailable (model/list failed: …); cannot apply model "<name>". — Codex could not list its models, so Orkestra cannot check the model that you chose. The text can end with "reasoning effort" or "the session-start model" in place of the model name. Orkestra asks Codex again at the next start of a chat and at the next change of the model or the effort. While the list is down, Orkestra does not refuse a turn because of the reasoning effort that Codex itself reports for the chat.
  • Notes from Codex — one line in System activity that starts with "Codex config warning:", "Codex deprecation notice:", "Codex warning:", 'Codex MCP server "<name>" failed to start' or "Codex rerouted the model from … to …". Codex printed the warning and Orkestra shows it. A note about one chat appears in that chat only. A chat that has not sent its first message yet shows the note with that message. A note that names no chat appears in every chat on that Codex engine.
  • Further … notices are hidden; Orkestra's diagnostic logs still record them. — one line in System activity that replaces the eleventh note about the same thing. Orkestra shows at most ten notes about the same failing tool server, or ten of the same warning text. The line names what is hidden: 'Further Codex MCP server start failure notices for "<name>" are hidden; …', or "Further identical Codex warning notices are hidden; …". For the other kinds, "Codex warning" is "Codex config warning", "Codex deprecation notice" or "Codex model reroute". When Codex sends very many different warnings, the line has no word "identical", for example "Further Codex warning notices are hidden; …". A different warning, or another tool server, is not hidden by this line. The diagnostic logs still record every warning.
  • Notes from Claude Code — one line in System activity with the first message of a chat on a Claude Code engine: 'Claude MCP server "<name>" failed to connect: …' or 'Claude MCP server "<name>" needs authentication.' Claude Code could not reach a tool server of the chat, for example the one named "orkestra". The chat starts anyway.
  • The plan reached its size limit; some task details were omitted. — a note in System activity when Claude Code's plan grows beyond the display limit. It appears once in that chat session. The plan keeps the details that fit; later task updates can still change it.
  • Orkestra requires Codex approval requests to route to the user, but Codex reports reviewer "…" — Codex is set up to send its approval requests to a reviewer other than you, so Orkestra closes that Codex session without starting a turn. It appears when Helm starts a Codex chat, or continues an old one after a restart. Check the approvals setting of Codex, then send again.
  • This engine doesn't accept images, so "<name>" can't be sent. Remove the image attachments or switch to an image-capable engine in Settings. — the engine cannot read pictures.
  • Attachment errors (red line under the input):
    • "You can attach at most 6 files per message."
    • '"<name>" is too large (max 4.0 MB per file).'
    • "Attachments exceed the 10.0 MB total limit."
    • 'Could not read "<name>".'
    • 'Skipped "<name>" (too large).' or 'Skipped "<name>" (unreadable).'
    • "Couldn't read the copied files from the clipboard."
  • remote — the chat came in through a remote connection, such as Telegram. See Remote control with Telegram.

Limits and tips

  • What Helm does for you. By default Helm runs Orkestra for you. It manages projects, tasks, terminals, worktrees, terminal groups and schedules, and it can send you a notification. It can also answer questions about the active project. Helm acts through Orkestra's own tools, so you see its work as tasks and terminals. You can change this behaviour in Settings → Helm.

  • Helm does not edit the project itself, by default. The default rules tell Helm to read project files and to do repository work through a task or a terminal. Settings → Helm can widen its access. See Settings: Helm.

  • Some steps need your approval. Helm shows a permission card before it:

    • launches a task or a group;
    • creates and starts a worktree, or removes a worktree;
    • sets a schedule, or creates, changes, deletes or runs a routine;
    • runs a command or sends keys in a terminal;
    • opens, closes or reconnects a terminal;
    • deletes or trashes tasks, groups or projects, or merges tasks;
    • restores a session, changes project groups or renames a project.

    Other Orkestra steps run without a card.

  • Chats belong to a project. History lists only the chats of the active project. When you change the project, Helm shows the latest chat of that project. A turn in the other project goes on in the background. See Projects.

  • Chats from routines. A routine that runs in Helm adds a chat to History. See Scheduler and routines.

  • Files from your file manager. You cannot drag them onto the input. Use Attach, or copy the file and paste it.

  • Attachment limits. At most 6 files per message, 4 MB for one file and 10 MB in total.

  • Draft text. The text and the waiting attachments stay when you switch between the bottom bar and the side panel. They do not stay after you restart the app.

  • Shift+Enter adds a new line. Enter sends.

  • The engine, the model and the system prompt of Helm are in Settings: Helm. The saved lessons of Helm are in Helm memory.