obsidian-project-sync

Sincronização de projetos do Obsidian

O cofre descreve a si mesmo. Onde os projetos estão, para onde vão os finalizados, onde o hook deixa seus logs e qual nota declara as convenções do cofre: tudo isso vem de .claude-vault.json na raiz do cofre, e scan o retorna. Esta skill não assume nomes de pastas.

Um cofre não é apenas projetos, e sua nota de convenções diz o que cada pasta contém. Tenha isso em mente ao oferecer onde colocar algo novo: uma decisão ou fato que afeta vários projetos não vai na nota de um único projeto.

Mapa local primeiro

Procure pelo mapa local desta skill antes de qualquer outra coisa: uma seção chamada obsidian-project-sync local map nas instruções permanentes do usuário (seus arquivos CLAUDE.md no Claude Code, lidos do disco em vez da cópia no contexto, que pode anteceder uma edição; instruções do Projeto ou preferências do usuário no claude.ai). Uma seção chamada Local map for this install dentro deste SKILL.md, adicionada quando a skill foi empacotada para uma conta claude.ai, também conta; instruções permanentes que digam o contrário vencem. Ela contém o que apenas aquela configuração sabe: o caminho do cofre, as convenções próprias do usuário sobre as do cofre (notas complementares que todo projeto carrega, estilos de callout), outros arquivos que apontam para o cofre e devem mudar com ele. Siga-a onde ela falar; ela substitui os padrões aqui.

O script e o cofre

O script é scripts/vault.py, ao lado deste SKILL.md: construa seu caminho a partir da própria pasta da skill (o Claude Code informa o diretório base quando a skill carrega). Todo exemplo abaixo o escreve como vault.py. Ele precisa de Python 3.8 ou superior; se python não for encontrado, tente python3, depois py.

O caminho do cofre vem, nesta ordem, do mapa local, da variável de ambiente OBSIDIAN_VAULT ou perguntando ao usuário. Passe-o com --vault, antes ou depois do subcomando. O script não tem padrão embutido de propósito: sem um cofre ele para e avisa.

Sempre primeiro: olhe antes de escrever

python vault.py scan --vault "<cofre>"

Sem --project ele retorna o inventário do cofre: quais projetos existem, em qual zona e com qual status. statuses_in_use lista os valores que o usuário já usa; escolha um deles e não invente rótulos.

Depois o projeto em si:

python vault.py scan --vault "<cofre>" --project "<nome da pasta>"

Ele retorna a pasta, a nota principal, seu frontmatter, a lista exata de seus cabeçalhos, os outros arquivos na pasta, o log de sessão (e qual arquivo de log leu, em session_log_file), e sessions_since_note_changed: as sessões registradas mais novas que a última modificação da nota no disco. Essa última lista é onde "o que ainda não está na nota" começa, não prova disso: verifique na nota antes de afirmar que algo está faltando.

--project aceita o nome da pasta do projeto no cofre, combinado sem caixa ou acentos. Ao trabalhar a partir de um repositório de código, a pasta geralmente tem o nome do repositório; se não, execute scan sem --project e combine pelo frontmatter da nota principal (uma chave path ou url, se o cofre usar uma), e pergunte quando nada combinar.

Um projeto na zona de arquivo está finalizado. Não o recrie entre os ativos nem o atualize sem perguntar.

Segundo: leia as convenções do cofre

scan retorna um bloco config:

"config": {
  "source": ".claude-vault.json",
  "projects": "Projects",
  "archive": "Archive",
  "logs": "Toolbox/Claude Sync",
  "conventions": "/caminho/para/cofre/Meta/Conventions.md"
}

conventions é a nota que manda. Leia-a antes de escrever em qualquer outra: ela declara o esquema de frontmatter, como as notas são escritas naquele cofre, o que pode mudar sem perguntar e o que não pode. Esta skill deliberadamente não carrega cópia disso: uma cópia envelhece, e uma versão anterior desta skill acabou apontando para uma pasta que já não existia.

Se conventions for null, o cofre não declara nenhuma. Pergunte antes de escrever em qualquer nota.

O mesmo bloco diz de onde vieram as pastas. Se source for defaults, o cofre não se descreveu e você está trabalhando com suposições: diga isso e ofereça escrever .claude-vault.json (formato em references/mechanics.md). Se um warning aparecer, a configuração está quebrada e precisa ser corrigida antes de continuar.

Cada pasta de projeto é diferente: algumas têm apenas a nota e um canvas, outras carregam notas soltas. Confie em scan, nunca no que estava lá da última vez.

Escrevendo em uma nota

As notas são escritas à mão. Não há modelo nem marcadores ocultos, e nenhum é adicionado. O corpo de uma seção específica é substituído:

python vault.py section --vault "<cofre>" --note "<caminho>" --heading "Deploy" --content "<arquivo>" --dry-run

O cabeçalho é combinado sem emoji e por correspondência parcial, então Deploy encontra ## 🚀 Deploy. Se não houver correspondência, o script lista os cabeçalhos que existem em vez de inventar um.

--content é um arquivo contendo o novo markdown. Escreva-o em uma pasta temporária (a área de rascunho da sessão ou a pasta temporária do sistema), nunca dentro do cofre ou de um repositório de código, e delete-o depois.

Regras que realmente importam:

• --dry-run primeiro, sempre, e o sim do usuário antes da escrita real. Mostre ao usuário o diff do dry-run, diga se cada mudança é factual ou prosa, e espere. Execute o mesmo comando sem --dry-run somente depois que ele concordar; um sim cobre os diffs que ele viu, nada mais.
• --content carrega a seção inteira, não apenas o que muda. replace troca todo o corpo sob aquele cabeçalho. Envie apenas uma tabela e a prosa abaixo dela desaparece. Leia a seção atual, trabalhe a mudança nela e envie o resultado completo.
• A última seção da nota está protegida. Os links de rodapé geralmente ficam abaixo dela, não pertencem a nenhuma seção e seriam perdidos. O script para com código de saída 2 e avisa. Use --mode append para adicionar sem deletar, que quase sempre é o certo para um log contínuo como Mudanças recentes.
• append respeita callouts. Quando uma seção é um callout cercado (```ad-note, do plugin Admonition), o novo texto vai dentro do cercado, antes de sua linha de fechamento; quando é um callout nativo (> [!note]), as novas linhas são citadas para que fiquem dentro dele. O rodapé permanece último de qualquer forma.
• Imite o que está lá. Idioma, voz, prosa ou marcadores, tamanho: a nota de convenções do cofre declara, e a nota que você está prestes a tocar confirma. Leia-a antes de rascunhar.
• Verifique antes de afirmar. Uma contagem, versão ou status escrito em uma nota deve vir de algo que você leu ou executou nesta sessão. Se não puder ser verificado agora, omita ou diga que não está verificado.

Adicionar uma nova seção requer dizer onde ela vai: --heading "Testing" --after "Gotchas". Pergunte primeiro: uma nova seção muda a estrutura de um documento que o usuário escreveu.

O que você pode mudar sem perguntar

O cofre declara, em sua nota de convenções: a parte que diz o que é factual e verificável (e portanto corrigido sem perguntar) e o que é prosa, que não é tocada sem permissão.

Até que você a leia, trate tudo como prosa e pergunte.

Quando uma informação nova não se encaixa em nenhuma seção existente, ofereça ambas as saídas e deixe o usuário escolher: estender uma seção ou uma nota separada vinculada à principal. Não decida por si mesmo.

Frontmatter

O esquema pertence a cada cofre e sua nota de convenções o declara. scan retorna o frontmatter real de cada nota, que é a outra maneira de vê-lo.

python vault.py frontmatter --vault "<cofre>" --note "<caminho>" --set updated=2026-09-13 --dry-run

Apenas chaves escalares. O script recusa listas em bloco de propósito: mudar os tópicos de uma nota é decisão do autor. section --touch-updated já define a data, então isso raramente é necessário sozinho.

Um campo pertencente a um plugin (um adesivo, um ícone) nunca é tocado.

Canvas

Arquivos .canvas são JSON com nodes e edges (JSON Canvas 1.0). O layout foi feito à mão, com grupos e conexões deliberados.

python vault.py canvas --vault "<cofre>" --file "<caminho>.canvas" --report

Ele fornece nós, arestas, nomes de grupos, quais notas estão vinculadas e se alguma aponta para um arquivo que não existe mais.

E state_outside_its_group, o campo que realmente precisa de atenção. Um canvas que agrupa notas por seu state armazena esse fato duas vezes: no frontmatter e na posição e cor do nó. Mude o state, deixe o cartão onde estava, e o canvas não quebra; ele ainda aponta para um arquivo que existe e ainda mostra a cor antiga. Começa a mentir sem nada para avisar ninguém.

Portanto, sempre que você mudar um state, verifique se aquele projeto ou pasta tem um canvas que agrupa por estado e execute o relatório. O inverso também vale: após criar uma nota, verifique se ela tem um cartão. Uma nota que não está no quadro não existe para quem lê o quadro.

Corrigir significa mover o nó e recolorir, o que é edição manual: o script relata, não reorganiza. Diga isso e proponha a mudança.

python vault.py canvas --file "<caminho>.canvas" --add-file "Caminho/Relativo/Nota.md" --color 6 --dry-run

Novos nós pousam em uma lacuna abaixo de tudo que existe: nada já existente se move. Colocá-los dentro de um grupo é trabalho manual do usuário, e com razão. Execute novamente sem --dry-run assim que o usuário concordar.

Se o relatório mostrar links quebrados, diga e pare. Não delete nós.

O log de sessão

Um hook SessionEnd registra os dados brutos de cada sessão do Claude Code na pasta de logs que o cofre declara (config.logs), um JSON por repositório: data, branch, novos commits desde a última vez, arquivos tocados e se algo ficou não commitado. Ele não escreve em nenhuma nota.

Essa é a matéria-prima. Quando o usuário pedir uma atualização, scan --project já a traz lida, em session_log e sessions_since_note_changed. Verifique esses commits contra o que a nota diz e proponha quais seções ficaram desatualizadas.

Se o hook ainda não estiver instalado, leia references/hook-install.md.

Notas de uma conversa claude.ai

Projetos do claude.ai não estão no disco, então não há script lá. Escreva o markdown completo em um bloco de código, com frontmatter que siga o esquema do cofre do usuário (pergunte por ele, ou por uma nota existente para copiar, se você não souber), e diga onde salvar. Se o projeto já tiver uma nota, diga em qual seção colar em vez de criar um arquivo solto.

Quando algo falha

• python não é reconhecido: tente python3, depois py. Se nenhum funcionar, não há Python; diga isso e ofereça fazer a edição manualmente com as ferramentas de arquivo, que é mais lento e arriscado.
• "Nenhum cofre fornecido": o mapa local não tem caminho de cofre e OBSIDIAN_VAULT não está definido. Pergunte ao usuário pelo caminho e ofereça adicioná-lo ao mapa local.
• O script para com código de saída 2: é a proteção da última seção funcionando. Mude para --mode append.
• O diff mostra mais deletado do que o esperado: não escreva. Quase sempre --content estava incompleto.
• A pasta do projeto não existe: pergunte. Não crie novas pastas na zona de projetos por conta própria.

Referências

• references/hook-install.md: instalando o hook de registro de sessão, no Windows, macOS e Linux.
• references/mechanics.md: como o script funciona e o que ele garante: o arquivo de configuração, como um cabeçalho é encontrado, as proteções, o formato do log.

As convenções de escrita não estão aqui. Elas vivem no cofre, na nota que scan retorna em config.conventions.