Claude Autopilot para Obsidian
SuzumiyaHaruhi719/claude-autopilot-for-obsidian
Vault Obsidian como fonte única de verdade, automaticamente sincronizado com seu código
Ver no GitHubSkill 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-obsidian1 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
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
- What was wrong with the old way
- How it works
- The dynamic workflow
- Install
- Configuration
- Security model
- Cross-platform notes
- Command reference
- Project layout
💡 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 setup | Fix in this rewrite |
|---|---|---|
| 1 | Windows-only. Six powershell.exe scripts with GBK-encoding workarounds. | One pure-Python toolkit; runs identically on all three OSes. |
| 2 | Hardcoded 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. |
| 4 | Process storm. 3–6 detached shells spawned on every prompt. | One dispatcher process per lifecycle event. |
| 5 | Brittle triggers. Hardcoded project names in a keyword regex. | Per-vault, configurable, bilingual keywords. |
| 6 | Copy-pasted plumbing. Lock/throttle logic reimplemented in each script. | A single locking + throttling primitive, reused everywhere. |
| 7 | No observability. Logs scattered, no way to check health. | pilot.py status and pilot.py doctor. |
| 8 | Single 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. initis 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=valuesecrets before anything is written. - A managed
.gitignoreblock 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. installbacks up yoursettings.jsonand never clobbers unrelated hooks.
🌍 Cross-platform notes
| Concern | How it's handled |
|---|---|
| Python launcher | install writes the absolute path of the active interpreter (python/python3/venv). |
| Paths | pathlib + ~/env expansion; forward or back slashes both work. |
| File encoding | All reads/writes are UTF-8, no BOM — Obsidian- and git-friendly. |
| Atomic writes | temp-file + os.replace, atomic on NTFS, APFS and ext4. |
| Claude config dir | Honors CLAUDE_CONFIG_DIR; defaults to ~/.claude. |
| Locks / throttles | OS-agnostic stamp files; stale locks auto-reclaimed. |
📟 Command reference
| Command | Purpose |
|---|---|
python pilot.py init | Scaffold <project>/obsidian, archive dir in ~/Documents, register the vault (run in a project root) |
python pilot.py install | Register the three lifecycle hooks |
python pilot.py uninstall | Remove this skill's hooks (others untouched) |
python pilot.py status | Show resolved config + recent sync log |
python pilot.py doctor | Check git, python, paths, remotes |
python pilot.py sync | Manually pull + push every vault now |
python pilot.py session-start | prompt | stop | Hook 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