Solução de problemas

Comece pelo diagnóstico

Em Configurações, no grupo geral, a tela de diagnóstico mede tudo na hora e devolve cinco linhas, cada uma com o detalhe em texto e, quando dá, um botão que conserta:

A sessão não sobreviveu

Fechar o app e perder o que estava rodando tem quatro causas possíveis:

• macOS sem tmux. O diagnóstico mostra o aviso e copia o comando de instalar.
• Versão do tmux antiga demais, ou uma versão com defeito conhecido de desenho de tela. O diagnóstico diz qual é o caso e o que atualizar.
• Windows sem o serviço do Deck de pé. Ele pode demorar no primeiro boot em máquina com antivírus. O app continua tentando em segundo plano, e as sessões criadas depois de ele subir já nascem persistentes.
• Duas cópias do Deck na mesma pasta de dados. Elas disputam o estado e os avisos, e a última a abrir rouba os ganchos da outra.

No macOS, dá para alcançar as sessões de fora do app, por qualquer terminal:

tmux -L deck ls
tmux -L deck attach -t deck-<id>

O agente não aparece

A lista de agentes mostra só quem responde ao comando de versão. Se o seu agente funciona no terminal mas não aparece no Deck:

• Confirme que ele responde ao comando de versão no mesmo shell que você usa normalmente.
• Reabra o Deck. Ele lê o caminho de busca do shell uma vez, ao iniciar.
• No Windows, depois de instalar um agente, o caminho novo pode exigir reabrir o app.

Um instalador quebrado, que existe mas falha ao rodar, conta como não instalado de propósito. Isso evita sessão que abre e morre com comando não encontrado.

O estado parou de atualizar

Se as sessões param de acender, o custo some do rodapé e as notificações silenciam, o problema é a integração com o agente. Causas conhecidas:

• Arquivo de configuração ilegível. O Deck não escreve por cima de um arquivo inválido. O diagnóstico mostra o erro.
• Codex com ganchos sem a confirmação de confiança. Ele os ignora em silêncio, e o botão de reinstalar resolve.
• Grok com um arquivo de ganchos de outra origem. O Deck não sobrescreve, e avisa.
• Linha de status de terceiro. Se você já tinha uma, ela é preservada, e o contexto e o custo deixam de aparecer no rodapé.
• Windows com o console forçado em UTF-8. Isso faz os ganchos falharem sem nenhuma mensagem. Tirar essa configuração do perfil do PowerShell resolve.

Com o Deck fechado, nada se perde: os eventos ficam anotados e entram no próximo boot. Mais sobre isso em Agentes.

O atalho global não responde

O registro do atalho global falha em silêncio quando outro aplicativo já reservou a mesma combinação. A saída é escolher outra em Configurações, no grupo geral. O app oferece alternativas prontas para cada sistema.

Casos do macOS

• A atualização recusa por app translocado. Acontece quando o Deck foi aberto direto da pasta de downloads. Mova o aplicativo para a pasta de aplicativos e abra de lá.
• Sem permissão para atualizar. Conta sem administrador com o app instalado por outra pessoa. Reinstalar pelo comando de instalação resolve, colocando o app na sua pasta pessoal.
• Microfone negado. Quem grava é o agente, mas o sistema cobra a permissão do Deck. O app mostra o aviso e abre a tela de privacidade no lugar certo.
• A barra de rolagem não acompanha o agente. Em tela cheia, o histórico que o terminal guarda não é o mesmo que o agente desenha. A rolagem do agente é dele, e o controle do Deck navega o histórico local.

Casos do Windows

• Antivírus atrasando o primeiro boot. O serviço que segura as sessões pode levar mais de dez segundos na primeira vez. O app espera e segue tentando.
• Console em UTF-8 forçado. Quebra os ganchos sem mensagem nenhuma, como descrito acima.
• Colar imagem no Claude Code. O atalho nativo dele no Windows não é o de colar comum. O Deck já manda a sequência certa.
• PowerShell antigo. O Deck prefere a versão nova quando ela existe, porque a antiga estraga acentos em texto longo.

O primeiro pedido some

Se você escreveu um pedido longo e vê no terminal um comando curto lendo um arquivo, está tudo certo. Acima de algumas centenas de caracteres o Deck grava o texto em arquivo e manda o agente ler dali, porque o terminal descarta linha muito longa sem avisar.

O limite duro é de 64 mil caracteres. Acima disso o app recusa e pede para resumir, deixando os detalhes em um arquivo do projeto.

Quando nada disso resolve

Escreva para deck@mazeanalytics.com.br com a versão do Deck, o sistema, o que você esperava e o que aconteceu. A versão instalada está em Configurações, no grupo avançado, e o resultado do diagnóstico ajuda bastante.

Se for algo que parece falha de segurança, o caminho e o que incluir estão na página de segurança. Para conferir atalhos enquanto investiga, ⌘/ abre a folha dentro do app.