Agents

The Agents tab (Ctrl+2) is where you work with agents. It lists every live session of the project: the ones tasks started, the ones automations started, and the ones you start yourself, including terminals and file browsers. Pick one on the left, and the right side shows its stream and a side panel of everything it produced.

The session list

Each row shows the agent, the session's name and its status: Starting, Thinking, Calling tool, Needs your input, Ready, Done or Connection lost. A session a task started carries its role (Refiner, Planner, Coder or Reviewer); one an automation started carries its run number, such as #3. Search sessions... (Ctrl+F) filters by name, and the menu button collapses the list to a strip of icons to give the session more room.

Hover a row and press the X, or press Ctrl+W, to close a session. If the session made its own worktree and nothing was done in it, the worktree is removed; otherwise it is kept and Maestro says why.

Starting a session

New Session (Ctrl+N) starts an agent with no task attached. Pick:

• Agent: any agent installed on the connection, with the project's default marked Default. An agent that needs a missing tool is greyed out and says which.
• Or open: Terminal for a shell, or Files for the file browser on its own, to read or edit a checkout without an agent.
• Workspace (git projects): Create new worktree on a new or existing branch, Use the repository directory, or Reuse an existing workspace. A terminal or a file browser opens on an existing checkout, never a new worktree.
• Session name: optional, generated when blank.

Terminals and file browsers last until Maestro closes. Closing a file browser with unsaved edits asks first.

The session header

The header above the stream names the session; click the name to rename it. Beside it are the stage a task session runs (such as Implement), its status, and its branch.

On the right, Reload session reattaches the window to the session without ending it, for when the stream looks stuck. The cost pill shows what the session has cost and how many tokens it used; hover it for each turn, each model and each kind of token. For agents that report a plan limit, such as Claude Code, a meter shows how much of the 5-hour window is used and when it resets, and its hover card adds the weekly limit.

Talking to the agent

The composer at the bottom is where you write. Type @ to attach files from the workspace, and / for the commands the agent offers. Attach files with the paperclip or paste an image, when the agent accepts images. The row beneath it switches the agent's model, mode (Shift+Tab cycles it), effort and any other option the agent exposes, and a gauge shows how full its context is, with Compact context to shrink it (Compact now once it is nearly full). While the agent works the send button becomes Cancel, and Esc does the same.

When the agent needs you, the composer is replaced by the question:

• Permission requests show the tool, the command and its details, with the agent's own allow and reject options.
• Plans come with Reject and an accept button that also sets how much the agent may do on its own afterwards, from approving every tool use to trusting the whole session.
• Questions (the agent asking you to choose or fill something in) show as a small form, one question at a time, with free text where you need it.

A question survives the window: close Maestro while the agent waits, and it is still there when you come back.

The stream

The stream is the agent's side of the conversation. Tool calls are grouped into one line per run, such as "4 commands · 1 edited · 1 created", and expand to their output. Thinking blocks can be expanded, collapsed or hidden from Display settings (the sliders button), which also hides tool calls or compacts the stream.

Answers render more than text. Mermaid diagrams, SVG, images, KaTeX formulas and chemical structures from SMILES all draw inline and zoom on click, tables sort by any column, and a file:// link opens the file in the side panel. So an answer can be a flowchart or a formula rather than a description of one.

Every message has Create task from message, which turns an answer, or the part of it you selected, into a task on the board.

The side panel

The side panel sits beside the stream and holds everything the session produced, one tab each. Some tabs open on their own the moment the agent produces something (a plan, a first file change, a canvas, a terminal); + adds a terminal or a file browser. Drag the edge to resize it, collapse it to a strip of icons, or maximize it over the stream.

Overview

A summary of the session in cards, each opening its tab: the plan's progress, the changes (files touched, lines added and removed, committed or not), the pull request on the branch with its CI checks, the canvas surfaces, the artifacts and the subagents.

The changes card also ships the work. Commit and push drafts the request to the agent in the composer, for you to send; Open pull request opens one on your forge once the branch is pushed. When the pull request's checks fail, Send failing checks to the agent drafts the fix request.

Plan

The plan, when the agent wrote one. Select any passage to comment on it, and Revise plan sends every note back at once, each anchored to the text it is about. Accepting or rejecting the plan itself happens in the composer.

Changes

Every change the session made, as a diff, unified or split, with a file list you can filter or show as a tree. The scope menu in its header narrows it to All changes, the Uncommitted ones, one commit, or a range of commits. Drag across lines to comment on them, comment on a whole file, and mark files as viewed as you go. Send annotations hands all the comments to the agent as one prompt, the same way a review works on the board.

Files

The workspace as a tree, with an editor. Open any file, edit it, create or rename files and folders, show hidden files, and open a file in its default application. Images, PDFs, audio and video show in place, and Markdown can be edited side by side with its preview. Click the file name in the header to copy its full path. On a remote connection, Download and open and Download to… fetch a copy to this computer. If the agent writes to a file while you are editing it, Maestro asks before overwriting either version.

Each file opens in its own tab. Drag a tab to the side, or choose Move to the side from its menu, to show two files next to each other, and drag the line between them to resize. Drag tabs to reorder them or to move them between sides; a side with no tabs left closes. A file link in an agent's reply opens its file here, and a link to a line, such as store.ts#L42 or #L42-L50, scrolls to that line and briefly highlights it.

Terminal

A shell in the workspace, as many as you want. The agent's own long-running commands open here as their own tabs too, and so does a sign-in prompt an agent needs you to type into.

Artifacts and subagents

Artifacts collects the documents the agent wrote during the session in .maestro/artifacts/, .planning/ or .claude/plans/, such as reports, plans, Markdown, JSON or HTML, with a zoomable preview and a button to open each one. Subagents lists the helper agents the session spawned, each with its prompt, tool calls, output and status, and a button to stop it.

Canvas

A canvas is how an agent shows you something instead of describing it: a dashboard, a chart, a comparison table, a form, a mockup of the screen it is about to build. The agent writes it as a web page and Maestro draws it in the Canvas tab, in the app's own theme and accent colour, light or dark.

What an agent can draw

Anything a web page can show. Tables, cards and layouts come ready-styled; charts can use any charting library from a CDN; and the agent can push new data into a canvas it already drew, so a table or chart updates in place without being redrawn. A session can hold several canvases, and the arrows in the tab's header page between them.

A canvas you can use

A canvas is not a picture: its buttons, forms and inputs work, and they answer the agent. When the agent is waiting on a canvas, a click or a submitted form goes to it straight away, with every field you filled in, and it reacts: redraws the chart, runs the next step, asks the next question. A click while the agent is busy is kept and delivered when it is free. That makes a canvas a way to answer an agent with more than a sentence: pick options from a list, adjust values, approve rows one by one.

In the screenshot at the top of this page, the agent drew a Show only untested files button and waited. Clicking it sent the click back, and the agent filtered the chart and explained what it found.

Pointing at things

Annotate this canvas (the icon in the tab's header) switches to annotation mode. Click an element to attach a note to it, or drag a rectangle to cover several; a rectangle also sends a screenshot of that region when the agent accepts images. Notes collect in a bar, across every canvas of the session, and Send annotations sends them together. The agent receives each note with the exact element it is about, so "make this one red" is unambiguous.

Keeping and sharing canvases

Every canvas is saved as it is drawn, as a single .html file under .maestro/canvases/ in the workspace, and a reopened session brings its canvases back. Export as HTML saves a copy anywhere, and it opens in any browser.

Import a canvas (or drop an .html file on the tab) brings one back into a session, yours or a colleague's. A canvas Maestro saved comes back live, with the agent listening to it. Any other HTML file can be shown as it is, or handed to the agent to rebuild as an interactive canvas.

Safety

A canvas runs in a sandbox: it cannot reach Maestro, your files, or the rest of the app. It may load scripts, styles and images from the web, which is how charting libraries work, and it may only read data from the addresses the agent declared, which are listed beside its title. When something in a canvas fails to load or throws an error, Maestro shows it under the canvas and reports it to the agent on its next canvas call, so the agent can fix what it cannot see.

Session history

History (Ctrl+H) browses an agent's past sessions, by date or by search. Click one to resume it: Resume Session asks where the conversation continues, already set to the worktree it ran in when that still exists. You can rename sessions there, and delete them when the agent supports it.

Sessions outlive the window

Agents run in a background Maestro server on each connection, not inside the window. Close Maestro, or go back to Home, and a running session finishes its turn; come back and you pick the session up where it is, including any question the agent was waiting on. A session nobody is watching is closed a minute or two after its turn ends, and resumed from history when you need it.

Tasks live in the same server, so the task pipeline keeps going with every window closed: queued tasks start, plans and reviews run, and Home shows what is waiting on you when you return. Only a task waiting on its pull request needs a window open, since checking the forge uses your keychain token.

Agents that talk back

Every session gets Maestro's own tools. An agent can create and update tasks on your board, read and comment on the task it works on, manage automations, templates and prompts, and draw canvases. Running an automation always asks you first.