Problemas comuns

O que fazer quando algo do Faundr não funciona como esperado. Comece sempre por:

/faundr:status

Ele mostra o servidor em uso, se há token, qual projeto está ligado, a branch e onde fica o registro de erros do plugin, e diz o que falta configurar.

O painel não mostra as minhas sessões

Confira, nesta ordem:

1. O plugin está instalado? No Claude Code, /plugin mostra os plugins instalados; no Codex, rode codex plugin list no terminal. Se o Faundr não aparece, veja Instalação e primeiro projeto. Depois de instalar, feche e abra o agente.
2. Você fez o login? Se /faundr:status mostra "token (não configurado)", rode /faundr:login.
3. A pasta está ligada? O agente precisa estar aberto na pasta do código, ou numa pasta dentro dela, e essa pasta precisa ter o .faundr.json. Se não estiver ligada, rode /faundr:link.
4. É o projeto certo? O /faundr:status mostra o projeto ligado. Se for outro, rode /faundr:link com o nome certo.

Se tudo isso estiver certo, veja o registro de erros do plugin, em ~/.faundr/hook.log. O Faundr nunca trava o agente: quando algo falha, ele anota ali e segue.

"Sem token. Faça o login primeiro"

O computador não tem um token salvo. Rode /faundr:login, confira o código no navegador e clique em Autorizar.

"Token inválido"

O token deste computador não vale mais (por exemplo, foi apagado em Minha conta → Token do plugin). Rode /faundr:login de novo.

"Pasta não ligada a um projeto"

O comando precisa de uma pasta ligada. Rode /faundr:link na pasta do código. Se você trabalha em várias pastas, cada uma precisa ter o próprio .faundr.json (ou estar dentro de uma que tenha).

O /faundr:link não mostra o meu projeto

• O projeto pode estar em outra organização. O link lista os projetos de todas as suas organizações; confira o nome.
• O seu papel pode ser Leitura, que só olha o painel e não liga pastas. Peça a um Dono ou Admin para mudar o seu papel em Time.

Os comandos /faundr:… não aparecem

O plugin não está carregado. Rode /plugin para ver se ele está instalado e ativo, e reabra o agente depois de instalar ou atualizar. No Codex, as skills se chamam com $: digite $faundr para ver a lista.

No Codex, o Faundr não aparece nas sessões

O Codex só roda os hooks do Faundr depois que você confia neles. Abra o Codex, digite /hooks e confie nos do Faundr. Depois de cada atualização do plugin, o Codex pede de novo.

No Codex, um comando do Faundr deu "fetch failed"

O Codex roda os comandos do agente sem internet. Rode $faundr:setup e aceite a Regra do Codex, que libera só o comando do Faundr para usar a rede. Ela vale a partir da próxima sessão. Até lá, aprove quando o Codex pedir para rodar o comando fora da área protegida.

O agente continua depois de parecer que terminou

É a conferência do fim da resposta: o Faundr pediu ao agente para provar que o código funciona, deixar o bilhete de passagem, revisar telas ou conferir o critério de pronto. É esperado. O Claude Code mostra esse pedido como "Stop hook error", mas não é um erro; no Codex, ele aparece como um novo pedido logo abaixo da resposta. A última resposta, a que vem depois do aviso, é a completa: traz o que importava da anterior e o resultado da conferência. Veja O que o Faundr faz sozinho.

O agente pediu confirmação para um comando

O Faundr achou o comando arriscado: ele pode apagar trabalho ou dados. Leia a explicação, e confirme só se for isso mesmo que você quer. No Codex, o comando é barrado e o agente pergunta a você no chat; com o seu sim, ele roda o mesmo comando de novo e o Faundr deixa passar uma vez. Quando o risco é nos arquivos, um ponto de volta já foi salvo antes. Veja Proteção contra desastres.

Um comando foi barrado

O Faundr barra o que não tem volta (apagar o disco, zerar o banco de produção) e pacotes que não existem. O agente não deve procurar outro caminho. Se você tem certeza, rode o comando à mão, no seu terminal.

Um achado não fecha depois de corrigido

Na maioria dos achados, o Faundr só fecha depois de refazer a checagem e confirmar que o problema sumiu. Se continua aberto:

• a correção pode não ter resolvido. Rode a checagem de novo (/faundr:security-scan, /faundr:quality-scan) e veja o detalhe;
• num erro E-n, ele fecha quando o mesmo comando volta a passar. Rode o mesmo comando que falhou;
• num erro do app publicado, use "Resolvido no próximo deploy": ele fecha de vez quando a versão nova vai ao ar.

O mapa do código diz "grafo atualizando" ou está vazio

• Se o projeto nunca gerou o mapa, rode /faundr:map.
• "Atualizando" é normal depois de edições: o mapa é refeito no fim da resposta, em segundo plano.
• Se ele continua desatualizado, rode /faundr:map de novo.

Os testes não rodam

• O Faundr só roda testes quando alguém pede: !faundr tests-run.
• Se os testes parecem usar o banco de produção, ele não roda até você confirmar. Crie um .env.test com um banco de teste.
• Se falta a ferramenta (o executor, a medição de cobertura), ele mostra o comando para instalar. Ele nunca instala sozinho.

O /faundr:undo diz que precisa de git

Os pontos de volta ficam no git do projeto. Se a pasta ainda não usa git, o agente oferece rodar git init. A partir daí, os pontos começam a ser salvos.

A conferência do fim gasta muitos tokens

O aviso do fim da resposta é a parte do Faundr que mais gasta. O quanto aparece em Insights → Tokens, na parte "Aviso do fim da resposta". Ele quase sempre só dispara nas respostas que mudaram arquivos, e cada pedido (bilhete, Stack, Visão) tem um limite de frequência.

Para gastar menos, ligue o modo econômico: a auditoria rápida de design e as atualizações da Stack e da Visão passam a rodar só quando você pede. O /faundr:setup mostra quanto o fim das respostas custou nos últimos 30 dias e oferece o modo; no terminal, faundr setup --economy all liga e faundr setup --no-economy desliga. A prova, o bilhete e a segurança continuam sempre.

Uma skill minha não aparece no painel

O Faundr lê as skills de três lugares, no Claude Code e no Codex: as do repositório (pastas .claude/skills e .agents/skills), as suas skills pessoais (em ~/.claude/skills, ~/.agents/skills ou ~/.codex/skills) e as dos plugins ligados nesta pasta (no Codex, os ligados no config.toml). Cada sessão relê a lista sozinha. Se uma skill nova ainda não apareceu em Workflows → Skills, rode /faundr:skills: ele lê de novo e escreve quando usar cada uma. Uma skill que acha problemas só manda o resultado ao painel depois de marcada como Conectada, o que o /faundr:skills faz e dá para trocar no detalhe da skill. Veja Workflows.

O /faundr:browse diz que falta a chave

O navegador rápido usa o Jev, um serviço de fora, que precisa de uma chave. Ponha a chave numa variável de ambiente do seu computador e rode, no terminal, faundr browse-key --env TYPESAFE_API_KEY (troque pelo nome da sua variável). Nunca cole a chave no chat. Se o comando usa o seu Chrome (--chrome) e diz que a extensão não respondeu, instale ou recarregue a extensão do Faundr em chrome://extensions.

O app não sobe no computador com a pasta no OneDrive

Pastas sincronizadas pelo OneDrive, Google Drive ou iCloud podem confundir ferramentas de desenvolvimento, que às vezes deixam de encontrar pacotes já instalados. Se o npm run dev diz que pacotes como react "não estão instalados" mesmo estando, mova o projeto para uma pasta fora da sincronização, como C:\dev. Isso não é do Faundr, mas é comum em quem está começando.

Ainda com problema?

Mande para quem cuida do Faundr:

• o resultado de /faundr:status;
• as últimas linhas de ~/.faundr/hook.log;
• a versão do plugin, que aparece em /plugin.