maestrly.
EN ⌄Download free

Concepts

These are the building blocks behind every Maestrly workflow.

Provider, account, and model

A provider operates the AI service. An account is one connection to it: a subscription sign-in or an API key. You can connect several accounts per provider, each with its own label, and order ChatGPT or Claude subscription accounts for automatic rotation when one hits a usage limit. A model is one of the inference options an account offers. Requests go directly from Maestrly to the selected provider, whose terms, pricing, limits, and regional availability apply.

Standalone chat and workspace conversation

A standalone chat (Chats → New chat) needs no project. It has a private working folder in the app profile, its own saved permissions, and the personal memory shared by your chats. When you ask, it can send a plan to a workspace for development.

A workspace is a project: a Git repository on your computer. A workspace conversation works on a branch of it, or across several repositories at once, with the project's instructions and project memory. Maestro, Git review, and branch operations need a workspace.

Conversation experience, mode, and permissions

A conversation is Standard (one agent) or Maestro (orchestrated). In Standard, the mode sets what the agent may do: Agent, Design, Plan, or Ask. A separate permission mode, Ask for approval, Approve for me, or Full access, decides when the agent stops for your approval. See Chat, models, and context.

Maestro and subagents

Maestro is the orchestrator. The selected model coordinates without editing and routes executable work, tests, and review to the agents in the Agent Pool, following a strategy: Balanced, Best quality, Fast, or Economy. Configure it in Settings → Maestrly Chat → Maestro.

A subagent is an isolated run that an agent delegates a subtask to. It has its own history, instructions, and tool subset, returns its result to the parent, and cannot delegate further. In Claude and Codex conversations, independent subagent tasks run in parallel. Allow or block delegation per conversation with Subagents in the + menu; Subagent execution profiles set fixed provider, model, effort, and speed rules for them.

Agent and skill

An agent is a reusable role: a Markdown file with a name, a description, optional model and tool settings, and instructions. Maestrly reads agents from .agents/agents and .claude/agents, in the project and in your home folder. Reference one in the composer with #, or let the main agent delegate to it as a subagent. Maestro's Agent Pool keeps its own agents, with instructions, specialties, and execution candidates.

A skill is a focused procedure an agent loads on demand: a folder with a SKILL.md file and optional scripts, references, and assets. Skills live in ~/.agents/skills (global) or in the project's .agents/skills; the .claude/skills and .codex/skills folders are read too. Manage them in Settings → Maestrly Chat → Skills and choose them per conversation in the Skills menu.

Use agents for stable roles and skills for specialized, reusable know-how. See Maestro, agents, and skills.

Tool, Maestrly tools, and MCP

A tool lets an agent act or retrieve information. Maestrly tools are the app's built-in tools, in groups: Terminal, Browser, Notes, Memory, Conversation history, Debugger, and Artifacts. They are on by default; turn groups off in Settings → Maestrly Chat → Tools, or per conversation under + → Maestrly tools.

MCP (Model Context Protocol) is a standard way to add tools and resources from local processes or remote services. A connected MCP server has its own permissions, credentials, network behavior, and availability. Every tool call follows the conversation's mode and permission mode. See Tools and MCP.

A plugin bundles skills and MCP servers, and sometimes commands, agents, and hooks, from a Git source. Maestrly installs it on one host and makes its parts work the same with every model. See Plugins.

Git execution mode

A workspace conversation runs in one of two work modes:

  • Worktree: an isolated folder outside the repository, in the app data, on its own branch. It suits parallel or automated tasks. Deleting the conversation removes the worktree and branch it created.
  • Local: your repository folder. Before switching branches there, Maestrly previews your local changes and preserves them after you confirm.

Isolation reduces collisions but does not replace review. See Projects and Git.

Memory

Memory is durable knowledge an agent reads as evidence: pinned entries enter the context, and the others are recalled by relevance or read on demand. There are separate spaces: personal memory for your standalone chats, project memory for each workspace (managed in its Memory Center), and each bot's own memory. Automatic saving is optional and starts off.

Artifact

An artifact is a web page, made of HTML, CSS, JavaScript, and assets, that an agent publishes: a prototype, a report, or a dashboard. Each change creates a new version. Artifacts are hosted only on your bot server and stay private until you share them. Artifacts, at the bottom of the sidebar's icon rail, lists them. See Artifacts.

Bot, environment, and bot server

Experimental. A bot is a Maestrly agent that runs in Docker, with its own conversation, models, memory, routines, screens, and Chromium browser with its site logins. An environment is one container shared by up to eight bots: one Maestrly desktop, one home folder, and one set of model accounts, skills, and MCP servers.

The bot server runs your environments and hosts your artifacts. Install it from Settings → Bot servers on this computer's Docker or on your own Ubuntu or Debian VPS over SSH, and pair additional running servers with Add server. Bots on a VPS keep working while your computer is off; bots on this computer stop when it sleeps. See Bots.

The bot server can also host workspaces environments: Maestrly instances with no bots that run your own chats and workspaces, one per scope of your work, which the sidebar lists when you switch to them (experimental). Since 0.25.0, you can also connect your other computers directly over your local network or Tailscale in Settings → Computers and use them from the same machine switcher. The mobile app pairs with your bot servers to follow bots and server chats from a phone. See Remote workspaces and chats.

Local-first, not local-only

The desktop app has no hosted Maestrly backend. Conversations, notes, memory, settings, and usage records stay on your computer, in the local profile or your project files, unless you choose to run them on your own bot server. There is no Maestrly account, telemetry, analytics, or automatic log upload. Network boundaries still matter:

  • AI prompts, selected context, attachments, and responses travel directly between the app and your chosen provider for inference.
  • The optional bot server is one you host, on your Docker or your VPS. It stores your bots' conversations, files, and memory, your artifacts with their sharing state and comments, and the chats and workspaces you choose to run there. The desktop reaches it locally or through an SSH tunnel. Sharing an artifact with other people needs a public address you provide, such as Tailscale Serve; no hosted Maestrly relay is involved.
  • MCP servers, browser and web tools, the web search provider you choose, Git remotes, and other connected services receive the data needed for calls you authorize.
  • A paired phone talks only to your bot server. Its notifications go through Expo's push service to Apple or Google and carry only a bot's name or a chat's title, never message content.
  • The app checks GitHub Releases for updates and may query models.dev for model limits and pricing. Optional components, such as the voice model or a provider runtime, download only when needed or after you confirm.

Maestrly does not act as the inference provider or bundle model access.

Usage and responsibility

Maestrly is free, but providers and connected services may charge your own accounts. You control what is connected, what an agent may use, and whether a result is accepted, committed, merged, or deployed.

Next: Features overview.