Claude Code no Obsidian: o que muda quando o agente edita direto no seu vault?

Um agente de terminal escrevendo dentro das suas anotações pessoais parece coisa de setup maluco, mas é das integrações mais bobas que existem

Fala aí, beleza? Nesses últimos meses eu andei fuçando bastante Obsidian e tem uma coisa que confunde quem tenta juntar as duas ferramentas: não tem integração oficial, não tem API secreta, não tem plugin obrigatório

O que faz isso funcionar é onde o Obsidian guarda as suas notas

E é isso que eu quero explicar aqui: o que muda de verdade, na prática, quando o Claude Code trabalha direto no seu vault

O que é um vault do Obsidian na prática

Vault, ou cofre, é uma pasta no seu sistema de arquivos

Só isso mesmo, sem pegadinha 🙂 O Obsidian funciona sobre uma pasta local de arquivos de texto puro em Markdown, e essa pasta é o vault

Cada nota é um arquivo .md, texto puro com sintaxe Markdown

Os dados ficam locais, acessíveis offline, sem formato proprietário no meio do caminho

E os links entre notas?

Os links internos usam a sintaxe de wikilink

[[Zettelkasten]]
[[Zettelkasten|o método de notas atômicas]]

Ou seja: a rede de conhecimento que aparece bonita no grafo é, no disco, um monte de colchete dentro de arquivo de texto

E as configurações?

As configurações do vault ficam em arquivos JSON dentro da pasta de configuração .obsidian, que vive dentro do próprio vault

Dado de plugin também: cada plugin guarda o seu data.json na pasta dele

Se você já mexeu com projeto de código, a analogia é direta: o vault é o repositório, as notas são os arquivos e o .obsidian é a pasta de config do projeto

É por isso que o vault é legível por QUALQUER ferramenta que saiba abrir arquivo de texto

Inclusive um agente de terminal

O que muda quando o agente edita direto no seu vault

O Claude Code, por padrão, enxerga os arquivos do diretório em que foi iniciado

Abriu o terminal dentro da pasta do vault? Pronto, pra ele o seu segundo cérebro é só um conjunto de arquivos markdown

Na prática isso quer dizer que ele consegue:

• ler o conteúdo das notas que já existem
• criar arquivos .md novos
• reescrever notas antigas
• montar wikilinks ligando uma nota na outra

Nada disso é recurso especial de integração, é leitura e escrita de arquivo

"Mas e se o Obsidian estiver aberto na hora?"

Essa é a dúvida que trava quase todo mundo que tenta, e a resposta é boa: é seguro editar uma nota do Obsidian por outro aplicativo, inclusive com o Obsidian aberto

O app percebe o arquivo salvo externamente e reindexa a nota

E se você tinha uma alteração ainda não salva no editor (existe uma janela de auto-save de 2 segundos), as versões são mescladas automaticamente, com aviso de modificação externa

Então não precisa ficar fechando o Obsidian toda vez que for chamar o agente, beleza?

Controles e limites: permissão, CLAUDE.md e desfazer

Agente soltinho dentro das suas notas pessoais assusta, e com razão

Se liga no que segura ele

Permissão e escopo

O acesso é limitado ao diretório de trabalho e às subpastas: escrever fora dali exige permissão explícita

A aprovação é por ferramenta (Read, Edit, Write) e vale até o fim da sessão

Se você cansar de confirmar edição a cada arquivo, existe o modo acceptEdits, que permite criar e editar arquivos no diretório de trabalho sem perguntar

Quando a tarefa é grande e você quer ver o plano antes de qualquer arquivo ser tocado, vale conhecer o modo plano do Claude Code e segurar o agente antes da primeira edição

CLAUDE.md: onde moram as suas regras de nota

O CLAUDE.md é um arquivo Markdown na raiz do projeto que o Claude Code lê no início de toda sessão

No contexto de vault, ele vira o lugar onde você escreve como as suas notas devem ser: nomenclatura de arquivo, estrutura de cabeçalho, quando usar wikilink, onde cada tipo de nota mora

O comando /init gera uma versão inicial dele

O /memory lista e abre os arquivos de memória

Dica de quem já apanhou: regra genérica não pega, escreva a regra como você explicaria pra outra pessoa que fosse escrever a nota no seu lugar

Se você quiser empacotar esses comportamentos de forma reutilizável, aí entra o papo de skills, comandos e subagentes, cada um resolvendo uma coisa diferente

Desfazer, e o limite honesto do desfazer

O Claude Code tira snapshot dos arquivos antes de cada alteração

Pra voltar, é o /rewind (ou Esc duas vezes com o campo vazio), com as opções de restaurar código, conversa ou os dois

Os checkpoints ficam salvos junto com a conversa

Tome cuidado com uma coisa: os checkpoints só registram mudanças feitas pelas ferramentas de edição de arquivo

O que passa por comandos Bash ou por processo externo NÃO é capturado

E arquivo symlink ou hard link é pulado na restauração

Traduzindo pro seu vault: se o agente resolver mover nota em massa via comando de shell, o /rewind não vai te salvar disso

Para que serve juntar Claude Code e Obsidian

Todo caso de uso aqui embaixo nasce do mesmo fato chato e maravilhoso: o vault é texto puro

• Virar fonte em nota ligada: você joga o material bruto em Markdown na pasta e pede pro agente escrever notas a partir dele, já conectando os assuntos com wikilink
• Reorganizar e renomear em lote: renomear arquivos, mover pra outra subpasta, padronizar o cabeçalho de dezenas de notas de uma vez
• Padronizar estrutura de nota: a regra fica no CLAUDE.md, e toda nota nova já sai no formato que você definiu
• Gerar página derivada: a partir do que já está indexado no vault, o agente escreve a nota de resumo, a nota de comparação, o índice de um tema

Repara que nenhum desses casos depende de recurso novo

É leitura e escrita de arquivo markdown, do começo ao fim

Como isso se comporta num vault real

Eu mantenho 2 vaults só pra tutorial, então falo aqui do que eu vi acontecer, não do que deveria acontecer

O método que eu testei é bem simples de descrever: uma pasta pro conteúdo bruto, outra pra wiki que o modelo gera, e um loop entre as duas

Eu copiei o conteúdo de um Gist com as instruções do método, colei dentro do Claude Code junto com o pedido de configurar o vault, e completei dizendo o tema: conteúdo sobre IA, num recorte generalista

O Claude Code criou a estrutura de pastas sozinho, pedindo confirmação e permissão em vários momentos, tanto na configuração quanto na compilação depois

Pra alimentar a pasta bruta eu uso um clipper de navegador que converte artigo da web em Markdown e manda pro vault, o que evita conversão manual

Às vezes ele não consegue jogar o arquivo direto no Obsidian aberto, aí é salvar o arquivo e mover na mão mesmo, sem drama

E não precisa ser artigo: serve qualquer documento, incluindo transcrição de vídeo, desde que esteja em Markdown pro Obsidian entender

Na demonstração eu coletei artigos sobre modelos de IA, joguei tudo na pasta de conteúdo bruto e pedi pra compilar

O resultado: 4 artigos indexados como fontes viraram 19 páginas de wiki

Deu pra acompanhar em tempo real o agente indexando as fontes e escrevendo as páginas, organizadas em categorias como fontes, modelos, entidades e conceitos, além de atualizar os arquivos gerais do vault

A visão de grafo do Obsidian foi se formando conforme a base crescia, e ela mostra os pontos em comum entre as ferramentas estudadas, coisa que lendo artigo solto você não enxerga

O ponto que eu mais gosto: a curadoria continua sendo sua, a escrita fica com o modelo

Você compara ferramenta com dado que VOCÊ juntou, em vez de depender de um benchmark cuja metodologia você não faz ideia de qual é

E não precisa de banco vetorial, servidor nem infra nenhuma: é Markdown local, que você versiona no Git ou guarda na nuvem se quiser

Um aviso de quem se empolgou: não despeja tudo de uma vez sempre

Na primeira carga tudo bem, depois é um artigo ou outro conforme a base avança

Veja o método em vídeo

No vídeo abaixo eu mostro o processo inteiro rodando: a configuração do vault, o clipper mandando artigo pra pasta bruta, o Claude Code compilando a wiki e o grafo se formando no final

O que você precisa antes de apontar o Claude Code para o vault

Nada de exótico aqui, mas tem um pré-requisito que pega muita gente de surpresa (o último da lista)

1. Obsidian instalado, com um vault criado: o app é gratuito para uso pessoal, e existe licença comercial e os serviços pagos Sync e Publish à parte
2. Node.js 18 ou superior: o erro comum deste passo é descobrir isso só depois, com a instalação falhando por versão velha de Node
3. Claude Code instalado como pacote global do npm:

npm install -g @anthropic-ai/claude-code

4. Checar se ficou tudo certo com o diagnóstico embutido:

claude doctor

5. Conta paga: o Claude Code requer conta Pro, Max, Team, Enterprise ou Console

O plano gratuito do Claude.ai NÃO inclui o Claude Code, então não adianta tentar por ali

E os caminhos alternativos?

Se você não quiser só abrir o terminal na pasta do vault, existem outras rotas

Tem um plugin de Claude Code voltado pra vault mantido no repositório tuan3w/obsidian-vault-agent, com instalação em duas etapas:

claude plugin marketplace add tuan3w/obsidian-vault-agent
claude plugin install obsidian-vault-agent --scope project

Ele exige Claude Code, uv e Obsidian

E tem também plugins da comunidade do Obsidian que embutem o Claude Code dentro do próprio app, como o Claudian (repositório YishenTu/claudian) e o Claude Code IDE, ambos listados no diretório de plugins da comunidade

Conclusão

A resposta pra pergunta do título é meio anticlimática, e eu gosto disso: o que muda é que o seu conhecimento pessoal deixa de estar preso num app e passa a ser matéria-prima editável

Formato aberto é o recurso todo

Markdown em texto puro, wikilink em colchete, config em JSON dentro do próprio vault, tudo local

O agente não precisa de integração porque não tem nada pra integrar: já é arquivo

Próximo passo concreto, na ordem:

1. abre o terminal na pasta do vault (é ali que o Claude Code enxerga)
2. começa por uma cópia do vault ou por uma subpasta isolada, até pegar confiança
3. escreve as suas regras de nota no CLAUDE.md da raiz
4. deixa o /rewind à mão pra desfazer o que não gostou

E aí é rodar, olhar o resultado e ajustar a regra

É assim que a base fica melhor a cada rodada 😀

Até o próximo post!