Solução de Problemas
O Maestri é um app profundamente interativo — mais próximo de um motor de jogo de estratégia do que de um utilitário de desktop comum. Trabalhamos duro para mantê-lo estável, mas com tantas peças se movendo no canvas, eventualmente algo se comporta mal. Aqui está como recuperar quando isso acontece.
O Windows bloqueia o instalador do Maestri com o Controle inteligente de aplicativos
O Windows mostra uma janela com o título "O controle inteligente de aplicativos bloqueou um aplicativo que pode não ser seguro" quando o Controle inteligente de aplicativos bloqueia algo que não consegue verificar, incluindo aplicativos distribuídos fora da Microsoft Store.
Não existe um botão "Executar mesmo assim" aqui, diferente do SmartScreen. A única forma de passar é desativar o recurso:
- Abra a Segurança do Windows.
- Vá em Controle de aplicativos e navegador.
- Abra Configurações do controle inteligente de aplicativos.
- Mude para Desativado.
Depois, rode o instalador do Maestri novamente. Dá para reativar o Controle inteligente de aplicativos quando quiser.
Nenhuma outra configuração de segurança precisa mudar.
O canvas para de responder a inputs
Em casos raros, o gerenciamento de foco entre o canvas e as janelas que vivem nele pode se perder. Quando isso acontece, você pode descobrir que não consegue redimensionar ou mover nós, ou que atalhos de teclado deixam de funcionar onde você espera.
Abra o menu Visualizar e escolha Resetar Foco. Isso limpa o estado de foco e devolve o controle ao canvas, sem mexer no seu trabalho.
Se você cair nessa situação com frequência num cenário específico, por favor reporte (veja abaixo) — perda de foco é algo que queremos eliminar, não contornar.
O Maestri está usando muita memória
O Maestri em si é um app 100% nativo e fica em torno de 200 MB de RAM em repouso — o melhor da categoria pelo que entrega. A pressão de memória que você vê quase sempre vem dos agentes rodando dentro dos seus terminais, não do Maestri.
Uma única instância do Claude Code, por exemplo, costuma usar 500–700 MB. O Maestri encoraja ativamente você a rodar vários agentes em paralelo, então isso soma rápido.
Existem duas formas embutidas de manter tudo sob controle.
Limite de memória por terminal
Em Configurações → Terminal → Avançado, ative Limite de memória por terminal e defina um máximo (em MB).
Quando ativado, o Maestri monitora todos os processos iniciados dentro de um terminal. Se algum deles ultrapassar o limite, o Maestri encerra esse processo e mantém o shell vivo — você não perde o terminal, só o processo descontrolado. É uma ótima rede de segurança para pegar vazamentos de memória ou ferramentas se comportando mal antes que derrubem o sistema inteiro.
Descarregar um workspace que você não está usando
Clique com o botão direito em qualquer workspace na barra lateral e escolha Descarregar. O workspace hiberna e libera todos os recursos que estava segurando — terminais, agentes, portais, tudo.
Na próxima vez que você abrir, ele acorda imediatamente e retoma de onde parou. Use isso para projetos que você sabe que não vai tocar por um tempo.
A mesma lógica vale na inicialização do app: quando o Maestri abre, só o seu workspace ativo é carregado. Todos os outros ficam hibernados até você clicar neles. Para identificar de relance quais workspaces estão hibernados, olhe para os ícones de terminal na barra lateral — ícones esmaecidos indicam workspace hibernado, opacidade cheia significa carregado e rodando.
O Codex se comporta mal dentro do Maestri
O Codex roda todo comando dentro do próprio sandbox, e alguns hábitos dele atrapalham o Maestri. Atualize o Maestri e o Codex primeiro: versões novas resolvem a maior parte do que está abaixo.
O Codex não alcança o Maestri, ou pede permissão a cada comando maestri
O sandbox do Codex bloqueia a conexão que o comando maestri usa para falar com o app. No Mac ele falha com Connection failed: Operation not permitted, e no Windows com access denied (err 5). O Codex então pede para rodar o comando fora do sandbox, e aprovar só para a sessão não basta: cada agente novo pede de novo, inclusive os que um Maestro recruta.
Libere o maestri uma vez. Adicione esta linha ao arquivo de regras do Codex, criando o arquivo se ele não existir, e reinicie seus agentes Codex:
prefix_rule(pattern=["maestri"], decision="allow")
- Mac:
~/.codex/rules/default.rules - Windows:
%USERPROFILE%\.codex\rules\default.rules
Ou, na próxima vez que o Codex pedir, escolha liberar sempre. O Codex salva a mesma regra no mesmo arquivo.
Só os comandos que começam com maestri saem do sandbox. Todo o resto que o Codex roda continua dentro dele, com os mesmos limites de arquivos e rede, então você não precisa de acesso total nem de desligar as aprovações. A regra vale para todas as contas do Codex no Maestri e para todos os agentes que um Maestro recruta. Para conferir, peça a um agente Codex para rodar maestri list: ele deve responder sem pedir nada.
Nota
Quando o maestri está dentro de um comando de shell maior, como um loop, a regra não se aplica, e o Codex continua pedindo antes de rodá-lo.
O Codex pede para confiar na pasta a cada andar novo
Um andar com git isolado é uma cópia do projeto em uma pasta nova, e o Codex pergunta uma vez por pasta. Escolha Trust, e o Codex lembra disso para aquele andar.
O Codex não vê suas variáveis de ambiente
O Codex monta o próprio ambiente para os comandos que roda. Se o maestri não encontra o terminal dele, ou suas ferramentas somem do PATH, abra ~/.codex/config.toml (no Windows, %USERPROFILE%\.codex\config.toml) e confira:
[shell_environment_policy]
inherit = "all"
Se você mantém uma lista de permitidas, adicione MAESTRI_* a ela.
Windows: todo agente Codex age como o mesmo terminal
O maestri list mostra outro terminal em You:, ou as mensagens chegam no terminal errado. Depois de reabrir o Maestri, os comandos também podem falhar com no daemon pipe found. Versões novas do Codex rodam os comandos por um único servidor em segundo plano, que guarda as configurações do primeiro terminal e continua vivo depois que o Maestri fecha.
- Clique com o botão direito no terminal, escolha Editar Terminal e confira se o comando inclui
--no-daemon. O preset do Codex no Maestri já adiciona, e a janela avisa quando ele está faltando. - Feche o Maestri e encerre os processos do Codex que sobraram, no PowerShell:
Get-Process codex -ErrorAction SilentlyContinue | Stop-Process - Abra o Maestri de novo.
Windows: janelas de console abrem e fecham piscando
É um bug do Codex, corrigido nas versões novas. Atualize o Codex e inicie ele com --no-daemon. Se você mesmo roda o servidor em segundo plano do Codex, atualize ele também:
codex app-server daemon update --from-cli --yes
Windows: "Access is denied" quando o Codex inicia o maestri
O sandbox elevado do Codex roda os comandos como usuários separados do Windows, e esses usuários não conseguem abrir a pasta do Maestri. Mude o Codex para o sandbox não elevado em %USERPROFILE%\.codex\config.toml e reinicie o Codex:
[windows]
sandbox = "unelevated"
Windows: "timed out waiting for state db backfill"
Na primeira vez que o Codex inicia em uma conta, ele indexa o seu histórico de sessões, e qualquer outro Codex que inicia ali nesse meio-tempo desiste. Feche todos os terminais Codex dessa conta e espere 15 minutos. Depois inicie um Codex ali, e deixe ele terminar de abrir antes de abrir os outros.
Windows: "setup refresh had errors"
O próprio sandbox do Codex no Windows não conseguiu se configurar, e isso acontece fora do Maestri também. Atualize o Codex e reinicie o terminal. Se continuar falhando, reporte para a OpenAI com esse erro exato.
Ainda com problemas no Codex?
Junto com o relatório de diagnóstico, mande um screenshot do terminal do Codex, a saída do maestri debug rodado dentro desse terminal e a saída do codex --version.
Quer menos manias?
O Codex não é o único jeito de usar sua assinatura do ChatGPT. O OpenCode, o Pi e o Oh My Pi entram com o ChatGPT Plus ou Pro, ou com uma chave de API. São mais bem projetados, mais seguros e funcionam melhor.
Enviando um relatório de diagnóstico
Quando algo dá errado, a forma mais rápida de nos ajudar a corrigir é enviar um relatório de diagnóstico.
- Abra Reportar um Problema… — pelo menu Ajuda no macOS, ou em Configurações → Sobre no Windows.
- Clique em Baixar para salvar o arquivo de diagnóstico.
- Envie por e-mail como anexo para bugs@themaestri.app, junto com uma descrição curta do que aconteceu e a última ação que você lembra de ter feito.
Nota
O arquivo de diagnóstico é totalmente anônimo. Ele contém metadados do sistema e logs e crashes recentes do app — nenhum código, nenhuma saída de terminal e nada dos seus workspaces.
Quanto mais detalhe você compartilhar sobre o que estava fazendo logo antes do problema, mais rápido conseguimos reproduzir e corrigir. Obrigado por ajudar a melhorar o Maestri.