Chat, models, and context

A chat combines a task, its history, a provider model, its context, and the capabilities you allow. Use one chat per coherent outcome so its context and review remain understandable.

Providers and accounts

Connect providers in Settings → Maestrly Chat → Accounts (see Getting Started). Inference requests travel directly from the app to that provider; Maestrly does not resell model access. Provider authentication and retention follow the provider's terms.

Accounts list: since 0.20.0, the Accounts tab lists every account in one list grouped by provider, with its status and usage, and shows the selected account's details beside it. Search accounts, show only those that Needs attention or are Near limit, and find providers you have not connected under Available to connect.
Several accounts per provider: Add account connects a subscription or an API key. To add another account of the same provider, choose Add account again, or Connect another … account in an account's ⋯ menu. Each account has its own label, sign-in, and sessions.
Automatic rotation: with two or more ChatGPT or Claude subscription accounts, turn on Automatic rotation and order the list with Add fallback account, Move up, and Move down. When an account hits a usage limit, the request is retried on the next account, keeping the conversation context and completed tool results. An account that reached its limit is used again as soon as its limit resets. A disconnected account is skipped until you reconnect it.
Plan limits: ChatGPT and Claude subscription accounts show how much of the current usage window is used and when it resets. Since 0.21.0, a Google AI account shows its plan and weekly quota too, when its runtime reports them.
Accounts that need attention: since 0.22.0, an API key the provider refuses shows Key rejected with the provider's message, instead of looking connected, and saving or replacing a key checks it at once. A signed-in Claude account whose Claude Code is missing or too old keeps its row with Claude Code not found or Claude Code needs an update: install or update it as the card shows, then choose Check again, without restarting.

If authentication fails, sign in again and check the account status, region, and any organization or project selected at the provider.

Choose a model

Pick the model in the composer's model chip, or press Cmd+Shift+M on macOS (Ctrl+Shift+M on Windows and Linux). The list comes from each connected account and can vary by plan, region, and current availability. Filter models on an account hides models you do not use, and Default model, in the Conversation section of Settings → Maestrly Chat → Models & agents, sets the starting model; without one, a new chat starts on the last model you picked. That tab groups its models by purpose (Conversation, Background tasks, Memory, and Subagents), shows each as a chip with its provider, effort, and Fast, saves a choice at once, and sums them up under In use.

Match the model to the work:

use faster, lower-cost options for exploration and small edits;
use more capable reasoning options for broad, ambiguous, or high-risk changes;
check whether the model supports the tools, context size, or media the task requires.

A model shown by name is not an endorsement or a guarantee that your account can use it.

Reasoning effort and Fast mode

Reasoning effort sets how much the model thinks before answering; Ctrl+Tab cycles it. Only the levels the selected model supports are offered, and Default leaves the choice to the provider. Higher effort is usually slower and uses more quota.

Fast is a separate on/off switch, available on models that support it: faster responses with higher usage. It never means low effort.

Modes and permissions

The mode controls what the agent may do. Shift+Tab cycles through them:

Mode	What it does
Agent	All tools: reads, edits files, and runs commands.
Design	Builds navigable visual prototypes focused on UI/UX, with mock data.
Plan	Investigates with restricted tools and proposes a plan in the Plan tab for you to approve.
Ask	Answers with read-only MCP tools and permitted Maestrly tools, without changing code.

The permission mode decides when the agent stops for approval: Ask for approval (file edits, commands, and internet use), Approve for me (only potentially dangerous actions, such as shell commands or external directories), or Full access (never asks). Choose Full access only where mistakes are cheap to undo.

In a project, an approved plan can also start a new conversation with Implement in new conversation, and Use Maestro in the mode menu hands the conversation to Maestro, which coordinates the agents in your Agent Pool (see Concepts).

Write the first request

Include four things:

Outcome — what should be true when the work is done.
Scope — the project, files, or areas the agent may change.
Constraints — conventions, compatibility requirements, and actions to avoid.
Verification — tests, commands, or evidence expected before completion.

Attach only relevant context. Large, unrelated context consumes the model's context window and can make results less focused. While a turn runs, a new message is queued, or steers the agent on runtimes that support it.

Switch models mid-conversation

You can change the model or provider at any point. Maestrly carries the complete available conversation to the new model, including stored tool results and skill instructions. If it does not fit the destination's window, Maestrly compacts it first; if it still does not fit or compaction fails, the request is blocked instead of silently truncating context. Provider-private reasoning and session state cannot move between providers.

After switching, check the agent's understanding before authorizing consequential actions.

Context usage and compaction

The context meter shows how much of the model's working context is occupied. Hover over it to compare the last measurement with the estimate for the next request; estimates start with ~. When the runtime reports no measurement, as with Google AI and Cursor, the meter shows context unknown. Context occupancy is separate from accumulated token usage and cost.

When context runs high, a banner offers Compact, and /compact summarizes the history on demand. Maestrly also compacts before a request that would not fit. Original messages remain visible, and an open to-do list stays active across the compaction; the summary becomes the new context boundary only after every stage succeeds, and a failed compaction blocks the request without changing the history.

Click the context meter to set a Context limit for that model on that provider account, below its real window (such as 300k or 1M), or No limit to remove it. The meter shows the capped window with a lock, and Maestrly compacts the conversation at the limit before a turn. Since 0.23.0, the limit works with API providers and with the Codex, Claude, GitHub Copilot, Grok, Cursor, and Google AI subscriptions: API providers, Codex, Claude, GitHub Copilot, and Grok also compact during a turn that reaches it, while Cursor and Google AI compact between turns, so a long turn there can go past the limit. ChatGPT Web keeps its context inside ChatGPT and has no limit.

Background preparation is optional and starts off. In Settings → Maestrly Chat → Models & agents, under Background tasks → Prepare context, turn on Use background context preparation and choose a Preparation model and Preparation interval (100,000 new tokens by default). That model prepares a compacted checkpoint while the conversation keeps working, so a later compaction can use it without another summarization call. It receives the conversation content and consumes its own quota.

Attachments

Attach files with + → Image / file, by pasting, or by dragging them onto the composer.

Images: paste with Cmd/Ctrl+V. If the model cannot read images, turn on Use the image interpreter under Background tasks → Image interpreter in Settings → Maestrly Chat → Models & agents to describe them; otherwise the image is dropped from the context.
PDFs: up to 10 MB each and four per message, within a 20 MB per-message budget shared with images. The Claude subscription and Anthropic or OpenAI API models that accept PDFs receive the document (up to 100 pages); other models receive text extracted locally, without layout or images. Password-protected or damaged PDFs are rejected.
Text and code files, such as Markdown, JSON, or source files.

In the composer, @ references files or folders and # references agents. Attachments are stored in the app profile and deleted with their message or conversation; files a provider received follow its retention policy.

Interactive answers

Since 0.18.0, in chats, project conversations, and bot conversations, an agent can mix small interfaces into its answer: pages it writes in HTML, CSS, and JavaScript, shown in an isolated frame. They suit product pictures, visual comparisons, charts, diagrams, calculators, simulations, and small tools.

With Maestrly tools on, the agent can preview an interface before showing it: the app renders it at the chat's width and returns a screenshot and the problems it found.
Moving a slider or changing a field runs inside the interface and does not call the model. A button can send a message as you or open a page in your browser, only right after you interact with it.
Interfaces cannot call tools, read files, or fetch data, and keep nothing between views. They may load images, video, and audio from the web, and libraries and fonts from a few public CDNs, which see the addresses requested.
Problems the app finds, such as content wider than the answer or script errors, are listed under the interface. Interface source shows what the agent wrote. The mobile app runs interfaces too, in an isolated web view, and always asks before one sends a message or opens a page.

Turn Interactive answers off in the Tools tab of Settings → Maestrly Chat, or in the Preferences of a bot environment, to save their tokens. Answers that already have interfaces keep showing them.

Voice dictation

Click the microphone in a chat or bot composer, or press Cmd+D (Ctrl+D on Windows and Linux), to dictate; with Hold to record on, hold the button while you speak. Dictation runs on this computer, where the microphone is, whether the chat runs here, on a server, or on a bot.

Since 0.22.0, Settings → Maestrly Chat → Tools → Dictation chooses the engine:

This computer (Whisper), the default: speech never leaves the computer. whisper.cpp transcribes it locally with the Whisper large-v3-turbo model, and recordings without speech are discarded.
OpenAI (gpt-4o-transcribe) or Groq (whisper-large-v3-turbo): each recording goes to that provider with your API key and is billed to your account, about US$0.006 and US$0.0007 per minute. They handle speech that mixes languages and technical terms better, need no download, and work on any system. A recording stops by itself after 10 minutes, and Try again sends a failed one again.

Since 0.21.0, dictation takes over the composer's action bar while it records, with the time and the microphone level, and you can keep editing the text. ↑ or Enter sends the draft followed by the transcription, Insert (or Cmd/Ctrl+D again) adds the transcription to the draft for you to review, and ✕ or Esc discards the recording. Right-click the microphone to choose the microphone, Hold to record, and the Dictation language: App language by default; Detect automatically takes about twice as long.

With a bot server connected, Use on my phone too stores your engine and key on the server so the mobile app can dictate through it, and Remove from server deletes it there. The server keeps that key unencrypted in its database, like its other secrets.

The local engine's first use offers a one-time 547 MB download, listed as Voice model in Settings → Maestrly Chat → Components, or Use an API key instead. It needs macOS 15 or later on Apple silicon, or Windows x64 or Linux x64, where it runs on the CPU and is slower.

Memory

Personal memory holds facts and preferences, such as your language and response style, shared by your standalone chats across providers. Open Settings → Maestrly Chat → Models & agents → Memory → Manage personal memory to search, edit, pin, archive, and export entries. Automatic saving starts off and needs its own model.
Project memory belongs to a workspace. With Recall relevant memories automatically on (the default), each message can recall up to three relevant memories, listed in a chip under the message. Save memories from conversations uses a Memory model you choose and starts off. Both are in the Memory section of Settings → Maestrly Chat → Models & agents; the model that saves memories is under Background tasks → Memory extraction.

Personal memory stays in this computer's app profile and does not sync between devices. Agents treat memory as evidence to check. Removing a memory stops future recall; it does not erase what a provider already received.

Search a conversation

Press Cmd/Ctrl+F in a chat or bot conversation. Enter and Shift+Enter step through matches, and Esc closes search. In bot conversations, search also covers older transcript pages and opens folded activity that contains a match. With the Conversation history tool group on, agents can search and read their own earlier messages too.

Separate windows

Open chat in new window, in the conversation header or the sidebar menu, moves a standalone chat, workspace conversation, or bot conversation into its own window, for example on another monitor. Drafts, attachments, queued messages, and live responses move with it. Close the window or choose Return to app to bring it back without stopping its work.

Agent activity

The reasoning, commands, searches, and other tool steps behind each answer fold into one activity line. It shows the current step while the agent works and a summary afterward, including failed or denied steps; open it for the details. Answers, questions, plans, subagents, artifacts, generated images, and screenshots the agent shares stay in view. To give every step its own card, choose Expanded in Settings → Appearance & sound → Agent activity; Compact is the default.

Notifications and badges

When a conversation on this computer, on a server, or on another computer finishes its turn, fails, asks you a question, or brings a plan to review, Maestrly shows a silent system notification unless you are looking at that conversation (in the focused main window or in its own focused window). Clicking the notification opens the conversation, in its own window when it has one. A newer notification replaces the conversation's last one, opening the conversation removes it, and a turn that brought a plan shows only the plan's notification.

Alert sounds play for the same events (Turn ready, Turn failed, Permission request, Plan to review). Turn notifications off with System notifications in Settings → Appearance & sound; muting the sounds does not turn them off. Bots notify too (see Bots).

The app icon counts what needs you: the conversations with a red dot in the sidebar (on this computer and on the servers and computers it reaches) plus the count on the Bots tab. On macOS the count shows on the Dock icon, on Linux on launchers that support it, and on Windows a red mark shows on the taskbar button.

Troubleshoot a request

Unauthorized or forbidden: sign in again and verify account, project, organization, or model permissions.
Model unavailable: select another available model or check the provider's status and regional access.
Usage or rate limit: wait for the window to reset, reduce parallel work, or add fallback accounts for automatic rotation.
Context too large: use Compact, remove unrelated attachments, split the task, or choose a model with a larger window.
Compaction failed: retry or compact manually; if it keeps failing, check the provider connection.
Tool unsupported: choose a compatible model or remove the capability from the task.

Provider logs and billing dashboards are the source of truth for request status and charges. See Usage and costs.