Sync Obsidian vaults with Git instead of iCloud for AI agent compatibility

Problem

Obsidian vaults need reliable sync across devices and AI agents. iCloud sync is the default choice, but it causes silent merge conflicts when multiple writers (you on your phone, Claude Code on your laptop, an automation script on a server) modify the vault concurrently. iCloud also provides no meaningful version history -- if a file gets corrupted or overwritten, there is no easy way to recover a previous version. When AI agents are constantly adding and editing notes, these problems compound quickly.

Solution

Use Git and GitHub as the sync backend for your Obsidian vault. AI agents auto-commit on every change. Merge conflicts are resolved with standard git diffs rather than silently dropped.

Initialize the vault as a git repo:

cd ~/obsidian-vault
git init
git remote add origin git@github.com:username/obsidian-vault.git

# Create .gitignore for Obsidian workspace files
cat > .gitignore << 'EOF'
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/cache
.trash/
EOF

git add -A && git commit -m "Initial vault commit"
git push -u origin main

Auto-commit script for AI agents (save as vault-sync.sh):

#!/bin/bash
VAULT_DIR="$HOME/obsidian-vault"
cd "$VAULT_DIR" || exit 1

# Pull latest changes, rebase local work on top
git pull --rebase --autostash origin main 2>/dev/null

# Check for changes
if [ -n "$(git status --porcelain)" ]; then
    git add -A
    CHANGED=$(git diff --cached --stat | tail -1)
    git commit -m "vault sync: $CHANGED"
    git push origin main
fi

Run on a schedule with cron:

# Run every 5 minutes
crontab -e
# Add: */5 * * * * /path/to/vault-sync.sh >> /tmp/vault-sync.log 2>&1

Configure Claude Code to commit after vault edits in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd ~/obsidian-vault && git add -A && git diff --cached --quiet || git commit -m 'ai: update notes'"
          }
        ]
      }
    ]
  }
}

Access from mobile without the Obsidian app:

Set up a Telegram or Discord bot that watches for messages from you, searches the vault repo via git grep, returns matching note contents, and accepts new notes as messages to commit to the repo. This avoids needing git sync working natively on iOS.

Why It Works

Git was designed for exactly this problem -- multiple writers modifying a shared set of text files with full history and conflict resolution. Every commit creates an immutable snapshot of the vault, so you can recover any previous version of any note. When merge conflicts occur (two writers edit the same paragraph), git surfaces them as explicit diffs rather than silently picking a winner like iCloud does. The commit history also serves as an activity log -- you can see exactly what your AI agents changed and when, which builds trust in automated vault management. The commit graph doubles as a motivation tool -- seeing daily green squares keeps you incentivized to maintain and garden the vault.

Context

• This pattern focuses on the sync mechanism; for vault structure and AI knowledge management, see pattern-obsidian-ai-knowledge-base
• Use --rebase --autostash on pull to avoid unnecessary merge commits from concurrent edits
• For mobile access, a bot reading from the GitHub repo is simpler than trying to get git sync working on iOS
• Alternative approach: use iCloud as primary sync with git as periodic backup/savepoints if you prefer the iCloud mobile experience
• GitHub private repos are free and have no storage limits for text files, making this effectively free infrastructure
• Consider .gitignore-ing large attachments (PDFs, images) if they bloat the repo -- or use Git LFS for binary files
• The AI auto-commit pattern means humans rarely need to commit manually; the version history builds itself