From Notion to Obsidian: plain files, Git and AI agents

I used Notion for years. Work notes, side project ideas, trip plans, snippets I wanted to keep. It did the job, but at some point it stopped feeling like mine.

My notes lived on someone else’s server. Pages took a few seconds to open. The AI features were tied to Notion’s own plan and models. And as a developer, I kept wanting things I couldn’t have: grep my notes, version them, script them.

So I moved to Obsidian. The idea is simple: your notes are Markdown files in a folder on your disk. That’s it. No proprietary format, no lock in. The app is free if you skip their paid sync, and the plugin ecosystem is huge.

What really sold me is what that simple idea unlocks. Plain files can be versioned with Git. Plain files can be read by any AI tool, including coding agents. This post is about that setup.

First, turn on community plugins

Most of the good stuff comes from plugins, and they are disabled by default.

Open Settings (Cmd + , on macOS, Ctrl + , elsewhere).
Go to Community plugins and turn off Restricted mode.
Click Browse, find a plugin, install it, then Enable it.

Plugins are made by the community, so check the GitHub repo and the download count before installing anything.

Syncing the vault with Git

Obsidian has a paid sync service and it works fine. I went with Git instead: a private GitHub repo costs nothing, and I get the full history of every note. Broke something? Revert. Curious what I wrote last spring? git log.

Desktop

Turn the vault into a repo:

cd ~/path/to/vault
git init
git add .
git commit -m "Initial vault"
git branch -M main

Create an empty private repo on GitHub or GitLab (no README, no license, or the first push fails), then:

git remote add origin git@github.com:you/vault.git
git push -u origin main

Add a .gitignore so device specific files don’t fight each other between laptop and phone:

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
.DS_Store

Then install the Obsidian Git plugin. Two settings matter:

Auto commit and sync interval: I use 30 minutes. Frequent enough to never lose much, rare enough to keep a readable history.
Pull on startup: on. Essential as soon as you use more than one device.

From there, the vault commits and pushes itself.

Phone

Mobile Obsidian can’t use SSH, so switch the remote to HTTPS:

git remote set-url origin https://github.com/you/vault.git

On GitHub, create a fine grained personal access token limited to the vault repo, with read and write on contents. Copy it immediately, you won’t see it again.

Zip the whole vault, including the hidden .git and .obsidian folders, and send it to your phone (AirDrop or iCloud Drive on iOS, LocalSend or a cable on Android). Unzip it, then in Obsidian:

Open folder as vault and select the folder.
Trust the author and enable plugins. Settings come along since they live in .obsidian.
Run Obsidian Git: Pull from the command palette.
Enter your GitHub username and paste the token as the password.

Create a test note, run Commit all changes and push, and check it lands on your laptop.

A word of honesty: the plugin’s own docs call mobile support unstable. On phones it can’t run real Git, so it uses a JavaScript implementation that gets slow, and can even crash, on big vaults. What helps: keep heavy attachments out of the repo, and if a sync hangs, stage only the files you changed. For a light vault like mine, it’s good enough.

AI inside Obsidian: Copilot

The Copilot plugin adds a chat panel that can read your notes. It supports OpenAI, Anthropic, Google, OpenRouter and local models through Ollama. You set your key in Settings > Copilot, pick a default model, and you’re done.

What I use most:

@ to pull a note into the conversation: “summarize @meeting-notes and list the action items”.
Select text, right click, and rewrite, shorten or translate it in place. Useful since I write in English and French.
Vault QA mode to ask questions across the whole vault: “what did I decide about the server setup?”

One thing people don’t mention enough: Vault QA works by indexing your notes with an embedding model. If that model is in the cloud, your whole vault gets sent there. For private notes, point the embeddings to a local model in Ollama and nothing leaves your machine.

AI on the vault: agents

This is the part Notion could never give me.

Since my vault is just a folder of Markdown files in a Git repo, I can open it with a coding agent like Claude Code, the same way I open a Rails project. The agent can read every note, search across them, create new ones, reorganize folders and fix links. It’s not chatting about my notes anymore, it’s working on them.

A few things make this work well.

A CLAUDE.md at the root of the vault. Agents read this file first. I use it to explain how the vault is organized: which folder holds what, the frontmatter fields I use, how I name files, and what the agent should never touch. Think of it as the contract between you and the agent. The clearer it is, the less the agent guesses.

Git as a safety net. Letting an AI edit your notes sounds scary until you remember everything is versioned. I review the diff before committing, exactly like a pull request. If I don’t like a change, git restore and it’s gone. That’s really what makes me comfortable giving agents write access.

The official Obsidian CLI. Since version 1.12, Obsidian ships a command line tool (Settings > General > Command line interface). It lets agents use Obsidian’s own features instead of just reading raw files:

obsidian search query="server setup"
obsidian backlinks
obsidian daily:append content="- [ ] Renew domain"
obsidian tasks daily

Note that it drives the running app, so Obsidian has to be open. The big win is things like moving a note with obsidian move, which updates every link pointing to it, something a raw mv would break.

What I actually do with it: turn a messy brain dump into clean notes, link related notes I forgot about, add missing frontmatter across a folder, and build a weekly summary from my daily notes. Small chores that I would never do by hand.

Other plugins I kept

Bases: Obsidian’s built-in database views. Pick notes by folder or tag, show their properties as columns, sort and filter. It’s the closest thing to Notion databases, with no plugin or query language needed.
Dataview: for the few views that need more logic than Bases offers.
Kanban: boards stored as Markdown. I track my blog posts with one, versioned with Git like the rest.
Excalidraw: diagrams stored inside the vault. Perfect for architecture sketches.
LanguageTool: grammar and spelling in several languages.

Was it worth it?

Yes. My notes are plain files I own, backed up with full history, available on every device. And because they’re plain files, any AI tool can work with them: a chat panel when I want a quick answer, an agent when I want real work done, a local model when the content is private.

If you’re thinking about switching, try it with a small folder of notes for a week. Add Git on day one. You’ll see quickly why it sticks.