Sync Obsidian Vault with Git for AI Collaboration

Mar 23, 2026

I tried to let Claude Code read my Obsidian vault and it was a mess.

My vault lives in iCloud. Claude runs on a remote server. iCloud doesn’t work on Linux. I couldn’t just point Claude at my notes and say “read this project context.”

Then I made it worse. I tried syncing my entire vault to a VM with Syncthing. Now my personal journal, random thoughts, and sensitive notes were all sitting on a server somewhere. Not ideal.

Here’s what I learned: you need two vaults. One for you, one for your AI.

The Problem

I use Obsidian for everything. Project notes, daily journal, random ideas, meeting notes. It’s all in one place, synced via iCloud across my Mac and iPhone.

When I started using Claude Code for development, I wanted Claude to understand my project context. The obvious answer was: “just point Claude at my Obsidian vault.”

But that doesn’t work:

iCloud Vault
    |
    +-- Can't access from Linux servers
    +-- No git history of AI changes
    +-- AI sees EVERYTHING (including personal notes)
    +-- No rollback if AI messes up

I needed something different. Git-backed, accessible from anywhere, but without exposing my private thoughts.

The Solution: Dual-Vault Architecture

After some trial and error, I settled on this:

~/obsidian/
├── personal/              # iCloud synced - PRIVATE
│   ├── journal/
│   ├── personal/
│   └── random-thoughts/
│
└── ai-workspace/         # Git synced - AI ACCESSIBLE
    ├── projects/
    │   └── my-app/
    │       ├── soul.md       # Project purpose
    │       ├── heart.md      # Core decisions
    │       └── decisions.md  # Key choices made
    ├── daily/
    ├── templates/
    └── .git/

Two separate vaults. Different sync strategies. Different purposes.

Personal vault: Stays in iCloud. Contains everything private. Claude never touches it.

AI workspace: Lives in git. Contains project documentation, decisions, learning notes. Claude can read and write here.

This isn’t as crazy as it sounds. Obsidian handles multiple vaults natively. Switching between them is Cmd+P and select. And the benefits are worth it.

Setting It Up

Step 1: Create the AI Workspace

mkdir ~/obsidian-ai-workspace
cd ~/obsidian-ai-workspace
git init
git branch -M main
git remote add origin [email protected]:username/obsidian-ai-workspace.git

Create the structure:

mkdir -p projects daily templates
touch README.md .gitignore

Step 2: The .gitignore

Obsidian creates a lot of files you don’t want in git. Here’s my .gitignore:

# Obsidian workspace settings (user-specific)
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/graph.json
.obsidian/graph.cache

# Plugin cache and temp files
.obsidian/plugins/*/data.json
.obsidian/plugins/*/.hotreload

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Temporary files
*.tmp
*.temp
~$*

# Cache directories
.cache/
.trash/

# Obsidian Git plugin cache
.obsidian/plugins/obsidian-git/data.json

The key insight: .obsidian/workspace.json contains window state, open tabs, sidebar width. It changes constantly and causes merge conflicts. Ignore it.

Step 3: Install Obsidian Git Plugin

Open the new vault in Obsidian. Install the Obsidian Git plugin from community plugins.

Configure it:

{
  "vaultBackupInterval": 10,
  "commitMessage": "auto: vault backup",
  "autoPullInterval": 5,
  "autoPushInterval": 10,
  "pullBeforePush": true,
  "disablePush": false,
  "disablePopups": true
}

This auto-commits every 10 minutes. Your AI changes get backed up automatically.

Step 4: Create Project Context Files

For AI to understand your project, create context files:

# Project Soul

## Purpose
What this project exists to solve.

## Users
Who uses this and why.

## Success Metrics
How we measure if it's working.

# Project Heart

## Core Decisions
- Why we chose X over Y
- What constraints we're working within
- What we explicitly decided NOT to do

## Architecture Principles
- Principle 1
- Principle 2

These files give Claude context without needing to read your entire codebase every time.

Why This Works for AI Collaboration

The git-backed approach gives you three things cloud sync can’t:

1. Audit Trail

Every change Claude makes is in git history:

git log --oneline
# a1b2c3d docs: update API integration notes
# d4e5f6g Claude: refactor decision log
# g7h8i9j auto: vault backup

You can see exactly what changed and when. If Claude writes something weird, you know where to look.

2. Rollback Safety

AI sometimes makes bad decisions. With git:

# Claude deleted an important section
git checkout HEAD~1 -- projects/my-app/decisions.md

Done. No digging through iCloud versions or hoping Time Machine caught it.

3. Branch Experiments

Testing a new architecture? Let Claude draft in a branch:

git checkout -b ai-experiment/new-architecture
# Let Claude work on this branch
git add .
git commit -m "wip: Claude drafting new architecture notes"
git push origin ai-experiment/new-architecture

Review it. If it’s good, merge. If not, delete the branch. Your main notes stay clean.

VM Setup for Always-On AI

I run Claude on a VM that’s always connected. Here’s how I set it up:

# Clone the AI workspace
git clone [email protected]:username/obsidian-ai-workspace.git
cd obsidian-ai-workspace

# Now Claude can read/write here
claude --vault /path/to/obsidian-ai-workspace

I added a cron job for auto-sync:

crontab -e

*/5 * * * * cd /home/user/obsidian-ai-workspace && git pull && git add . && git commit -m "auto sync" && git push

Every 5 minutes, it pulls any changes I made locally, commits any changes Claude made, and pushes everything. Both my local machine and the VM stay in sync.

Handling Merge Conflicts

This is the part I was worried about. What if I edit a file on my laptop while Claude edits it on the VM?

It happens. Here’s how to deal with it:

# See what's conflicted
git status

You’ll see something like:

Unmerged paths:
  both modified: projects/my-app/decisions.md

Open the file and look for the markers:

Some content here.

<<<<<<< HEAD
My local changes
=======
Claude's changes
>>>>>>> origin/main

More content here.

Three options:

# Option 1: Keep your changes
git checkout --ours projects/my-app/decisions.md

# Option 2: Keep Claude's changes
git checkout --theirs projects/my-app/decisions.md

# Option 3: Edit manually, then:
git add projects/my-app/decisions.md
git commit -m "resolve: merge conflict in decisions.md"

I usually go with option 3. The conflicts aren’t that common, and when they happen, it’s worth looking at both versions.

What About Syncthing?

I mentioned I use Syncthing for my other devices. It works great for personal notes across my phone, tablet, and laptop. But for the AI workspace, git is better.

Syncthing doesn’t:

Track history
Let you branch
Show diffs
Work well on headless servers

Git does all of those. For AI collaboration, those matter more than real-time sync.

Common Mistakes I Made

Mistake 1: Using iCloud for the AI vault

iCloud and git don’t play nice. iCloud locks files during sync. Git tries to lock files during operations. They fight. Files get corrupted. Don’t do this.

Mistake 2: Not setting up .gitignore early

I initially committed everything. Then .obsidian/workspace.json changed every time I opened Obsidian. Git showed “modified” constantly. Clean git history became impossible.

Add the .gitignore first. Before your first commit.

Mistake 3: Mixing personal and AI notes in one vault

I thought: “I’ll just be careful about what I let Claude read.”

No. Claude will see everything. Your journal. Your draft emails. That note about how annoying your coworker is. Keep them separate.

Mistake 4: Forgetting to pull before Claude sessions

I’d make changes locally, then start a Claude session on the VM. Claude wouldn’t see my latest updates. We’d duplicate work.

Now I always pull first:

git pull origin main

What I Gained

Since setting this up:

Claude understands my project context without reading my personal journal
Every AI edit is tracked in git history
I can experiment with branches and merge when ready
My VM and laptop stay in sync automatically
I can rollback any bad AI suggestions

The setup took about 15 minutes. The payoff is ongoing.

How to Start

Create a new vault in Obsidian
Initialize git in that vault
Add the .gitignore
Install Obsidian Git plugin
Create your first project context files (soul.md, heart.md)
Push to a remote repository
Clone to your AI server/VM

That’s it. You now have an AI-accessible, version-controlled knowledge base that’s separate from your private notes.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!