Mods com Jev dependem do stack do projeto? O que avaliar antes de instalar

Spoiler: o mod não roda no seu stack, ele roda dentro do Claude Code 😀

Fala aí, beleza? Agora que os mods vêm ligados por padrão no Claude Code, os mods com Jev estão ganhando espaço, e junto veio a dúvida clássica…

Meu projeto é em Python, Go ou PHP, o mod é escrito em JS/TS, será que ele serve pra mim?

Tem também uma frustração mais sorrateira: instalar um mod que espera uma estrutura de pastas que o seu repositório não tem

Aí tu fica olhando pra tela esperando algo acontecer haha

Bora entender o que um mod realmente assume do seu ambiente e como checar isso ANTES de instalar

O que é um mod do Claude Code e onde o Jev entra?

Um mod é um plugin do Claude Code cujo comportamento é um módulo de hooks em JavaScript ou TypeScript, executado dentro do próprio processo do Claude Code (está tudo na documentação oficial de mods)

Que hook?

Hook é uma função que reage a um evento do Claude Code, por exemplo quando o Claude chama uma ferramenta ou quando o spinner é desenhado na tela

Esse hook pode fazer três coisas:

• só registrar o evento e repassar
• repassar uma cópia alterada
• devolver o próprio resultado, e aí nada depois dele roda

Se você conhece middleware de servidor web, a ideia é bem parecida: o evento passa pelo seu código e você decide o que fazer com ele 🙂

Qual a estrutura mínima de um mod?

São três arquivos:

• .claude-plugin/plugin.json: o manifesto
• hooks/hooks.json: aponta pro módulo
• hooks/register.js: o módulo de hooks, que exporta register

meu-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

Repara numa coisa: nenhum desses arquivos tem a ver com a linguagem do SEU projeto

O JS/TS é a linguagem do mod, e o mod roda no Claude Code, não no seu código

Qual a diferença entre hooks de settings e mods?

Hooks de settings rodam um comando shell fora do processo do Claude Code

Os hooks de um mod são funções dentro do processo, e só mods conseguem desenhar na interface

E o Jev nessa história?

O Jev é um modelo de decisão da TypeSafe AI, lançado em 15 de setembro de 2026, que a empresa chama de modelo System One

Ele responde perguntas tipadas sobre um texto ou JSON e devolve só valores estruturados, nunca prosa

Ou seja, ele não escreve código pra você: ele decide coisas tipo ‘essa tarefa é simples?’ ou ‘essa chamada é arriscada?’

Mods com Jev são justamente os mods que consultam o Jev em algum ponto do fluxo pra tomar uma decisão

Desde quando os mods vêm ligados?

Desde o Claude Code 2.1.287, publicado em 1 de outubro de 2026

Antes disso eles ficavam em acesso antecipado atrás de flag, desde a 2.1.259 (2 de setembro de 2026)

Tome cuidado! A variável CLAUDE_CODE_ENABLE_FUNCTION_HOOKS é ignorada desde a 2.1.287, então colocar 0 nela NÃO desliga os mods

O que cada mod com Jev assume do seu ambiente?

Aqui está o ponto que interessa: cada mod tem as suas premissas, e elas aparecem na descrição e no código, não no nome

Se liga no padrão: o que aparece nas descrições são pastas .claude, versão do Claude Code e provedor do Jev

Linguagem e framework do projeto não aparecem nessas descrições

Os dois do aitmpl instalam com um comando cada:

npx claude-code-templates@latest --mod productivity/jev-model-router
npx claude-code-templates@latest --mod productivity/jev-skill-suggestion

E vale lembrar: quando um mod manda trecho do transcript pro Jev (o cc-mod-jev faz isso via OpenRouter), esse conteúdo sai da sua máquina

Antes de ligar algo assim num repositório com segredo, pense em o que anonimizar antes de enviar

Como avaliar um mod com Jev antes de instalar?

Antes do checklist, um aviso que muda tudo: um mod roda com as SUAS permissões e não é isolado em sandbox

Ele pode ler e gravar seus arquivos, iniciar processos e fazer requisições de rede

Então avaliar não é frescura, é o mínimo 🙂

1. Leia o manifesto e o register.js

Abra o .claude-plugin/plugin.json e o hooks/register.js e veja em quais eventos ele se pendura e quais pastas ele procura

A API de mods tem métodos $.session que expõem o diretório de trabalho onde o Claude Code foi aberto, então caminho relativo no código é relativo ao seu repositório

É a mesma lógica de avaliar uma skill no GitHub: o que importa é o que o código espera encontrar

O erro comum deste passo: ler só o README e pular o register.js, que é onde mora o comportamento de verdade

2. Confira a versão mínima do Claude Code

O cc-mod-jev, por exemplo, pede a 2.1.278 ou posterior com function hooks habilitados

O erro comum deste passo: tentar ligar ou desligar mods pela CLAUDE_CODE_ENABLE_FUNCTION_HOOKS numa versão 2.1.287 ou mais nova, onde ela é ignorada

3. Veja o provedor e a chave exigidos

Cada mod chama o Jev por um caminho: o cc-mod-jev usa OpenRouter, o claude-jev-mod aceita OpenRouter, Vercel AI Gateway, Cloudflare Workers AI, LiteLLM ou a API da TypeSafe

O erro comum deste passo: procurar a chave no settings.json num mod do aitmpl, sendo que esses guardam a chave no keychain do sistema

4. Cheque se ele mexe em configuração existente

O comando /jev-skill-suggestion:setup grava user-invocable-only em skillOverrides pra cada skill de usuário e de projeto

Na prática o Claude deixa de ver a skill sozinho, mas você ainda pode digitar /nome pra chamar

Tem até a issue #1013 aberta no repositório davila7/claude-code-templates relatando que o setup bloqueia skills que os autores tinham deixado o modelo rodar

O erro comum deste passo: rodar o setup sem saber que ele altera o comportamento de TODAS as suas skills

5. Escolha o escopo e instale revisando no painel

Dentro do Claude Code, /plugin install com o nome do plugin e o marketplace abre o painel /plugin nos detalhes dele, onde você revisa e escolhe o escopo

Os escopos são três:

– usuário: vale em todos os projetos da máquina, em enabledPlugins no ~/.claude/settings.json – projeto: fica registrado no .claude/settings.json do repositório pros colaboradores, que ainda precisam instalar uma vez – local: só pra você, só naquele repositório

O erro comum deste passo: instalar em escopo de usuário um mod que depende da estrutura .claude de um projeto específico, e depois estranhar o comportamento nos outros repositórios

Instalei e o mod não faz nada: quais são as causas comuns?

Calma, antes de achar que o mod não serve pro seu stack, olha esses sintomas aqui

O Jev Skill Suggestion não sugere nada útil?

Causa: não há skills nas pastas que ele lê, ou ele não acha o corpo delas

Quando o SKILL.md não está lá, o candidato fica só com a descrição de uma linha, e a escolha fica pobre

Solução: conferir se as skills estão em .claude/skills/<nome>/SKILL.md ou .claude/commands/<nome>.md, no projeto ou no home

O claude plugin test diz que o mod está desligado?

Causa: o claude plugin test reportava mods desligados por ler configuração salva desatualizada

Solução: isso foi corrigido na 2.1.288

Uso gateway e os mods aparecem desligados?

Causa: quem acessa via gateway (com ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN) sem conta Anthropic via os mods desligados

Solução: corrigido na 2.1.290

Instalei pelo shell e a sessão aberta não enxerga o mod?

Causa: a sessão já estava rodando quando você instalou

Solução: rodar /reload-plugins, que carrega numa sessão aberta o que foi instalado pelo shell

Como prevenir e como desligar um mod?

Prevenção é o checklist de cima: pasta, versão e provedor conferidos antes de instalar

E se precisar desligar, tem três níveis:

• por plugin, no painel /plugin
• por sessão, com --safe-mode
• em tudo, com disableAllHooks

Veredito: mods com Jev são genéricos na linguagem e específicos no ambiente

O stack do projeto quase nunca é o problema

Um mod em JS/TS roda dentro do Claude Code, então repositório em Python, Go ou PHP não muda nada pra ele

O que amarra um mod de verdade é:

• a estrutura .claude do repositório (e do seu home)
• a versão do Claude Code
• o provedor e a chave do Jev

O escopo de projeto faz sentido quando o time inteiro usa a mesma estrutura de skills e o mesmo provedor

Já o escopo local é melhor quando o mod mexe em configuração (tipo o setup do Skill Suggestion) ou quando só você quer experimentar

E o jev-guard está na tabela só como contraponto: ele nem é um mod, é um projeto à parte que funciona em vários agentes, o Claude Code incluso

Próximo passo antes de instalar seu primeiro mod com Jev

Escolhe um mod da tabela, abre o register.js dele e lê com calma quais eventos e pastas ele usa

Depois instala em escopo local, roda alguns dias no seu repositório e só então promove pra projeto

Inclua o custo na conta também: a TypeSafe alega US$ 0,042 por milhão de tokens de entrada, com saída gratuita, e cada mod chama o Jev numa frequência diferente (o Model Router consulta antes de cada turno, o cc-mod-jev na compactação)

Resumindo: o mod não liga pro seu stack, ele liga pro seu ambiente

Até o próximo post! 😀