Obsidian + VS Code Copilot: Build an AI Second Brain Per Project (Full Setup Guide)

A developer created a per-project Obsidian vault system committed alongside code in Git, enabling GitHub Copilot to maintain full project context across sessions. The setup includes a `.obsidian-vault` directory with structured folders for decisions, specs, bugs, and daily notes, plus a `CLAUDE.md` briefing file that tells the AI what the project is, what decisions have been made, and what it should never touch. The approach solves the common problem of AI agents losing context when developers return to projects after breaks, eliminating wasted time re-explaining project state to both themselves and their coding assistants.

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 → https://youtu.be/fmYn6ODiISA 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: Project Name 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 workspace state device-specific, don't commit .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: Project Dashboard 🐛 Open Bugs dataview TABLE status, file.mtime as "Last updated" FROM "bugs" WHERE status = "Open" SORT file.mtime DESC 📋 Open Specs dataview TABLE status FROM "specs" WHERE status = "Done" 🗺️ Recent Decisions dataview 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.