https://github.com/webdevtodayjason/obsidian-github-sync
Bidirectionally sync an Obsidian vault to a headless host (e.g. an AI-agent Pi) via Git + a private GitHub repo as source of truth.
https://github.com/webdevtodayjason/obsidian-github-sync
Last synced: 17 days ago
JSON representation
Bidirectionally sync an Obsidian vault to a headless host (e.g. an AI-agent Pi) via Git + a private GitHub repo as source of truth.
- Host: GitHub
- URL: https://github.com/webdevtodayjason/obsidian-github-sync
- Owner: webdevtodayjason
- License: mit
- Created: 2026-06-02T23:52:31.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-02T23:52:33.000Z (about 2 months ago)
- Last Synced: 2026-06-05T07:18:48.129Z (about 1 month ago)
- Language: Shell
- Size: 5.86 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# obsidian-github-sync
Bidirectionally sync an [Obsidian](https://obsidian.md) vault to a **headless host** — e.g. a Raspberry Pi running an AI agent — using **Git + a private GitHub repo as the source of truth**. The agent reads and writes the *live* vault; its edits flow back to GitHub and to your other machines.
No Obsidian GUI required on the headless host. No Obsidian Sync subscription required. You get full **version history** for free.
```
your Mac (Obsidian) headless host (AI agent, e.g. Pi)
┌───────────────────────────┐ ┌───────────────────────────────────┐
│ vault/ ──launchd 5min──┐ │ │ ┌──systemd 3min── vault/ (clone) │
│ (Obsidian + git) │ │ │ │ agent reads + writes here │
└─────────────────────────┼──┘ └──┼──────────────────────────────────┘
│ pull/push │ pull/push
▼ ▼
┌──────────────────────────────────┐
│ GitHub (PRIVATE repo) = truth │
│ full version history │
└──────────────────────────────────┘
```
## Why not Obsidian Sync or Syncthing?
- **Obsidian Sync** is great, but it's a paid cloud and the agent can't read those files headlessly.
- **Syncthing** is live P2P but has *no central source of truth and no history*.
- **Git/GitHub** gives you a canonical store, version history, free hosting, and plain files any agent can read/write. It also matches a normal dev workflow (repo updated → everyone syncs).
## Security
- The vault repo **must be PRIVATE** — it's your personal notes.
- Don't keep raw secrets in notes you push (a private repo still puts them on GitHub and on the agent host). Keep credentials in a manager (1Password, etc.) and reference them.
- Push auth uses the GitHub CLI (`gh auth setup-git`) — no tokens in scripts.
## Quickstart
**1. Create + seed a PRIVATE vault repo** (from your main machine, in your vault folder):
```bash
cd "/path/to/your/Obsidian Vault"
printf '%s\n' '.obsidian/workspace.json' '.obsidian/workspace-mobile.json' '.obsidian/cache/' '.trash/' '.DS_Store' > .gitignore
git init && git add -A && git commit -m "seed vault" && git branch -M main
gh repo create /obsidian-vault --private --source=. --remote=origin --push
```
**2. On the headless host** (Linux + systemd; enable linger so it runs without a login):
```bash
loginctl enable-linger "$USER"
./install-host.sh /obsidian-vault ~/Obsidian 3min ~/.hermes/.env
```
`~/.hermes/.env` is optional — pass your agent's env file and the installer wires `OBSIDIAN_VAULT_PATH` for you (Hermes/Evy reads that). For any other agent, just point it at the clone path.
**3. On your Mac** (launchd daemon — or skip this and use the in-app *Obsidian Git* plugin instead; use one, not both):
```bash
git clone https://github.com//obsidian-vault.git "$HOME/Obsidian" # if not already a clone
./install-peer-macos.sh "$HOME/Obsidian" 300
```
That's it. Each side runs `sync.sh` on an interval: `git pull --rebase --autostash`, then commit + push local changes.
## How it works
- `sync.sh` — the portable core. Pull-rebase, commit, push. A `mkdir`-based atomic lock (with a stale-lock guard) prevents concurrent runs from racing — works on macOS and Linux without `flock`.
- `install-host.sh` — clones the vault + installs a `systemd --user` service + timer.
- `install-peer-macos.sh` — installs a launchd agent.
- **Conflicts:** `--rebase --autostash` handles the common case; a true conflict is *logged, not auto-resolved* (so nothing is silently lost) — resolve it once in the repo and the daemons resume.
## Notes
- Commits from each side carry a label (`mac:` / `host:` / `evy:`) so history shows who edited where.
- Built to give an AI agent (Evy, on a [Hermes](https://hermes-agent.nousresearch.com) Pi) live, writable access to an Obsidian vault — but it works for any Obsidian + headless-host setup.
## License
MIT — see [LICENSE](LICENSE).