Stop losing context every time you come back to a project. This guide shows you how to set up a per-project Obsidian vault — committed alongside your code in Git — so GitHub Copilot always knows exactly what your project is, what decisions have been made, and what it should never touch.
▶️ Prefer video? Watch the full tutorial on YouTube →
I built this after wasting too much time watching AI agents lose context at the worst possible moments. This is my approach — a work in progress, and every developer will adapt it to their own style, but it should give you a solid starting point.
Most developers work like this: Notion open in one tab, the repo in another, and the AI has no clue what either of them contains.
You come back to a project after two weeks, and the first 20 minutes are wasted re-explaining the context — to yourself, and to Copilot. You type "look at my codebase and tell me what this does" and get a generic response because the AI has no history, no decisions, no current state.
One giant vault for everything makes it worse. You're searching through 500 notes to find the one that belongs to this client or this project. The context is diluted.
There's a better way: one vault, per project, committed to the same Git repo as the code.
Here's the structure you're going to build:
my-project/
├── src/ ← your code
├── .obsidian-vault/ ← your project brain
│ ├── .obsidian/ ← Obsidian settings (auto-created)
│ ├── decisions/ ← Architecture Decision Records
│ ├── specs/ ← Feature specs and API contracts
│ ├── bugs/ ← Issue investigations
│ ├── daily/ ← Quick standup notes
│ ├── retro/ ← Milestone reflections
│ ├── templates/ ← ADR, spec, bug templates
│ ├── 00-inbox.md ← Capture zone
│ ├── Dashboard.md ← Your project home screen
│ └── CLAUDE.md ← AI briefing file ← the most important file
├── .gitignore
└── project.code-workspace
Everything lives in one directory. Obsidian reads the vault. VS Code reads the code. Copilot reads both. Git versions all of it together.
Open your terminal and run:
mkdir my-project && cd my-project
mkdir .obsidian-vault && cd .obsidian-vault
mkdir -p decisions specs bugs daily retro templates
touch 00-inbox.md CLAUDE.md Dashboard.md
cd ..
The dot prefix on .obsidian-vault
keeps it visually separate from your source folders. It's still committed to Git — we just want it to sit apart from /src
.
This is the most important file in the entire system.
CLAUDE.md
is a plain-text briefing document. Every time Copilot (or Claude, or any AI agent) opens this project, it reads this file first. Write it like you're briefing a new developer joining the team.
Here's the structure:
## What this is
[One or two plain sentences. No jargon.]
## Tech stack
- Language: TypeScript
- Framework: Next.js 16
- Deployment: Vercel
- Database: Supabase (Postgres)
## Current state
[What's working. What's broken. What you're focused on right now.]
[Update this every time you return after a break. Takes 30 seconds. Saves 5 minutes.]
## Key decisions made
These are settled — not open for discussion:
- [Decision 1: e.g. "Server components for all data fetching — no client-side useEffect fetches"]
- [Decision 2: e.g. "Zod for all form validation, no exceptions"]
## File map
- `src/app/` — Next.js App Router pages
- `src/components/ui/` — shadcn/ui components, do not modify these manually
- `src/lib/db/` — all database queries live here
## DO NOT
- Do not suggest React Query — we use server components and Next.js cache
- Do not modify `src/components/ui/` without reading `decisions/001-design-system.md` first
- Do not add new environment variables without updating `.env.example`
The DO NOT section is what separates a good briefing from a great one. It prevents Copilot from helpfully "fixing" something you deliberately designed a certain way for a reason that isn't obvious from the code alone.
.obsidian-vault
folder (not the project root — the vault folder specifically)Obsidian initialises the vault and creates .obsidian/
inside it for settings and plugins.
Go to Settings → Community Plugins → Browse, then install and enable:
| Plugin | Why |
|---|---|
| Templater | |
| Dynamic templates with date variables — you'll use this for ADRs, specs, and bugs | |
| Dataview | |
| Database-style queries across notes — powers your project dashboard | |
| Obsidian Git | |
| Auto-commits notes with your code on a timer | |
| Linter | |
| Keeps frontmatter consistent across all notes |
At your project root (not the vault folder):
git init
Create your .gitignore
:
.obsidian-vault/.obsidian/workspace.json
.obsidian-vault/.obsidian/workspace-mobile.json
Everything else in the vault — plugin settings, themes, all your notes — gets committed. This is intentional.
Initial commit:
git add .
git commit -m "init: project with obsidian vault"
git remote add origin git@github.com:your-username/your-project.git
git push -u origin main
Now configure the Obsidian Git plugin:
Your notes now commit with your code. Every git log
shows both. When you look at a commit from six months ago, you'll also see the decision record that motivated it.
In Obsidian, go to Settings → Templater and set the templates folder to templates
.
templates/_template-adr.md
)
---
title: <% tp.file.title %>
date: <% tp.date.now("YYYY-MM-DD") %>
status: Proposed
---
## Context
[Why was this decision needed?]
## Decision
[What was chosen?]
## Consequences
[What changes as a result?]
templates/_template-spec.md
)
---
title: <% tp.file.title %>
date: <% tp.date.now("YYYY-MM-DD") %>
status: Draft
---
## Goal
[What are we trying to achieve?]
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
## Out of Scope
[What this spec deliberately does not cover]
templates/_template-bug.md
)
---
title: <% tp.file.title %>
date: <% tp.date.now("YYYY-MM-DD") %>
status: Open
---
## Steps to Reproduce
1.
## Expected Behaviour
## Actual Behaviour
## Root Cause
[Fill this in when found]
Create a workspace file at the project root (project.code-workspace
):
{
"folders": [
{ "path": "." }
],
"settings": {
"files.exclude": {
"**/.obsidian": true
}
}
}
Open this file with File → Open Workspace from File instead of opening the folder directly. This gives you a clean explorer view and ensures Copilot sees the entire workspace including the vault.
Enable Copilot Agent Mode:
Ctrl+Shift+I
(or Cmd+Shift+I
on Mac)Now test it. Type into Copilot:
Read .obsidian-vault/CLAUDE.md and give me a summary of the current project state.
Copilot reads your briefing file and responds with a summary. From this point on, every agent session starts with that context — no copy-paste, no re-explaining.
You can also tell Copilot to write back into the vault:
Summarise the change we just made and write an ADR to
.obsidian-vault/decisions/001-auth-strategy.md using the template
at .obsidian-vault/templates/_template-adr.md
Copilot reads the template, generates the ADR, writes the file. Next commit: decision record and code go together.
Create Dashboard.md
at the vault root with Dataview queries:
## 🐛 Open Bugs
``` dataview
TABLE status, file.mtime as "Last updated"
FROM "bugs"
WHERE status = "Open"
SORT file.mtime DESC
📋 Open Specs #
TABLE status
FROM "specs"
WHERE status != "Done"
🗺️ Recent Decisions #
TABLE file.mday as "Date"
FROM "decisions"
SORT file.mday DESC
LIMIT 5
Set Dashboard.md as your **default file** in Obsidian settings. Every time you open the vault, in 30 seconds you know exactly where you left off.
You haven't touched this project in two weeks.
`Dashboard.md`
`00-inbox.md`
— you left a note: `"Read CLAUDE.md and bugs/partial-fill-issue.md and help me investigate the root cause"`
`00-inbox.md`
`CLAUDE.md`
. Two sentences. What you fixed. What's next.Tomorrow, in two weeks, in six months — you're back in context within 60 seconds.
This is where the per-project vault model really shines.
In **Obsidian**: click the vault icon → select a different project vault. Each vault has its own plugins, its own dashboard, its own graph view. Zero bleed-through between projects.
In **VS Code**: close the current workspace, open the other project folder. Copilot's context resets automatically.
You're never reading notes from one project while working on another. Each project is an island — isolated, focused, self-contained.
The second part will cover GitHub Copilot instructions, agents, skills, prompts, and MCP files — so don't worry if this feels incomplete for now.
Once this is running, the natural progression is **Claude Code** — a terminal-based agent that reads the same `CLAUDE.md`
file and can run commands across the project. It's built for exactly this kind of project-scoped context.
📺 **Full video walkthrough (16 min):** [Obsidian + VS Code Copilot: AI Second Brain Per Project Setup →](https://youtu.be/fmYn6ODiISA)
🗂️ **Template files** (CLAUDE.md starter + ADR/Spec/Bug templates): drop a comment below or on the video and I'll link them
💬 **Questions?** Leave them in the comments below or on the YouTube video — what part of your dev workflow are you trying to fix? Best questions become future videos.