Como remover um sistema do Claude Code que não funcionou para você?

Fala aí, beleza? Instalar plugin no Claude Code é fácil, qualquer um faz sem pensar muito

Desinstalar é que separa o setup limpo do setup entulhado 🙂

E aqui mora o problema: o Claude Code não tem um botão único de "remover tudo isso que eu testei semana passada"

Plugin, servidor MCP, skill, subagente, hook e memória vivem em lugares diferentes, com comandos diferentes e arquivos diferentes

Então o caminho de volta é um mapa, não um clique

Este post fecha o ciclo dos posts de instalação e adoção que já rolaram por aqui: o que precisa sair, o que costuma ficar pra trás e como confirmar que o comportamento antigo voltou de verdade

Antes de remover: faça o inventário do que está instalado

Antes de sair apagando, levanta o que existe

Parece óbvio, mas é o passo que todo mundo pula e depois passa uma hora caçando fantasma

Plugins. O comando claude plugin list (alias ls) mostra versão, marketplace de origem e status de habilitação

Dá pra filtrar por estado com --enabled ou --disabled

claude plugin list
claude plugin list --enabled
claude plugin ls --disabled

MCPs. Dentro da sessão, /mcp mostra o status dos servidores

No terminal, claude mcp list lista e claude mcp get <nome> abre a configuração de um específico

Hooks. O /hooks é um navegador dos hooks configurados: lista cada evento com a contagem de hooks, deixa abrir os matchers e ver o comando, prompt ou URL de cada handler

E mostra de qual arquivo de settings cada hook veio, que é justamente a informação que você vai precisar depois

Skills. São três origens diferentes: skills de usuário em ~/.claude/skills/, skills de projeto em .claude/skills/ e skills empacotadas em plugins instalados

Subagentes. Duas localizações: ~/.claude/agents/*.md (usuário, vale em todos os projetos) e .claude/agents/ (projeto)

Memória. São dois sistemas: os CLAUDE.md que você escreve e a auto memory que o próprio Claude grava, e cada um sai de um jeito (tem seção só sobre isso mais pra frente)

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Um aviso antes de continuar: commitar o .claude/settings.json faz com que quem clonar o repositório receba as mesmas permissões, hooks, telemetria e plugins

Ou seja, aquele item estranho pode não ter vindo da sua máquina, pode ter vindo do repo

Tome cuidado antes de apagar achando que é seu 😛

Como desinstalar um plugin do Claude Code (e limpar as dependências)

1. Desabilite antes de desinstalar. Dá pra desabilitar um plugin sem remover nada, e essa é a forma mais barata de testar se o comportamento chato realmente vinha dele

claude plugin disable <plugin>

2. Se o comando falhar, leia a mensagem de erro. Quando outro plugin habilitado depende do que você quer desabilitar, o comando falha de propósito

E a mensagem de erro traz um comando encadeado que desabilita todos os dependentes primeiro, então é só copiar e rodar

O erro comum deste passo: achar que o comando "não funcionou" e sair mexendo em arquivo de configuração na mão, quando a saída já entregou o comando pronto

3. Desinstale de verdade, com prune. A flag junta as duas coisas em um passo só: tira o plugin e limpa as dependências que vieram junto

claude plugin uninstall <plugin> --prune

O prune lista as dependências órfãs e pede confirmação antes de remover

E se liga nisso: ele remove só dependências instaladas automaticamente que nenhum plugin instalado exige mais, e nunca mexe em plugin que você instalou diretamente

4. Prefere fazer dentro da sessão? Tem versão de barra. O menu /plugin resolve, e a forma direta aceita o nome do marketplace

/plugin uninstall <plugin-name>@<marketplace-name>

5. Nomes iguais em marketplaces diferentes. Quando dois plugins instalados de marketplaces diferentes têm o mesmo nome, a forma plugin-name@marketplace-name desambigua e desinstala apenas o do marketplace indicado

O erro comum deste passo: omitir o @marketplace e desinstalar o plugin certo, mas do lugar errado

Aí você fica com a sensação de que "removeu e não mudou nada", quando na verdade removeu o gêmeo

Como remover um marketplace sem perder o resto dos plugins

1. Removendo a fonte configurada:

claude plugin marketplace remove <marketplace>

O alias é rm, se você tem preguiça de digitar (eu tenho)

2. Quando o objetivo é só atualizar. Se o que você quer é uma versão nova sem perder os plugins instalados, o comando é outro

claude plugin marketplace update <marketplace>

3. Na sessão interativa é a mesma coisa. Os subcomandos claude plugin marketplace equivalem aos /plugin marketplace de dentro da sessão

Então escolhe o que for mais confortável, o resultado é o mesmo

4. Alternativa gráfica no VS Code. Os plugins instalados aparecem no topo com chaves de liga e desliga, e tem ícone de lixeira pra remover um marketplace pela interface

Pra quem prefere clicar em vez de digitar, resolve bem

O erro comum deste passo: remover o marketplace achando que isso desinstala os plugins que vieram dele

São coisas separadas: tirar a fonte não tira o que já foi instalado a partir dela

Como remover um servidor MCP e os escopos que ele deixou para trás

Essa aqui é a limpeza que mais rende, na minha opinião

MCP esquecido é o entulho clássico do Claude Code

1. Localize:

claude mcp list

2. Confira a configuração antes de apagar:

claude mcp get <nome>

3. Remova:

claude mcp remove <nome>

4. Entenda os três escopos. O Claude Code tem escopo local (o padrão), project (compartilhado via .mcp.json) e user (vale em todos os projetos), selecionados por -s ou --scope

E cada um grava em um lugar diferente do disco: servidores de escopo project ficam no .mcp.json na raiz do projeto, enquanto user e local ficam no ~/.claude.json

O erro comum deste passo: mexer em um escopo e o servidor continuar aparecendo, porque a entrada real estava em outro

Se sumiu da lista de um projeto mas volta em todos os outros, provavelmente a entrada de verdade é de escopo user

5. Resete as aprovações que ficaram. O Claude Code pede aprovação em sessões interativas antes de usar servidores de escopo project vindos do .mcp.json

Se você quer zerar essas escolhas:

claude mcp reset-project-choices

Como tirar uma skill que atrapalhou mais do que ajudou

1. Descubra a origem antes de apagar qualquer pasta. São três: skill de usuário em ~/.claude/skills/, skill de projeto em .claude/skills/ e skill empacotada em plugin instalado

2. Skill de usuário ou de projeto: remova o diretório da skill

A parte boa é que a mudança é captada na sessão em andamento: adicionar, editar ou remover skill em ~/.claude/skills/ e no .claude/skills/ do projeto é detectado sem restart

Não precisa fechar e abrir o Claude Code, beleza?

3. Skill que veio de plugin: mexa no plugin, não na pasta. O caminho é desabilitar ou desinstalar o plugin que fornece a skill, pelo menu /plugin ou direto

/plugin uninstall <plugin-name>@<marketplace-name>

O erro comum deste passo: apagar a skill de um subdiretório e ela continuar carregando

Skills de projeto são carregadas do diretório onde o Claude Code foi iniciado E de todos os diretórios acima, até a raiz do repositório

Então existe uma cópia num diretório pai te assombrando, é quase sempre isso

Como remover um subagente depois que o /agents mudou

Subagentes são arquivos Markdown com frontmatter YAML, e é isso que salva a sua vida aqui

1. Ache o arquivo. Ele está em ~/.claude/agents/*.md (usuário, vale em todos os projetos) ou em .claude/agents/ (projeto)

2. Remova apagando o .md correspondente. É literalmente isso, sem menu, sem comando especial

3. Entenda a mudança de versão pra não se perder. A partir da v2.1.198, o /agents apenas imprime um lembrete pra pedir ao Claude ou editar .claude/agents/ direto

Na v2.1.197 e anteriores existia um assistente com aba Library pra criar, editar e apagar subagente ali mesmo no terminal

O erro comum deste passo: procurar aquele menu que apagava subagente, não achar, e concluir que subagente não pode mais ser removido

Os arquivos, os campos de frontmatter e as duas pastas não mudaram

Só o assistente no terminal saiu 🙂

Como desativar um hook e desfazer o que ficou no settings.json

1. Abra o /hooks pra investigar. Ele lista cada evento com a contagem de hooks, deixa abrir os matchers e ver o comando, prompt ou URL de cada handler

E, o mais importante pra remoção: mostra de qual arquivo de settings aquele hook veio

2. Apague a entrada no JSON de settings. O /hooks é somente leitura, ele não remove nada

Então a remoção é editar o arquivo de settings na mão, ou pedir pro próprio Claude fazer a edição

3. Não precisa reiniciar. O Claude Code observa os arquivos de settings e recarrega quando eles mudam, e a maior parte das edições vale na sessão em andamento

Isso inclui permissões, hooks e credential helpers como apiKeyHelper

Falando em permissões, é aqui que mora boa parte do trabalho de impedir edições que você não pediu, então vale conferir o que ficou configurado antes de sair apagando bloco por bloco

O erro comum deste passo: editar o arquivo errado por ignorar a precedência

A ordem é: managed settings primeiro, depois --settings, depois user settings (~/.claude/settings.json), depois settings de projeto (.claude/settings.json) e locais (.claude/settings.local.json)

Se você apagou o hook no arquivo de projeto e ele continua rodando, é bem provável que ele exista também num arquivo de precedência maior

Como limpar a memória que o Claude gravou sozinho sobre o projeto

Aqui tem uma confusão comum: são DOIS sistemas de memória, não um

Os arquivos CLAUDE.md são as instruções que você escreve

A auto memory são as notas que o próprio Claude grava a partir das suas correções e preferências

1. Limpe o que é seu. Nível de projeto fica em CLAUDE.md ou .claude/CLAUDE.md do diretório de trabalho, nível de usuário fica em ~/.claude/CLAUDE.md

2. Ache o que o Claude escreveu sozinho. A auto memory fica em uma pasta por projeto, derivada do repositório git

~/.claude/projects/<project>/memory/

Dentro tem um índice MEMORY.md e um arquivo por tópico

3. Abra e limpe pela sessão. Roda /memory e seleciona a pasta de auto memory

É markdown puro, você pode ler, editar ou apagar sem cerimônia

O erro comum deste passo: limpar num worktree achando que é isolado

Worktrees e subdiretórios do mesmo repo compartilham a MESMA pasta de memória

Já dá pra imaginar a confusão: você apaga em um lugar e a nota reaparece do outro lado, como se o Claude tivesse teimado com você haha

Removi e o comportamento continuou: o que costuma ficar para trás

Agora a parte que ninguém documenta

Remover não é só rodar o comando, é entender por que o resíduo sobrevive

Sintoma: desinstalei o plugin mas ele ainda aparece habilitado no papel

Causa: uma entrada do plugin em enabledPlugins em qualquer escopo tem precedência sobre o padrão do plugin

E tem a nuance: entradas em .claude/settings.json ou .claude/settings.local.json do projeto são ignoradas pra pluginConfigs, mas enabledPlugins continua honrando settings de projeto e local

Solução e prevenção: procure enabledPlugins em TODOS os escopos antes de concluir que a remoção falhou, e evite deixar essa chave escrita em vários arquivos ao mesmo tempo

Sintoma: apaguei a permissão e ela continua valendo

Causa: quando a mesma chave de lista aparece em mais de um arquivo, o Claude Code combina as listas em vez de escolher uma

Listas como permissions.allow são somadas entre arquivos, então um arquivo não apaga a entrada do outro

Solução e prevenção: remova a entrada em cada arquivo onde ela existe, e concentre permissões em um lugar só pra não virar caça ao tesouro

Sintoma: limpei a configuração e ela voltou sozinha

Causa: o próprio Claude Code escreve arquivos

O ~/.claude/settings.json é escrito quando você muda uma opção no menu /config que salva em user settings

E o .claude/settings.local.json é escrito quando você dá aprovação permanente em um prompt de permissão

Solução e prevenção: depois de limpar, evite clicar em "sempre permitir" naquele mesmo prompt, senão o arquivo é reescrito na hora

Sintoma: removi da minha máquina e o time inteiro continua com o item

Causa: o .claude/settings.json foi commitado, e quem clona o repositório recebe as mesmas permissões, hooks, telemetria e plugins

Solução e prevenção: trate o settings versionado como código de verdade, com revisão, porque ele é configuração distribuída

Sintoma: a skill funciona local e some no Cowork e em sessões na nuvem

Causa: sessões Cowork e sessões na nuvem, incluindo routines, não leem o ~/.claude/skills/ da sua máquina

Cada execução de routine começa como sessão remota nova, e o Claude Code reporta que a skill não foi encontrada

Solução e prevenção: se a skill precisa rodar remoto, ela não pode viver só na pasta de usuário local

Como confirmar que o comportamento antigo voltou

Sensação não é verificação

Depois de limpar, roda o checklist:

1. Estado dos plugins:

claude plugin list --enabled
claude plugin list --disabled

2. Status dos servidores MCP na sessão: /mcp

3. Hooks: /hooks, pra ver se o evento ficou realmente sem handler

4. Memória: /memory, pra abrir a pasta de auto memory e checar se a nota que você apagou não voltou

5. Custo de contexto: /context conta tokens por grupo de ferramentas e mostra a linha de Skills já com o orçamento aplicado, batendo com o que o modelo recebe

Se você removeu skill e a linha não mexeu, algo ainda está sendo carregado

6. Diagnóstico mais fundo: /doctor dentro da sessão e claude doctor no terminal

Dá pra estimar o custo de contexto da listagem, ver os maiores contribuintes e, na versão de linha de comando, as entradas rejeitadas

Uma observação que economiza dor de cabeça: /status e /config abrem o mesmo diálogo em abas diferentes, e a aba Config NÃO é uma visão do conteúdo do seu settings.json

O erro comum deste passo: usar a aba Config como prova de que a chave sumiu do arquivo

Não é prova, abre o arquivo e confere

O que aprendi limpando meu próprio setup para parar de queimar token

Eu cheguei nesse assunto pelo lado do custo, não pelo lado da organização

As sessões do Claude Code passaram a durar menos aqui, a cota parecia estar sendo consumida de forma mais agressiva, e eu fui atrás de estratégias pra reduzir consumo de token

E o que apareceu na frente foi exatamente isso: o que você instalou pra testar e nunca removeu

Muita gente instala um MCP só pra experimentar, deixa a instalação global e nunca tira

Aí esse MCP segue sendo carregado nos projetos seguintes, sem necessidade nenhuma

Pior: um MCP esquecido pode acabar sendo acionado sem intenção, porque o modelo julga que ele faz sentido pro prompt que você mandou

Consumo de token à toa, sem você pedir nada

No vídeo eu mostro na tela a lista de MCPs ativos do projeto aberto, separando o que vem do escopo local, do usuário e do projeto, justamente pra enxergar o que está ligado

Virou rotina: começo projeto novo, olho a lista, desconecto o que não vou usar naquele trabalho

E prefiro instalar MCP por projeto, nos arquivos de configuração do Claude, em vez de deixar tudo global

O mesmo raciocínio vale pro .claude/settings.json que você commita: ele propaga configuração pro time inteiro, então o entulho vira entulho coletivo

Meu critério prático na hora de remover é sempre o mesmo: desabilita primeiro, mede, desinstala depois

Olha /context antes, desabilita, olha /context de novo

Se a linha não mexeu, o problema não era aquilo, e você acabou de economizar uma remoção desnecessária

É o mesmo espírito de medir antes de pedir melhoria de performance: sem número na mesa, você está chutando

Tem também o lado de impedir que o Claude entre em pasta que não precisa ler, tipo node_modules, usando o arquivo de ignore do Claude

Ele não vai necessariamente ler essas pastas, mas pode acabar acessando por engano e poluindo o contexto

Eu prefiro deixar a restrição explícita, e dá pra pedir pro próprio Claude criar esse arquivo pra você

No fim, minha conclusão foi radical e simples: começar com ZERO MCP conectado, e só ligar o que for realmente necessário naquele projeto

Porque o que fica ligado sem uso continua poluindo o contexto e queimando token, mesmo que você nunca use

No vídeo abaixo eu destrincho isso com mais dicas, se quiser ver na prática:

Um setup limpo é mais fácil de reconstruir do que um setup entulhado

A ideia toda é de ciclo: instalar, testar, remover sem medo

Quando você sabe desmontar, você experimenta MUITO mais, porque o custo de errar cai perto de zero

O plano concreto que eu sugiro: uma vez por mês, roda o inventário completo

claude plugin list, /mcp, /hooks, /memory e /context

Olha o que está ligado, pergunta "eu usei isso no último mês?" e trata o que sobrou

Começa sempre desabilitando antes de desinstalar, mede a diferença, e só então tira de vez

E se você chegou aqui vindo de algum dos posts de instalação e adoção do blog, agora o ciclo fechou: tem o caminho de ida e tem o caminho de volta 🙂

Até o próximo post!