convez.ai
SkillAutomaçãoIntermediário
SuzumiyaHaruhi719

Claude Autopilot para Obsidian

SuzumiyaHaruhi719/claude-autopilot-for-obsidian

Vault Obsidian como fonte única de verdade, automaticamente sincronizado com seu código

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill Python que mantém seu vault Obsidian como fonte única de verdade para o código, integrando leitura inteligente de notas, escrita estruturada durante mudanças e sincronização automática via git. Funciona nativamente em macOS, Linux e Windows sem dependências externas.

Instalação

$npx convez-ai SuzumiyaHaruhi719/claude-autopilot-for-obsidian

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter documentação sempre sincronizada com mudanças de código
  • Arquivar e indexar automaticamente sessões de trabalho com Claude
  • Criar grafo de conhecimento conectado enquanto desenvolve
  • Gerenciar projetos multi-plataforma com segurança (redação de secrets)

Veredito

Ferramenta madura que resolve um problema real: documentação que apodrece quando código e notas divergem. A segurança out-of-the-box (sem vazar secrets) e suporte cross-platform genuíno (não apenas PowerShell) a distinguem de versões caseiras. Ideal para quem trabalha com Obsidian e quer que Claude seja um colaborador com memória organizada.

README

A tradução para o português deste README ainda está na fila.

Claude reads the right notes before it changes code, writes structured notes as it changes code, archives every conversation, cross-links related sessions, and git-syncs the vault. One pure-Python toolkit. macOS · Linux · Windows.


Table of contents


💡 Why this exists

If you keep an Obsidian vault that documents a project, the documentation rots the moment code and notes drift apart. The cure is a discipline — change the note in the same breath as the code — plus plumbing that handles the mechanical parts (syncing, archiving, indexing) so you never think about them.

Claude Autopilot for Obsidian is that discipline encoded as a Claude skill plus that plumbing encoded as three lifecycle hooks — two lanes that both keep the vault true:


🔍 What was wrong with the old way

This skill is a ground-up rewrite of a working-but-brittle setup. The redesign fixed concrete problems — worth listing, because they are the problems any home-grown version hits:

#Problem in the old setupFix in this rewrite
1Windows-only. Six powershell.exe scripts with GBK-encoding workarounds.One pure-Python toolkit; runs identically on all three OSes.
2Hardcoded paths. A user's absolute path baked into every script.Everything lives in one config file; nothing is hardcoded.
3🔴 Security leak. Full transcripts (tool results with API keys, file contents) auto-pushed to GitHub via git add -A.Archives stay local by default, are secret-redacted, and pushing is opt-in. Staging is scoped, never add -A.
4Process storm. 3–6 detached shells spawned on every prompt.One dispatcher process per lifecycle event.
5Brittle triggers. Hardcoded project names in a keyword regex.Per-vault, configurable, bilingual keywords.
6Copy-pasted plumbing. Lock/throttle logic reimplemented in each script.A single locking + throttling primitive, reused everywhere.
7No observability. Logs scattered, no way to check health.pilot.py status and pilot.py doctor.
8Single vault assumed.Config holds an array of vaults.

🛠️ How it works

Two layers, one vault.

Automatic layer — three hooks registered in ~/.claude/settings.json, each calling one dispatcher (pilot.py <event>):

Semantic layer — SKILL.md. Claude loads it whenever your work touches a configured vault, and follows the read-before / write-with / commit-trailer rules. This is the part that keeps the content honest; the hooks only keep the mechanics honest.


🔄 The dynamic workflow

What actually happens across one unit of work:

The one rule: a vault note and the code it documents change together, in the same unit of work — never "edit now, fix the note later." If the note lags the code, the knowledge chain is broken.


📦 Install

Requirements: Python 3.8+ and git. No pip packages — pure standard library.

# 1. Clone anywhere
git clone https://github.com/SuzumiyaHaruhi719/claude-autopilot-for-obsidian.git
cd /path/to/claude-autopilot-for-obsidian

# 2. Register the lifecycle hooks in Claude Code (once per machine)
python /path/to/claude-autopilot-for-obsidian/pilot.py install

# 3. In EACH project you want documented, run init from the project root:
cd ~/code/my-project
python /path/to/claude-autopilot-for-obsidian/pilot.py init

# 4. Verify
python /path/to/claude-autopilot-for-obsidian/pilot.py doctor

What init does

Run it from a project root and it scaffolds everything for you:

  • The vault lives next to your code at <project>/obsidian — versioned with the project, no separate repo to manage.
  • Conversation archives default to ~/Documents, deliberately outside the project so transcripts never pollute (or leak into) your code repo.
  • init is additive and idempotent — run it in each new project; existing files are never overwritten.

Auto-document an existing codebase: /obsidian-init

pilot.py init lays down an empty skeleton. To fill it from your actual code, use the bundled slash command — type it in the Claude Code CLI:

/obsidian-init

Claude then reads through the whole codebase and writes a richly cross-linked vault: one note per feature and per module, each citing the real file:line entry point, every dependency wired up with [[wiki-links]], plus data-flow, architecture, risk-map and glossary notes — so the vault's graph mirrors how the project is actually built.

Install the command once by copying it where Claude Code looks for commands:

# user-wide
cp commands/obsidian-init.md ~/.claude/commands/
# or per-project
mkdir -p .claude/commands && cp commands/obsidian-init.md .claude/commands/

To make Claude follow the semantic workflow too, expose the skill — either symlink/copy the repo into ~/.claude/skills/claude-autopilot-for-obsidian/, or install it as a plugin. Claude will then load SKILL.md automatically when your work touches a configured vault.

Uninstall cleanly at any time:

python pilot.py uninstall   # removes only this skill's hooks; backs up settings.json

⚙️ Configuration

One file: ~/.claude/obsidian-pilot.config.json (or set OBSIDIAN_PILOT_CONFIG).

{
  "vaults": [
    {
      "name": "MyProject",
      "path": "~/Documents/Obsidian/MyProject/Knowledge", // notes Claude reads/writes
      "git_root": "~/Documents/Obsidian/MyProject",       // where git runs
      "auto_pull": true,
      "auto_push": false,                                  // opt-in; off by default
      "pull_keywords": ["obsidian", "vault", "笔记", "MyProject"],
      "push_paths": []                                     // [] = whole repo minus ignores
    }
  ],
  "archive": {
    "enabled": true,
    "dir": "~/Documents/Obsidian/MyProject/Agent History",
    "push": false,            // archives stay LOCAL unless you flip this
    "include_thinking": true,
    "redact_secrets": true
  },
  "organize":      { "enabled": true, "throttle_seconds": 1800 },
  "link_sessions": { "enabled": true },
  "pull_throttle_seconds": 30
}

~ and environment variables are expanded. Forward slashes work on Windows too.


🔒 Security model

  • Archives never leave your machine unless you set archive.push: true.
  • Secret redaction masks AWS keys, GitHub/Slack/OpenAI tokens, bearer tokens, private-key blocks and key=value secrets before anything is written.
  • A managed .gitignore block keeps *.raw.jsonl, the Agent-History folder, and credential files out of every push — automatically.
  • No git add -A. Staging is scoped to configured content paths.
  • install backs up your settings.json and never clobbers unrelated hooks.

🌍 Cross-platform notes

ConcernHow it's handled
Python launcherinstall writes the absolute path of the active interpreter (python/python3/venv).
Pathspathlib + ~/env expansion; forward or back slashes both work.
File encodingAll reads/writes are UTF-8, no BOM — Obsidian- and git-friendly.
Atomic writestemp-file + os.replace, atomic on NTFS, APFS and ext4.
Claude config dirHonors CLAUDE_CONFIG_DIR; defaults to ~/.claude.
Locks / throttlesOS-agnostic stamp files; stale locks auto-reclaimed.

📟 Command reference

CommandPurpose
python pilot.py initScaffold <project>/obsidian, archive dir in ~/Documents, register the vault (run in a project root)
python pilot.py installRegister the three lifecycle hooks
python pilot.py uninstallRemove this skill's hooks (others untouched)
python pilot.py statusShow resolved config + recent sync log
python pilot.py doctorCheck git, python, paths, remotes
python pilot.py syncManually pull + push every vault now
python pilot.py session-start | prompt | stopHook entry points (read JSON on stdin)

🗂️ Project layout

claude-autopilot-for-obsidian/
├── pilot.py                  # single entry point: hooks + CLI
├── SKILL.md                  # the semantic workflow Claude follows
├── config.example.json       # config template
├── README.md
├── commands/
│   └── obsidian-init.md      # /obsidian-init slash command (auto-document a codebase)
├── docs/
│   ├── make_hero.py          # renders the animated hero banner (hero.gif)
│   ├── make_demo.py          # renders the knowledge-graph demo (demo.gif)
│   └── flowgif.py            # renders the six animated flow diagrams
└── obsidian_pilot/           # pure-stdlib package
    ├── util.py               # paths, logging, locking, atomic writes
    ├── config.py             # discovery, schema, defaults
    ├── gitsync.py            # throttled pull/push + managed .gitignore
    ├── archive.py            # transcript -> Markdown + secret redaction
    ├── organize.py           # rebuild Agent-History index
    ├── linker.py             # cross-link related sessions
    ├── scaffold.py           # init: create the vault skeleton
    └── installer.py          # register/remove hooks in settings.json

License

MIT © 2026 SuzumiyaHaruhi719

🤖 Generated with Claude Code

Ver o original no GitHub

Bom para

Relacionados