DEV Community

Clemente Nogueira
Clemente Nogueira

Posted on • Originally published at youtu.be

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

#obsidian #vscode #githubcopilot #productivity

TL;DR

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 →

The Problem

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.

The Architecture

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
Enter fullscreen mode Exit fullscreen mode

Everything lives in one directory. Obsidian reads the vault. VS Code reads the code. Copilot reads both. Git versions all of it together.

Step 1 — Create the Folder Structure

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 ..
Enter fullscreen mode Exit fullscreen mode

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.

Step 2 — Write the CLAUDE.md Briefing File

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`
Enter fullscreen mode Exit fullscreen mode

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.

Step 3 — Open the Vault in Obsidian

  1. Launch Obsidian
  2. Click the vault icon in the bottom-left corner
  3. Click "Open folder as vault"
  4. Select your .obsidian-vault folder (not the project root — the vault folder specifically)
  5. Click Open

Obsidian initialises the vault and creates .obsidian/ inside it for settings and plugins.

Step 4 — Install the Four Essential 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

Step 5 — Wire Up Git

At your project root (not the vault folder):

git init
Enter fullscreen mode Exit fullscreen mode

Create your .gitignore:

# Obsidian workspace state (device-specific, don't commit)
.obsidian-vault/.obsidian/workspace.json
.obsidian-vault/.obsidian/workspace-mobile.json
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Now configure the Obsidian Git plugin:

  • Settings → Obsidian Git
  • Auto commit-and-sync interval: 10 minutes
  • Enable: auto commit after stopping file edits
  • Merge strategy: Merge

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.

Step 6 — Set Up Templates

In Obsidian, go to Settings → Templater and set the templates folder to templates.

Architecture Decision Record (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?]
Enter fullscreen mode Exit fullscreen mode

Feature Spec (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]
Enter fullscreen mode Exit fullscreen mode

Bug Investigation (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]
Enter fullscreen mode Exit fullscreen mode

Step 7 — Connect VS Code and Copilot Agent Mode

Create a workspace file at the project root (project.code-workspace):

{
  "folders": [
    { "path": "." }
  ],
  "settings": {
    "files.exclude": {
      "**/.obsidian": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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:

  1. Open Copilot chat: Ctrl+Shift+I (or Cmd+Shift+I on Mac)
  2. Click the mode selector at the top of the chat panel
  3. Switch from Ask to Agent

Now test it. Type into Copilot:

Read .obsidian-vault/CLAUDE.md and give me a summary of the current project state.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Copilot reads the template, generates the ADR, writes the file. Next commit: decision record and code go together.

Step 8 — Build Your Project Dashboard

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
```
Enter fullscreen mode Exit fullscreen mode

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.

What a Real Session Looks Like

You haven't touched this project in two weeks.

  1. Open Obsidian → switch to the project vault → open Dashboard.md
  2. Two open bugs. One spec in progress. Good.
  3. Check 00-inbox.md — you left a note: "look into partial fill edge case in risk manager"
  4. Open VS Code → Copilot agent mode on
  5. Type: "Read CLAUDE.md and bugs/partial-fill-issue.md and help me investigate the root cause"
  6. Copilot reads both files, understands the context, starts reasoning with you
  7. As you work, you drop quick notes into 00-inbox.md
  8. Root cause found → update the bug note, mark status: Fixed
  9. Before closing: update the Current State section of CLAUDE.md. Two sentences. What you fixed. What's next.
  10. Commit. Notes and code together.

Tomorrow, in two weeks, in six months — you're back in context within 60 seconds.

Switching Between Projects

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.

Key Takeaways

  • One vault per project — not one vault for your life
  • CLAUDE.md is the most important file — it's your AI briefing document, update it every session
  • The DO NOT section prevents AI from "helpfully" breaking things you designed on purpose
  • Same Git repo — code and notes are versioned together, always in sync
  • Copilot in agent mode can read and write your vault — it's not just reading your code anymore
  • Dashboard.md + Dataview — you're back in context within 60 seconds every time

What to expect

The second part will cover GitHub Copilot instructions, agents, skills, prompts, and MCP files — so don't worry if this feels incomplete for now.

Next Steps

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 →

🗂️ 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.

Top comments (0)