JEV instalado e o Claude Code não reconhece: por onde começar o diagnóstico

Fala aí, beleza? Você seguiu o passo a passo direitinho, o terminal disse que instalou, e mesmo assim o Claude Code responde como se o JEV nunca tivesse existido

Calma que na MAIORIA das vezes isso não é bug

É sessão que não recarregou, escopo que ficou no lugar errado ou nome de chamada diferente do que você imagina

E a boa notícia: esses erros têm uma ordem de probabilidade bem conhecida, dá pra diagnosticar por checklist em vez de sair chutando e reinstalando tudo 🙂

Antes do diagnóstico: qual JEV você instalou?

Essa pergunta vem antes de qualquer comando

Porque "instalar o JEV" pode significar três coisas bem diferentes, e o sintoma de cada uma é diferente também

A) O Jev como modelo hospedado da TypeSafe

O Jev é um modelo que responde por uma API própria, com chave própria

A chamada é um POST https://api.typesafe.ai/v1/systemone, autenticação Bearer, com a chave lida da variável de ambiente TYPESAFE_API_KEY e o modelo recomendado jev-latest

Repare no detalhe: isso NÃO é nativo do Claude Code

Se você só criou uma chave e esperava que o Claude Code passasse a ter uma ferramenta nova, o problema não é instalação, é expectativa

B) A skill oficial da TypeSafe (via marketplace de plugins)

A skill oficial é instalada assim:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Aqui mora a pegadinha que responde metade dos relatos

Essa skill é documentação para o agente: ela é licenciada em MIT, carrega o contexto da API System One (tipos de pergunta, padrões, boas práticas) e não tem nenhum hook nem comando executável

Ou seja: ela não adiciona ferramenta de chamada ao Jev

Dá pra invocar ela sim, pelo /typesafe:typesafe-ai (ou pedindo "use a skill da TypeSafe" no prompt), só que o que entra é CONTEXTO, não uma ferramenta que conversa com a API

Se você instalou o caminho B e ficou esperando o Claude Code sair chamando o modelo sozinho, ele vai continuar "não reconhecendo" pra sempre, porque não é isso que a skill faz

C) O jev-code, projeto da comunidade

O jev-code é um projeto mantido por FrancoisChastel, distribuído no npm como @francoischastel/jev-code

Não confunda com o oficial: o repositório oficial de skills da TypeSafe é typesafe-ai/skills

O setup dele pro Claude Code faz duas coisas: copia a skill para ~/.claude/skills/jev/ e registra o servidor MCP em escopo de usuário

jev-code setup claude
# copia a skill para ~/.claude/skills/jev/
# e roda: claude mcp add --scope user jev -- npx -y @francoischastel/jev-code mcp

Depois do setup, as ferramentas aparecem com prefixo MCP, no formato mcp__jev__jev_classify e equivalentes, e a skill responde por /jev

Esse é o caminho que de fato coloca ferramentas na mesa do agente

Sabendo qual caminho é o seu, o resto do diagnóstico fica muito mais rápido

Passo zero: os comandos que mostram o que o Claude Code realmente carregou

Antes de reinstalar qualquer coisa, olhe o estado da sessão

"Instalado" e "carregado" são coisas diferentes, e é aí que quase todo mundo se perde

1. Rode /mcp dentro da sessão. Ele lista os servidores configurados, o status de conexão (connected / failed) e se foram aprovados no projeto atual. O erro comum deste passo: ver o nome na lista e concluir que está tudo certo, sem olhar o status nem a aprovação

2. Rode claude mcp list no terminal. Quando um servidor falha, o detalhe do erro entra na própria linha de status. O erro comum: rodar só dentro do Claude e não checar a visão da CLI

3. Rode claude mcp get <nome> pra abrir o caso. Ele mostra na linha Issue: o status HTTP ou código de erro e o texto retornado, por exemplo um 401 com credencial inválida. O erro comum: reinstalar o servidor quando o problema era autenticação

4. Use /context e /hooks pra ver o que entrou na sessão. São eles que mostram o que realmente carregou, não o que você acha que carregou

5. Rode /doctor. Ele faz um checkup completo, propõe correções e pede confirmação antes de aplicar. O erro comum: pular essa etapa e já partir pros rm -rf da vida, que são caminho válido, porém só DEPOIS de saber o que está quebrado

6. Abra /plugin e olhe as abas Installed e Errors. Confirme que o plugin está listado E habilitado, e veja se tem erro registrado. O erro comum: assumir que instalado é igual a habilitado

7. Valide o frontmatter das skills pela CLI:

claude plugin validate .claude/skills
claude plugin validate ~/.claude/skills

O primeiro comando vale para skills de projeto, o segundo para as pessoais

O erro comum aqui: skill com YAML quebrado que simplesmente não entra, e o terminal nunca gritou nada

Esse mesmo roteiro serve pra outras extensões, viu? Se você já passou por quando o Ponytail não aparece, a lógica é idêntica

Causa 1: a sessão não foi reiniciada (ou o plugin não foi recarregado)

Sintoma: você instalou, o terminal não reclamou de nada, e o comando simplesmente não existe dentro do Claude

Causa: plugin instalado no meio da sessão precisa ser ativado

O comando pra isso é /reload-plugins

E tem um detalhe que pega muita gente: se o reload invalidar o cache de prompt, o Claude avisa e deixa o plugin pendente

Nesse caso, /reload-plugins --force ativa mesmo assim, ao custo de uma requisição sem cache

Com skills a regra é um pouco mais generosa

Mudanças em ~/.claude/skills/ ou .claude/skills/ são captadas na sessão corrente, sem reiniciar nada

A exceção é a que derruba todo mundo: se a pasta de skills de topo não existia quando a sessão começou, é preciso reiniciar o Claude Code pra ele passar a observar o diretório novo

E se você mexeu no .mcp.json na unha, não tem jeito

Esse arquivo é lido no início da sessão, então é sair e reiniciar

Prevenção: instale antes de abrir a sessão longa

E depois de atualizar a skill oficial, lembre do ciclo completo:

claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai
# depois: reinicie o Claude Code ou rode /reload-plugins

Atualizar sem recarregar é o clássico "mas eu já atualizei" que não muda nada na sessão aberta

Causa 2: escopo errado (funciona num projeto e desaparece no outro)

Sintoma: o JEV responde lindamente num repositório e some quando você abre outro

Se é isso, pode parar de investigar instalação: é escopo

Causa no lado MCP: o claude mcp add grava em escopo local por padrão, e local vale só no projeto atual

As outras opções:

• --scope user registra pra todos os projetos (grava em mcpServers no ~/.claude.json)
• --scope project usa o .mcp.json na raiz do repositório

E aqui vem a parte que confunde de verdade

Quando o mesmo NOME de servidor existe em mais de um escopo, existe precedência: local sobrepõe project, que sobrepõe user

Traduzindo: uma entrada local antiga e quebrada mascara a configuração boa que você acabou de criar em user

Você jura que registrou certo, o /mcp mostra failed, e a culpa é de um registro esquecido no projeto

Causa no lado skill: skills pessoais moram em ~/.claude/skills/ e skills de projeto em .claude/skills/ dentro do repositório

As de projeto carregam a partir da pasta onde a sessão foi aberta e das pastas acima, até a raiz

Skills que estão em .claude/skills/ abaixo do diretório de início não carregam no startup: elas entram na primeira vez que o Claude lê ou edita um arquivo daquela subpasta, e aí ficam disponíveis pelo resto da sessão

Ou seja, abrir o Claude Code na pasta errada já é motivo suficiente pro JEV "não existir"

No caminho jev-code, o jev-code setup claude usa --scope user

Se você prefere prender no repositório, existe a flag --project

E dá pra olhar o plano antes de qualquer coisa acontecer:

jev-code setup claude --dry-run
jev-code setup claude --project
jev-code setup claude codex pi opencode

O último exemplo mostra que é possível nomear os harnesses na chamada

Prevenção: escolha UM escopo padrão pro seu fluxo e confirme no /mcp do projeto onde você está reclamando, não no projeto onde funciona

Causa 3: nome errado na chamada

Sintoma: o Claude responde que não conhece o comando, e você jura que a skill está lá

Causa: skills vindas de plugin têm nome namespaced

O formato é /nome-do-plugin:nome-da-skill

Pra você ter a intuição: a pasta hello dentro do plugin my-first-plugin vira /my-first-plugin:hello

Com isso na cabeça, os nomes do JEV param de ser mistério

• Skill oficial da TypeSafe: /typesafe:typesafe-ai (ou simplesmente pedir "use a skill da TypeSafe" no prompt)
• Caminho jev-code: a skill é /jev, e as ferramentas aparecem com prefixo MCP, no formato mcp__jev__jev_classify e equivalentes

Digitou /jev esperando a skill oficial? Não vai achar

Procurou jev na lista de ferramentas esperando ver o nome cru, sem o prefixo mcp__? Também não vai achar

Vale lembrar da mecânica por trás: toda skill precisa de um SKILL.md com frontmatter YAML entre os marcadores --- e conteúdo markdown

O nome do DIRETÓRIO vira o comando que você digita, e a description é o que orienta o carregamento automático

Então renomear pasta na mão muda o comando, e descrição vaga faz a skill nunca ser puxada sozinha

Prevenção: rode claude plugin validate no caminho certo e confira o nome da pasta antes de acusar o Claude de esquecido

Quando a resposta vier estranha em vez de ausente, aí o caso é outro: vale perguntar antes de aceitar a resposta

Causa 4: aparece, conecta e falha na chave (ou a conta nem existe)

Sintoma: o servidor está listado no /mcp, mas com status failed

Ou a ferramenta é chamada e devolve erro na cara

Causa: a chave da API do Jev usada pelo jev-code vem de variável de ambiente exportada no shell, a TYPESAFE_API_KEY, com a chave criada no console da TypeSafe

E o diagnóstico é direto:

claude mcp get jev
# olhe a linha Issue:

Ela mostra o status HTTP ou código de erro e o texto retornado

Um 401 com credencial inválida é o caso clássico: não é instalação, é chave

Tem um contexto que você precisa saber antes de gastar a tarde nisso

A TypeSafe anunciou pausa temporária de novos cadastros do Jev por causa de demanda, com as contas já criadas continuando a funcionar e promessa de reabrir o acesso

Então se você tentou criar conta agora e não conseguiu chave nenhuma, o "não reconhece" tem explicação bem mais simples que config 🙂

Existe também o caminho do OpenRouter, que lista o Jev com mais de uma referência de modelo: typesafe/jev-latest e typesafe/jev-1.13

O preço listado do jev-1.13 é de US$ 0,042 por milhão de tokens de entrada e US$ 0 por milhão de tokens de saída

Prevenção: teste a variável no MESMO shell que abre o Claude Code

Exportar a chave num terminal e abrir o agente noutro é um erro silencioso e muito mais comum do que parece

Último recurso: limpar o cache de plugins

Sintoma: tudo parece certo, escopo conferido, nome conferido, e as skills do plugin continuam invisíveis

Antes de qualquer coisa drástica, abra /plugin

Na aba Installed, confirme que o plugin está listado e habilitado

Na aba Errors, veja se ele registrou alguma falha

Se persistir mesmo assim, o caminho documentado é esse:

rm -rf ~/.claude/plugins/cache
# depois: reinicie o Claude Code e reinstale o plugin

Tome cuidado com a ordem: limpar cache sem reiniciar e sem reinstalar não resolve, só te faz repetir o problema com cara nova

Prevenção: evite editar arquivos de plugin na mão

É a forma mais rápida de criar um estado que nem você nem o Claude conseguem explicar depois

O que aprendi montando camadas extras no Claude Code

Eu passei por essa dor recentemente testando o Printing Press, e foi didático demais

Tentei rodar o comando no terminal e tomei um belo "comando não reconhecido"

Na hora levantei duas hipóteses: ou era cache do terminal, ou a instalação do binário tinha dado ruim

Só que ao testar de novo com calma, a real apareceu: eu tinha DIGITADO o comando errado

Erro humano, puro e simples, não era instalação nem ferramenta

Corrigi a digitação e funcionou normal

Guarde esse aprendizado, porque ele vale pro JEV também: antes de acusar o Claude Code de não reconhecer nada, confira o nome exato que você digitou

A segunda parte foi menos culpa minha

Ao instalar uma skill (usei o pacote de voos como exemplo), o binário instalou certinho, mas a instalação da skill em si falhou

E não foi a primeira vez: eu já tinha batido nesse mesmo erro seguindo a documentação oficial noutra ocasião

A saída foi testar um comando alternativo, com flags diferentes, pra forçar a instalação da skill

Dessa vez pareceu funcionar

A moral que eu tiro disso pro dia a dia: instalar não é carregar, e carregar não é chamar pelo nome certo

Por isso eu virei chato com /context e /mcp antes de reclamar de qualquer coisa

São dez segundos que te poupam de reinstalar um plugin que já estava lá, só esperando um reload

No vídeo acima eu mostro esse processo acontecendo ao vivo: o comando que não roda, as hipóteses que levantei, e o momento em que a skill falha na instalação mesmo com o binário certo

É um bom retrato de como extensões carregam (ou não carregam) no Claude Code

Resumo do roteiro e próximo passo

A pergunta que vem antes de tudo: qual JEV você instalou?

Modelo hospedado com API própria, skill oficial que é só documentação pro agente, ou o jev-code da comunidade que registra MCP de verdade

Respondida essa, siga a ordem de probabilidade:

1. Sessão: /reload-plugins, --force se ficar pendente, reiniciar se a pasta de skills não existia antes ou se você editou o .mcp.json na mão
2. Escopo: local sobrepõe project, que sobrepõe user, e skill de projeto depende da pasta onde a sessão abriu
3. Nome: /typesafe:typesafe-ai no caminho oficial, /jev e mcp__jev__jev_classify no jev-code
4. Chave: TYPESAFE_API_KEY exportada no mesmo shell, e claude mcp get pra ler a linha Issue:
5. Cache: só no fim, depois de olhar /plugin nas abas Installed e Errors

O próximo passo prático é bem simples

Abra a sessão atual, rode /doctor e /mcp, e ANOTE o que aparece antes de reinstalar qualquer coisa

Na maioria dos casos o diagnóstico já termina aí, sem chute nenhum =)

Até o próximo post!