Como instalar mods do Claude Code

Este guia mostra como instalar mods do Claude Code em cada uma das três formas que o Claude Code oferece: uma linha dentro de uma sessão em andamento, dois comandos no seu terminal ou um carregamento temporário a partir de uma pasta local. Os exemplos usam o marketplace do ClaudeMods (rotbit/claudemods-marketplace) e o mod cm-git-branch; troque pelo nome de qualquer outro mod.

Mods são plugins, então os comandos são os mesmos comandos de plugin que você talvez já conheça. Toda página de mod neste site tem um bloco de instalação que já preenche os nomes certos para você.

Do que eu preciso antes de instalar um mod?#

Primeiro, confira sua versão:

claude --version

Você precisa do Claude Code 2.1.287 ou posterior no terminal. O app desktop roda mods a partir da 2.1.286. Se a sua versão estiver atrasada, atualize o Claude Code antes de continuar; versões mais antigas não rodam mods.

Se a sua empresa gerencia o Claude Code, um administrador pode ter limitado os mods a uma lista aprovada. Se um mod não carregar no trabalho, fale com quem gerencia as suas configurações.

Opção 1: instalar dentro do Claude Code em uma linha#

Em qualquer sessão, digite:

/plugin install cm-git-branch --marketplace rotbit/claudemods-marketplace

Informe só o nome do plugin, sem o sufixo @. O Claude Code adiciona o marketplace se ainda não o conhecer (pedindo sua confirmação antes), instala o mod e o carrega na sessão atual. Essa forma exige o Claude Code 2.1.275 ou posterior, o que qualquer versão compatível com mods já é.

Repare que /plugin install rotbit/claudemods-marketplace sozinho não funciona: sem --marketplace, o argumento precisa ser plugin@marketplace, e você recebe um erro "marketplace not found".

Opção 2: instalar pelo terminal#

Adicione o marketplace uma vez e depois instale quantos mods dele quiser:

claude plugin marketplace add rotbit/claudemods-marketplace
claude plugin install cm-git-branch@claudemods

O texto depois do @ é o nome do marketplace definido no marketplace.json dele (claudemods), não o nome do repositório. A mensagem de sucesso depois do marketplace add informa o nome que você deve usar.

Por padrão, os dois comandos gravam nas suas configurações de usuário, então o mod fica disponível em todos os projetos. Use --scope project para compartilhá-lo com um repositório, ou --scope local para mantê-lo só para você em um projeto:

claude plugin install cm-git-branch@claudemods --scope project

Sessões que já estavam abertas só enxergam o novo mod depois que você roda isto dentro delas:

/reload-plugins

Se preferir clicar, /plugin install cm-git-branch@claudemods dentro de uma sessão abre a tela de detalhes do mod no menu de plugins, onde você escolhe o escopo.

Opção 3: testar um mod sem instalar#

Para testar um mod a partir de uma pasta local, por exemplo um clone do repositório dele ou um mod que você está escrevendo, carregue-o por uma única sessão:

claude --plugin-dir ./cm-git-branch

Nada é gravado nas suas configurações. O mod recebe o id cm-git-branch@inline e desaparece quando você sai. Você pode passar --plugin-dir mais de uma vez, e salvar uma alteração no módulo de hooks faz o recarregamento sem reiniciar. Para confirmar o que foi carregado, rode:

claude --plugin-dir ./cm-git-branch plugin list

A saída tem uma seção "Session-only plugins" com a versão do mod e o status de carregado. Essa também é a forma mais segura de revisar um mod: rode antes claude plugin validate ./cm-git-branch e leia as linhas hooks: e calls:.

Como verifico se um mod está rodando?#

Abra o /plugin. Abaixo das abas, uma linha esmaecida como 1 mod active · cm-git-branch lista os mods que foram carregados. No terminal, claude plugin list mostra os plugins instalados e se cada um está ativado; adicione --json para usar em scripts.

Se o mod aparece na lista mas você não vê nada, confira onde está rodando. Mods só desenham no terminal e na aba Code do app desktop. No painel de chat do VS Code ou com claude -p, os hooks rodam, mas não há interface.

Como configuro um mod?#

A maioria dos mods declara opções com valores padrão. Logo depois da instalação, o Claude Code pode exibir uma linha dizendo que algumas opções de userConfig ainda não foram definidas. Isso é esperado; os padrões são aplicados.

Para mudar uma opção, abra o /config em uma sessão e procure as linhas do mod, ou use /plugin configure. O mod é recarregado com os novos valores. No terminal, você pode definir opções na hora da instalação:

claude plugin install cm-git-branch@claudemods --config hideWhenClean=true

ou depois, enviando por pipe um objeto JSON com valores em string:

echo '{"intervalMs": "5000"}' | claude plugin configure cm-git-branch --values-stdin

As opções que você deixar de fora mantêm os valores atuais. Rodar claude plugin configure cm-git-branch sem a flag mostra todas as opções e quais ainda não foram definidas. Cada página de mod lista as opções em uma tabela na seção "Personalize".

Como atualizo, desativo ou desinstalo um mod?#

Atualize para a versão mais recente do marketplace:

claude plugin update cm-git-branch@claudemods

A nova versão é carregada na sua próxima sessão, ou imediatamente depois de /reload-plugins.

Desligue um mod sem removê-lo, e ligue de novo:

claude plugin disable cm-git-branch
claude plugin enable cm-git-branch

Dentro de uma sessão, /plugin disable cm-git-branch faz a mesma coisa. Adicione -s project (ou user, local) quando o mod tiver sido instalado em um escopo diferente de user.

Para removê-lo por completo:

claude plugin uninstall cm-git-branch

Passe --keep-data para manter o diretório de dados do mod, ou --prune para remover também as dependências que foram instaladas automaticamente e não são mais necessárias. A cópia em cache é limpa mais tarde; claude plugin prune faz isso na hora.

Para desligar todos os mods em uma sessão, inicie o Claude Code com claude --safe-mode. Para mantê-los todos desligados, defina "disableAllHooks": true nas suas configurações.

Solução de problemas: mod que não carrega#

Siga estes passos na ordem:

• Versão. claude --version precisa ser 2.1.287 ou posterior.
• Recarregar. Depois de instalar ou atualizar pelo terminal, rode /reload-plugins ou inicie uma nova sessão.
• Ativado. O mod precisa estar ativado na aba Installed do /plugin. Mods desativados ficam instalados, mas não são carregados.
• Nome. claude plugin install precisa de plugin@marketplace-name. Rode claude plugin marketplace list para ver os nomes que você adicionou.
• Superfície. Não ter interface no chat do VS Code, no claude -p ou no Agent SDK é o comportamento esperado.
• Política. Configurações gerenciadas podem restringir mods a uma lista aprovada ou bloquear o --plugin-dir.
• Conflitos. Dois mods escrevendo no mesmo lugar, como a linha de status, podem esconder um ao outro. Desative um de cada vez para descobrir.

Se um mod continuar se comportando mal, confira a página dele em busca de problemas conhecidos, ou reporte o problema informando sua versão do Claude Code e a saída de claude plugin validate na pasta do mod. A referência completa de comandos está na documentação da CLI de plugins. É novo em mods? Comece por o que são os mods do Claude Code e depois escolha um no diretório.