Settings

Settings open as a dialog over any tab, from the cog in the header or with Ctrl+,. Search settings… finds a control by name. Everything saves as you change it.

The top strip shows the version, which links to its release notes, Check for updates, and Install when an update is ready (installing stops running agent sessions). Its menu turns Auto-update on or off. A .deb or .msi install offers Download instead, and cannot update itself.

Pages come in three groups. Project pages appear only with a project open. On Home, the cog opens the Application pages, and Settings in a connection's ⋯ menu opens that connection's pages too.

Project

Agents

Agents & sign-in lists the agents installed on the project's connection. Click one to make it the project's default, which runs new sessions and any task stage with no profile of its own. Logout signs you out of an agent.

Task workflow stages sets up the agent for each stage, on two tabs. Pipeline holds a task's stages, Refine, Plan, Implement and Review. Loops holds a loop's, Prepare, then Build and Judge for each iteration. Click a stage to see its profiles. Add profile creates one, with its own agent, model, permission mode, effort and instructions. A project opened for the first time starts with one profile per stage on the default agent. Without a profile, Refine, Plan and Review are skipped, Implement, Prepare and Build run on the default agent, and Judge runs on Build's agent. Profiles are saved in .maestro/profiles.json.

Waiting on you, on the Loops tab, sets how many loops may wait on you at once before auto mode starts no more of them. 0 means no limit.

Git

• Default workspace: where new tasks and new sessions start out.
• Default base branch: Auto uses the branch the repository is on.
• Git remote: the remote Maestro pushes to and lists branches from, with the code host's status and Connect when an integration is missing.
• When a task is approved: the default choice in the Approve dialog, one of Merge locally, Open a pull request or Push only.

Issue tracking

Pick the connected provider to import issues from, with its project fields, such as the repository for GitHub or the team for Linear. When the git remote points at a provider you have not connected, Maestro offers to connect it. Remove clears the setup.

Appearance

The project's own accent colour, and the tab it Opens On: Tasks, Agents, Collections or Workspaces.

Connection

These pages apply to the machine the project lives on, and to every project on it.

Running agents

How many agents Auto mode runs at once on this machine: estimated From free memory, or A fixed number from 0 to 64.

Background server

The server that runs agent sessions and automations, and keeps running after Maestro closes. Start automatically starts it at login (on a Linux host, at boot through systemd or cron), so schedules keep firing after a restart without opening Maestro. The page counts live sessions and automation runs. Stop server ends them all and takes you back to Home at once, where the connection reads Server stopped when the stop is done. Home's connection menu can also start, stop and restart the server.

Webhooks

Where webhook automations listen: the address and port (default 127.0.0.1:7433), and the Public URL of a tunnel or reverse proxy that webhook URLs are built from. Maestro warns before you bind to an address other machines can reach.

Application

Appearance

• System title bar (not on macOS).
• Reduce motion: turns off the background animation and the transitions between views. It is on by default when the system asks for less motion or the machine has no graphics acceleration.
• Terminal follows app theme.
• Theme: Light, Dark or System.
• Global Default Color: the accent colour, or Auto to follow the system's. New Projects either get a colour of their own or use this one.
• UI Scale: Default, Comfortable or Large (100%, 115% or 130%).
• Enter Key Behavior: whether Enter sends a message or adds a new line.

Notifications

Desktop notifications when an agent finishes, needs you, or fails. They are only sent while Maestro is in the background.

Diagnostics

The log level, from error to trace, and where the log is written: open the folder, change it, or reset it. A new folder takes effect at the next launch. Leave the level at info unless you are chasing a problem: trace records prompts and agent output.