Troubleshooting

Maestri is a deeply interactive app — closer to a strategy game engine than a typical desktop utility. We work hard to keep it stable, but with so many moving parts on the canvas, things occasionally misbehave. Here's how to recover when they do.

Windows blocks the Maestri installer with Smart App Control

Windows shows a dialog titled "Smart App Control blocked an app that might be unsafe" when Smart App Control blocks something it cannot verify, including apps distributed outside the Microsoft Store.

There is no "Run anyway" here, unlike SmartScreen. The only way through is to turn the feature off:

1. Open Windows Security.
2. Go to App & browser control.
3. Open Smart App Control settings.
4. Set it to Off.

Then run the Maestri installer again. You can turn Smart App Control back On afterwards.

No other security setting needs to change.

The canvas stops responding to input

In rare instances, focus management between the canvas and the windows on it can drift. When that happens, you may find that you can't resize or move nodes, or that keyboard shortcuts stop landing where you expect.

Open the View menu and choose Reset Focus. It clears the focus state and hands control back to the canvas, without touching your work.

If you hit this regularly in a specific situation, please report it (see below) — focus drift is something we want to squash, not work around.

Maestri is using too much memory

Maestri itself is a fully native app and idles at around 200 MB of RAM — best in class for what it does. The memory pressure you see almost always comes from the agents running inside its terminals, not from Maestri.

A single Claude Code instance, for example, typically uses 500–700 MB. Maestri actively encourages you to run many agents in parallel, so that adds up fast.

There are two built-in ways to keep things under control.

Memory limit per terminal

In Settings → Terminal → Advanced, enable Memory limit per terminal and set a maximum (in MB).

When enabled, Maestri monitors every process started inside a terminal. If any of them crosses the threshold, Maestri kills that process while keeping the shell itself alive — so you don't lose the terminal, just the runaway child. It's a great safety net for catching memory leaks or misbehaving tools before they take down your whole system.

Unload a workspace you're not using

Right-click any workspace in the sidebar and choose Unload. The workspace hibernates and releases all the resources it was holding — terminals, agents, portals, the lot.

The next time you open it, it wakes up immediately and picks up where it left off. Use this for projects you know you won't touch for a while.

The same logic applies on app launch: when Maestri starts up, only your active workspace is loaded. Every other workspace stays hibernated until you click it. To tell at a glance which workspaces are hibernated, look at the terminal icons in the sidebar — faded icons mean the workspace is hibernated, full opacity means it's loaded and running.

Codex misbehaves inside Maestri

Codex runs every command inside its own sandbox, and a few of its habits get in the way of Maestri. Update both Maestri and Codex first: newer versions fix most of what's below.

Codex can't reach Maestri, or asks before every maestri command

Codex's sandbox blocks the connection the maestri command uses to talk to the app. On the Mac it fails with Connection failed: Operation not permitted, and on Windows with access denied (err 5). Codex then asks to run the command outside the sandbox, and approving it for the session isn't enough: every new agent asks again, including the ones a Maestro recruits.

Allow maestri once. Add this line to Codex's rules file, creating it if it doesn't exist, then restart your Codex agents:

prefix_rule(pattern=["maestri"], decision="allow")

• Mac: ~/.codex/rules/default.rules
• Windows: %USERPROFILE%\.codex\rules\default.rules

Or, the next time Codex asks, choose to always allow it. Codex saves the same rule to the same file.

Only commands that start with maestri leave the sandbox. Everything else Codex runs stays inside it, with the same file and network limits, so you don't need full access or to turn approvals off. The rule covers every Codex account in Maestri and every agent a Maestro recruits. To check it, ask a Codex agent to run maestri list: it should answer without asking.

Codex asks to trust the folder on every new floor

A git-isolated floor is a copy of the project in a new folder, and Codex asks once per folder. Choose Trust, and Codex remembers it for that floor.

Codex doesn't see your environment variables

Codex builds its own environment for the commands it runs. If maestri can't find its terminal, or your tools are missing from PATH, open ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml) and check:

[shell_environment_policy]
inherit = "all"

If you keep an allowlist, add MAESTRI_* to it.

Windows: every Codex agent acts as the same terminal

maestri list shows another terminal under You:, or messages land in the wrong terminal. After reopening Maestri, commands may also fail with no daemon pipe found. Newer versions of Codex run commands through one shared background server, which keeps the first terminal's settings and outlives Maestri.

1. Right-click the terminal, choose Edit Terminal, and make sure the command includes --no-daemon. Maestri's Codex preset adds it, and the sheet warns you when it's missing.
2. Quit Maestri and end any leftover Codex processes in PowerShell:

   Get-Process codex -ErrorAction SilentlyContinue | Stop-Process
   

3. Open Maestri again.

Windows: console windows flash open and closed

This is a Codex bug, fixed in newer versions. Update Codex and start it with --no-daemon. If you run Codex's background server yourself, update it too:

codex app-server daemon update --from-cli --yes

Windows: "Access is denied" when Codex starts maestri

Codex's elevated sandbox runs commands as separate Windows users, and those users can't open Maestri's folder. Switch Codex to its unelevated sandbox in %USERPROFILE%\.codex\config.toml, then restart Codex:

[windows]
sandbox = "unelevated"

Windows: "timed out waiting for state db backfill"

The first time Codex starts on an account, it indexes your session history, and any other Codex starting there in the meantime gives up. Close every Codex terminal on that account and wait 15 minutes. Then start one Codex there, and let it finish starting before you open the others.

Windows: "setup refresh had errors"

Codex's own Windows sandbox failed to set itself up, and it happens outside Maestri too. Update Codex and restart the terminal. If it keeps failing, report it to OpenAI with that exact error.

Still stuck with Codex?

Along with the diagnostics report, send us a screenshot of the Codex terminal, the output of maestri debug run inside that terminal, and the output of codex --version.

Want fewer quirks?

Codex isn't the only way to use your ChatGPT subscription. OpenCode, Pi and Oh My Pi sign in with ChatGPT Plus or Pro, or take an API key. They are better designed, more secure and work better.

Sending us a diagnostics report

When something does go wrong, the fastest way to help us fix it is to send a diagnostics report.

1. Open Report a Problem… — from the Help menu on macOS, or from Settings → About on Windows.
2. Click Download to save the diagnostic file.
3. Email it as an attachment to bugs@themaestri.app, along with a short description of what happened and the last action you remember taking.

The more detail you can share about what you were doing right before the issue, the faster we can reproduce and fix it. Thank you for helping make Maestri better.