Claude Code no Obsidian: dá para limpar notas órfãs, links quebrados e duplicatas do vault?

Todo vault que tu usa de verdade vira depósito uma hora

Nota que ninguém referencia, link apontando pra lugar nenhum, o mesmo assunto escrito em dois arquivos com nomes quase iguais…

Aí a busca começa a devolver ruído no lugar de resposta, e a vontade de "soltar uma IA lá dentro pra arrumar tudo" bate forte

O que mudou nessa conversa é que o Obsidian passou a ter uma CLI oficial, liberada pra todos os usuários na versão 1.12.4 do desktop (publicada em 27/02/2026; antes disso ela ficou em acesso antecipado pros membros Catalyst, no 1.12.0)

E tem também uma skill oficial de Obsidian pra agentes, publicada pelo próprio CEO da Obsidian

Ou seja: falar de Claude Code Obsidian hoje não é mais gambiarra com script reescrevendo teus arquivos por fora do app

Mas tem limite, e o limite é a parte mais importante deste post, então segura a ansiedade de sair apagando nota 🙂

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O que você precisa antes de começar

Lista curta, sem PC da Nasa, mas com alguns pontos que não dá pra pular:

• Obsidian desktop na versão 1.12.4 ou superior, que é onde a CLI oficial foi liberada pra todos
• A CLI habilitada nas configurações: ela não vem ligada por padrão, tu liga em Settings (Configurações) → General (Geral) e segue as instruções da tela pra adicionar o binário ao PATH do sistema
• O Obsidian ABERTO enquanto tu roda os comandos
• Claude Code instalado na tua máquina
• Saber onde o Claude Code pode escrever: ele só escreve na pasta em que foi iniciado e nas subpastas dela, e ler caminho fora desse limite com Read, Grep e Glob passa por um prompt de aprovação
• Se tu tem mais de um vault, o comando precisa saber em qual: informa vault="Nome" no comando, porque por padrão a CLI conecta no vault ativo

E por que o Obsidian precisa estar rodando?

Porque a CLI oficial é um controle remoto do aplicativo, não uma ferramenta headless independente

Os comandos passam pelas APIs internas do Obsidian, então se o app está fechado não tem ninguém do outro lado pra atender

Isso parece um detalhe chato, mas é justamente o que salva teu vault, e já já tu vai entender o motivo

O que dá pra delegar e o que exige decisão sua

Antes de qualquer comando, separa as duas pilhas

Um lado é leitura e busca, o agente faz melhor e mais rápido que você

O outro lado é decisão editorial e mudança de arquivo, e ali tu não terceiriza

A régua que eu usaria é essa: delega o mapa, não a caneta

Como usar o Claude Code pra limpar o vault, passo a passo

1. Instala a skill oficial de Obsidian no Claude Code

São dois comandos de plugin, rodados dentro da sessão:

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

O repositório é o kepano/obsidian-skills, de Steph Ango (kepano), CEO da Obsidian

Ele traz as skills defuddle, json-canvas, obsidian-bases, obsidian-cli e obsidian-markdown, seguindo a especificação Agent Skills, então roda em agentes compatíveis, incluindo Claude Code, Codex e OpenCode

O erro comum deste passo: achar que instalar a skill já dá acesso ao teu vault, não dá, acesso é o passo 2

2. Estende o diretório de trabalho até a pasta do vault

São três formas: o argumento --add-dir <caminho> na inicialização, o comando /add-dir durante a sessão, ou a chave additionalDirectories nos arquivos de settings

/add-dir /caminho/para/o/seu/vault

Nos diretórios adicionais a leitura passa a não pedir prompt, e a edição segue o modo de permissão que tu estiver usando

O erro comum deste passo: iniciar o Claude Code em qualquer pasta e sair pedindo varredura, aí a leitura fora do limite fica abrindo prompt de aprovação e a escrita nem acontece

3. Confirma que a CLI está respondendo

obsidian help

Esse comando lista os comandos disponíveis, e a sintaxe geral segue sempre a mesma ordem: primeiro obsidian, depois o vault, o comando, o subcomando, os pares chave=valor e por último as flags

Vault, subcomando e flags são partes opcionais, dependendo do comando que tu roda

Valor com espaço vai entre aspas, sempre

O erro comum deste passo: rodar com o Obsidian fechado e achar que a instalação deu ruim, lembra que a CLI é controle remoto do app

4. Pede o relatório de varredura, em modo somente leitura

Aqui tu escreve a instrução com todas as letras: mapear e explicar, sem alterar nada nesta rodada

Um pedido tipo esse funciona bem:

Varra o vault em /caminho/para/o/seu/vault e monte um relatório com:
1) notas sem nenhum backlink
2) links internos que apontam para arquivos inexistentes
3) pares de notas que tratam do mesmo assunto
Use o comando de busca da CLI do Obsidian para checar termos repetidos.
NAO edite, NAO renomeie e NAO apague nada nesta rodada. Só relatório.

Pra checar termo repetido, a busca da CLI é essa:

obsidian search query="segundo cérebro"

Escrever a regra antes de soltar o agente é a mesma lógica de fazer ele respeitar o design system do projeto: sem limite escrito, ele inventa

E se teu vault for grande, essa varredura lê MUITO arquivo, então vale dar uma olhada em como gastar menos no Claude Code antes de sair rodando isso todo dia

O erro comum deste passo: esquecer o vault="Nome" quando tu tem mais de um vault, porque por padrão o comando vai no vault ativo, que pode não ser o que tu quer limpar

5. Revisa o relatório e decide item a item

Órfã de 2023 com três linhas soltas? provável lixo

Órfã que é um rascunho de artigo que tu ainda vai escrever? fica

Duas notas do mesmo assunto? tu escolhe qual vira a nota principal e o que migra da outra

O erro comum deste passo: aprovar a lista inteira de uma vez porque "tá tudo certo", e aí descobrir depois que sumiu uma nota que era ponto de entrada de um projeto

6. Aplica só o que foi aprovado, e rename/move sempre pela CLI

O comando move da CLI move e/ou renomeia, e os backlinks do vault são atualizados pelo próprio Obsidian, igualzinho a arrastar o arquivo na interface

É por isso que o app precisa estar aberto: a operação passa pelo runtime dele, não é um mv no sistema de arquivos

O erro comum deste passo: deixar o agente reescrever caminho direto dentro dos arquivos, na mão, em massa

Tome cuidado! esse é o caminho mais rápido pra transformar faxina em estrago

Problemas comuns nessa faxina (e como não criá-los)

"Renomeei e agora meia dúzia de notas aponta pra lugar nenhum"

Causa: o rename saiu por fora do Obsidian, mexendo direto no arquivo

O Obsidian só acompanha o rename quando ele acontece dentro do app, então reescrita em massa feita externamente não dispara esse acompanhamento e tudo que apontava pro nome antigo fica quebrado

Solução: refazer a operação pelo comando move da CLI, que passa pelo runtime do app e atualiza as referências

Prevenção: regra escrita na sessão, proibindo o agente de alterar caminho de arquivo por conta própria

"O comando não responde"

Causa: ou o Obsidian não está em execução, ou a CLI nem foi habilitada

Solução: abre o app e confere a habilitação em Settings → General, seguindo as instruções da tela pra deixar o binário no PATH

Prevenção: obsidian help como primeiro comando de toda sessão de faxina, se ele lista os comandos, tá tudo de pé

"Não confio na lista de órfãs e quebrados que o agente montou"

Esse ceticismo é saudável, e a saída é cruzar com plugin da comunidade em vez de discutir com o agente

O Find orphaned files and broken links (id find-unlinked-files, mantido por Vinzent03) varre o vault atrás de arquivos sem nenhum backlink e gera uma nota com a lista de órfãos e outra com a lista de links quebrados

Já o Broken Links (id broken-links) foca nos links internos que apontam pra arquivo, cabeçalho ou bloco inexistente, e consolida as ocorrências em três visões: por pasta, por arquivo e por link

O arranjo que faz sentido é esse: o plugin é a fonte da lista, o Claude Code é quem lê, interpreta e propõe o que fazer com cada item

Um gera o dado, o outro gera o julgamento, e tu assina embaixo

Conclusão

Dá pra usar o Claude Code no Obsidian pra limpar o vault, sim, mas não como "aperta o botão e some a bagunça"

O formato que se sustenta é de duas fases: o agente varre e explica, tu decide item a item, e a CLI executa o que mexe em arquivo

Órfã não é lixo por definição, duplicata não escolhe sozinha qual versão sobrevive, e rename em massa por fora do app é o jeito clássico de quebrar backlink em silêncio

Próximo passo concreto, na ordem: habilita a CLI nas configurações, instala a skill oficial, roda uma primeira varredura em modo somente leitura e só depois aplica o que tu aprovou

Sem promessa de automação total, beleza? faxina de vault é decisão editorial com ajuda de máquina, não o contrário

até o próximo post!