The Obsidian Setup Guide: From Installation to a Living Knowledge Vault

Obsidian is a knowledge environment built around markdown. It treats any folder on your computer as a “vault,” reads every markdown file inside it, and renders them into properly typeset documents with clickable internal links, full-text search, and a visual graph of how everything connects.

On its own, that already makes it the best second brain available. Paired with Claude Code, it becomes something different. A two-pane workspace where the AI writes files and the knowledge environment renders them instantly, with no copy, no paste, no sync, no friction. Same folder underneath. Two windows pointing at it.

This guide takes you from a fresh install to a working vault configured to pair with Claude Code. You will install Obsidian, understand the vault model, set up the two-window workflow, learn the three features that make Obsidian different from every other note-taking app, configure the small set of plugins that actually matter, and put the whole system on your phone.

If you have not yet set up Claude Code, read the companion Claude Code Setup Guide first. The two guides are designed to be used together. The Claude Code guide configures the AI that writes into the folder. This guide configures the environment that reads and explores it.

No technical experience required. If you can install an app and open a folder, you can do this.

Part 1: Install Obsidian

System Requirements

Obsidian runs on every modern desktop and mobile platform:

macOS: 10.15 (Catalina) or later. Native on Apple Silicon and Intel.
Windows: Windows 10 or later (64-bit).
Linux: AppImage, Snap, Flatpak, or .deb package. Ubuntu 18.04+ recommended.
iOS: 14.0 or later. iPhone and iPad.
Android: 7.0 or later.

You also need:

4 GB of RAM (minimum; 8 GB is more comfortable once your vault grows).
No internet connection required to use the desktop app. Sync, plugin downloads, and version updates need one; everything else works fully offline.
No account required. You can use Obsidian for years without ever creating one. Files live on your disk. Privacy is the default, not a setting.

Pricing

Obsidian is free for personal use, including both mobile apps, the full plugin ecosystem, and every core feature. Paid options exist only for specific needs:

Plan	Price	What You Get
Personal	Free	Full desktop and mobile apps, all core features, all community plugins and themes.
Commercial license	$50/user/year	Required if you use Obsidian for work at a company with two or more people on the payroll.
Obsidian Sync (Standard)	$4/month (annual)	End-to-end encrypted sync across devices, one vault, generous file size limits.
Obsidian Sync (Plus)	$8/month (annual)	Multiple vaults, larger files, one year of version history.
Obsidian Publish	$8/month per site	Publish a vault as a public website with backlinks and graph view.
Catalyst	$25 / $50 / $100 one-time	Insider builds, early access, custom badge. One-time purchase, no subscription.

Start with the free personal tier. If you want the same vault on your phone, the simplest path is iCloud Drive (free, all-Apple stack) or Obsidian Sync ($4/month) for cross-platform encrypted sync. We will cover both in Part 8.

Install

Download from obsidian.md. Run the installer for your platform.

On macOS, drag Obsidian to Applications. On Windows, the installer is a standard wizard. On Linux, choose the package format that matches your distribution.

For mobile, install “Obsidian” from the App Store or Google Play. Same vault, smaller screen.

First Launch

When you open Obsidian for the first time, you see a welcome screen with three options:

Create new vault - start a brand new folder Obsidian manages from scratch
Open folder as vault - point Obsidian at an existing folder you already have on disk
Open from previous vault - reopen a vault you have used before

The second option is the one that matters for this setup. The entire pairing with Claude Code rests on both tools working inside the same folder. We will set that up in Part 2.

Tip: Skip the default “Vault” location Obsidian suggests on first run. Pick the same folder you opened Claude Code in. That is the entire trick.

Part 2: Vaults and the Pairing with Claude Code

What a Vault Actually Is

A vault is a folder on your disk. That is it. There is no special file format, no proprietary database, no cloud bucket. Obsidian reads the contents of the folder, indexes every markdown file inside it, and renders them.

If you move the folder to another machine, the vault moves with it. If you delete Obsidian tomorrow, every file is still readable in any text editor. The vault is your folder. Obsidian is a window into it.

This is the architectural decision that makes the pairing with Claude Code work. Claude Code is also folder-anchored. When you type claude inside a folder, the AI is anchored to that folder. Every file Claude reads, writes, or edits lives there. If you have not set Claude Code up yet, the Claude Code Setup Guide covers that side of the workflow.

Point Obsidian at the same folder, and you have one workspace with two views.

Setting Up the Shared Folder

If you have already used Claude Code, you have a project folder. Use that one.

If you are starting fresh, pick a name and create the folder anywhere on your disk. Common choices:

~/Documents/Knowledge for a general second brain
~/Documents/Business for company-related work
~/AI/[project-name] for a specific project
~/[anything-you-like] if you want it at the top level

The folder name does not matter. What matters is that both tools point at the same one.

Opening the Vault

In Obsidian, click “Open folder as vault” on the welcome screen, or use the vault switcher icon in the lower-left corner of an existing window. Navigate to the folder you chose. Click Open.

Obsidian indexes everything inside. If the folder already contains markdown files, you will see them in the left sidebar within seconds. If the folder is empty, you will see an empty file tree, ready for the first file Claude Code (or you) write into it.

That is the entire setup. Obsidian is now a live window into the folder Claude Code is working in.

How the Two Tools Stay in Sync

Neither tool syncs anything. The folder is the sync.

When Claude Code creates a new file, the file appears in the folder. Obsidian’s file watcher sees it within milliseconds and shows it in the sidebar. When you click it, Obsidian renders it.

When Claude Code edits an existing file, Obsidian re-renders the open document in real time. No save button. No refresh. The pane is live.

This is why the pairing works as one workspace rather than two tools. Nothing is being passed between them. They are both looking at the same disk location through different lenses.

Tip: If you ever want to confirm what Obsidian is actually watching, hover over the vault name in the lower-left corner of the window. The full file path appears. It should match the folder you ran claude in.

Part 3: The Interface

Obsidian’s interface is built around four regions. Spend a few minutes orienting yourself before installing anything else.

The left sidebar holds your file explorer, search, bookmarks, and core tool icons. You can collapse it entirely with Cmd+\ (macOS) or Ctrl+\ (Windows / Linux).

Within the sidebar, the file explorer mirrors the folder structure of your vault exactly. Folders inside the vault appear as folders here. Subfolders nest. Files sort alphabetically by default, but you can reorder, group, and pin them.

Main Editing Pane

The center is where files render. You can have one file open or many, side-by-side or in tabs.

By default, files open in Live Preview mode, which renders markdown formatting as you type. Headings appear styled, bold text appears bold, tables render as tables, while the underlying syntax stays editable. If you prefer the old-school split between raw source and rendered output, switch a file to Source Mode via the toggle in the top-right of the pane.

The right sidebar holds contextual panels: backlinks (every file that links to the one you have open), outgoing links (every file the current one points at), file properties (frontmatter rendered as a form), the outline (an automatically generated table of contents), and the graph view of just the current note’s connections.

This panel is where you experience Obsidian’s “second brain” feel. Open a note, and the right sidebar shows you every thread that touches it.

Command Palette

Cmd+P (macOS) or Ctrl+P (Windows / Linux) opens the command palette. Every Obsidian action, including every plugin command and every keyboard shortcut, is accessible from this menu.

This is the single most useful keystroke in the entire app. Learn it before anything else. If you forget how to do something, type its name into the palette and execute it from there.

Panes and Tabs

You can split the editing pane horizontally or vertically (right-click the tab to see options), drag tabs around, and stack panes side-by-side. A common Claude Code + Obsidian workflow:

One pane open on the document Claude Code is actively writing into
A second pane open on the related research note or knowledge map
The right sidebar showing backlinks for cross-reference

You do not need this complexity on day one. But know it is there for when your vault grows.

Key Shortcuts

Shortcut	What It Does
`Cmd+P` / `Ctrl+P`	Open command palette (the master switchboard)
`Cmd+O` / `Ctrl+O`	Quick switcher - jump to any file by typing its name
`Cmd+\` / `Ctrl+\`	Toggle left sidebar
`Cmd+F` / `Ctrl+F`	Search in current file
`Cmd+Shift+F` / `Ctrl+Shift+F`	Search across the whole vault
`Cmd+G` / `Ctrl+G`	Open graph view
`Cmd+N` / `Ctrl+N`	Create a new note
`Cmd+T` / `Ctrl+T`	New tab
`Cmd+W` / `Ctrl+W`	Close current tab
`Cmd+E` / `Ctrl+E`	Toggle between Live Preview and Source mode

Part 4: Markdown and Links - The Format Both Tools Speak

Markdown is the shared language. Claude Code writes in it. Obsidian renders it. Knowing the basics is what lets you read Claude Code’s output fluently and write into the vault yourself when needed.

The Markdown Essentials

# Heading 1
## Heading 2
### Heading 3

**bold text**
*italic text*

- Bulleted list
- Another item
  - Nested item

1. Numbered list
2. Second item

| Column A | Column B |
|----------|----------|
| Row 1    | Value    |
| Row 2    | Value    |

`inline code`

> A quoted line

[Link text](https://example.com)
![Image alt text](path/to/image.png)

That is roughly 90% of what Claude Code will produce. Obsidian renders all of it with proper typography.

Internal Links - The Glue of the Vault

Obsidian extends standard markdown with one critical feature: wikilinks.

[[Some Other Note]]

Type two square brackets and Obsidian gives you an autocomplete dropdown of every note in your vault. Pick one, and the link is now active. Click it, and you jump to that note. The target note now shows the linking note in its backlinks panel.

This is how a vault becomes a graph rather than a folder. Every wikilink is a connection. Every connection compounds.

You can also link to a specific heading or paragraph inside another note:

[[Some Other Note#A Heading]]
[[Some Other Note#^paragraph-id]]

When Claude Code writes notes that reference other notes, ask it to use wikilink syntax. The vault becomes navigable on day one rather than after you manually link things together later.

Frontmatter (Properties)

The top of any markdown file can hold structured metadata in a YAML block:

---
title: Project Briefing
tags: [research, draft]
created: 2026-05-15
status: in-progress
---

Obsidian renders this block as a clean form at the top of the document (the “Properties” panel). You can edit fields directly there, query them through plugins like Dataview, and use them as filters across the vault.

This matters more than it sounds. When Claude Code writes a research brief, ask it to include frontmatter with the date, source URLs, and a status field. The vault becomes structured and filterable rather than a pile of loose notes.

Embeds

You can embed one note inside another:

![[Some Other Note]]

The exclamation mark turns the link into a transclusion. The full content of the target note appears in place, rendered live. Change the target, and every place that embeds it updates.

Useful for: research summaries that pull in source notes, dashboards that aggregate updates from sub-pages, and any kind of “single source of truth” structure.

Tip: Both standard markdown links [text](path) and wikilinks [[Note]] work in Obsidian. Wikilinks are easier inside the vault. Standard markdown is more portable if you ever move files to a different tool. Pick one and stay consistent. Wikilinks are the more common Obsidian choice.

Part 5: Three Features That Change Everything

Everything in Parts 1-4 gets you a beautiful markdown reader. Useful, but other apps have it. The three features in this section are what turn Obsidian into a second brain rather than a notebook.

1. Universal Search

Cmd+Shift+F (macOS) or Ctrl+Shift+F (Windows / Linux) opens vault-wide search. Type a query, and Obsidian returns every file containing it, with the matching snippets visible inline. Results update as you type.

The search is not just text. You can filter by tag, path, file property, line, or content type:

tag:#research
path:Projects/
[status:active]
line:(api AND error)
file:.png

Any of these can be combined. tag:#meeting path:2026 line:(decision) returns every meeting note in folders containing “2026” that has the word “decision” in any line.

This is the feature that pays for the entire setup. Three weeks from now, when you remember Claude Code wrote something about pricing models but cannot find it, search returns it in two seconds. Try doing that with a chat history.

2. Graph View

Cmd+G (macOS) or Ctrl+G (Windows / Linux) opens the graph view. Every note in your vault appears as a node. Every wikilink between notes appears as a line. The graph animates as it arranges itself, and clusters emerge - groups of notes densely connected to each other, with thinner threads to the rest of the vault.

The graph is interactive. Hover over a node to see its title. Click to open the note. Pan, zoom, filter by tag or folder, color nodes by attribute.

For solo work, the graph reveals shape. You see where your knowledge is dense and where it is thin. You see orphans - notes nobody links to, which usually means they are stuck somewhere and need either better links or a delete. You see hubs - notes that everything connects to, which usually means they are doing more work than their length suggests.

For Claude Code work specifically, the graph reveals what the AI has been spending time on. If three weeks of conversations produced a dense cluster around marketing and almost nothing around operations, that is a strategic observation, not an aesthetic one.

3. Backlinks

Every Obsidian note has a backlinks panel in the right sidebar. It shows every other note in the vault that links to the one currently open.

The implication is hard to feel until you live with it. You open a note on a person, or a project, or a concept, and at the bottom you see every other place in the vault where it appears. Meeting notes referencing them. Research briefs mentioning them. A briefing Claude Code wrote three weeks ago that touched the same topic from a different angle.

This is the difference between storing information and connecting it. Storage is a folder system. Connection is a knowledge environment. Backlinks are how a vault becomes the latter.

Tip: Backlinks only appear for files that are linked. Plain mentions of a name do not register. If you want a name to appear in backlinks, either wrap it in wikilink brackets [[Name]] when writing, or enable the “unlinked mentions” section in the backlinks panel (it shows you every plain-text mention of the current note’s title across the vault).

Part 6: Core Settings to Configure Right Away

Obsidian works out of the box. These four settings make it noticeably better for the Claude Code pairing specifically. All four live in Settings (Cmd+, on macOS, Ctrl+, on Windows / Linux).

1. Files and Links

Default location for new notes: “Same folder as current file.” Keeps notes near the context they were created in.
New link format: “Shortest path when possible.” Keeps wikilinks readable.
Use [[Wikilinks]]: ON. Makes typing internal links faster.
Detect all file extensions: ON. Lets Obsidian show non-markdown files (PDFs, images, code files) in the sidebar so you can browse and open them from inside the vault.

2. Editor

Default view for new tabs: “Live Preview.” The hybrid mode that renders most formatting as you type.
Show line number: Off by default; turn it on if you are working with Claude Code and want to reference specific lines in your prompts.
Show frontmatter: ON. Make properties visible at the top of notes by default.

3. Appearance

Theme: Pick one you can read for hours. The default light and dark themes are both excellent. Popular community themes for long-form reading: Minimal, Things, Catppuccin.
Font size: Bump to 16-18 if you read on a laptop. Your eyes will thank you in month two.
Translucent window: On macOS, off. Looks cool, costs readability.

4. Hotkeys

Worth scanning the full list once, but the two adjustments I recommend immediately:

Bind Insert template to a fast keystroke (e.g., Cmd+Shift+T). You will use templates more than you expect.
Bind Open graph view to a keystroke if Cmd+G conflicts with something on your system.

Tip: Settings live in .obsidian/ inside your vault. If you ever want to copy your configuration to a different vault, copy that folder. If you want a clean reset, delete it. Obsidian regenerates it on next launch.

Part 7: Plugins - When to Reach for Them

Obsidian has two plugin systems: Core plugins (built-in, official) and Community plugins (third-party, marketplace).

Resist the temptation to install everything. A vault with twenty plugins is a vault with twenty potential failure points, twenty things to debug, twenty surprises on a new device. Start lean. Add only what you have a concrete reason to add.

Core Plugins Worth Enabling

In Settings -> Core plugins, turn these on if they are not already:

Plugin	Why
Templates	Insert reusable note skeletons (meeting notes, research briefs, project plans) with one keystroke. Pairs beautifully with Claude Code, which can generate template files for you.
Daily notes	One note per day, auto-created. Acts as a journal, log, and landing pad.
Outline	The right-sidebar table of contents for the current note. Essential for long documents.
Quick switcher	The `Cmd+O` jump-to-any-file menu. Should be on by default.
Page preview	Hover over a wikilink, see the linked note preview without leaving the current one.
Properties view	Renders the YAML frontmatter as an editable form at the top of the note.
Workspaces	Save and restore multi-pane layouts. Useful if you have one layout for writing, another for research.
Audio recorder	Built-in voice notes, saved into the vault as audio files. Useful for capture-on-the-go.

Community Plugins Worth the Install

The community plugin marketplace has thousands of options. Three I recommend for the Claude Code pairing specifically:

1. Dataview

Turns frontmatter and inline metadata into a queryable database. You can write dataview code blocks that pull tables, lists, or cards from across the vault based on filters.

TABLE status, created, source
FROM "Research"
WHERE status = "active"
SORT created DESC

This is what turns a vault of notes into a vault of structured information. Useful for tracking projects, reading lists, contacts, anything that has consistent fields.

2. Excalidraw

Adds a full whiteboarding canvas inside Obsidian. Sketches, diagrams, flowcharts, system maps, all stored as .excalidraw files that live inside the vault and can be embedded in notes.

The Claude Code pairing is genuinely useful here: ask Claude to describe a system in text, sketch the system in Excalidraw, embed both in the same note. The diagram and the prose live together.

3. Iconize (or similar)

Lets you assign emojis or icons to folders and files in the sidebar. Looks aesthetic; the actual value is faster visual parsing of a large vault. Optional, but quietly improves the experience.

Plugins to Approach Cautiously

Some plugins are powerful but can quietly break your vault if they go wrong. Anything that auto-modifies many files, anything that renames in bulk, anything that touches frontmatter at scale. Read recent reviews before installing, back up your vault before turning these on, and never run multiple bulk-modifying plugins simultaneously.

Tip: Plugins live in .obsidian/plugins/ inside your vault. They are vault-scoped, not app-scoped. If you have multiple vaults, you can give each one a different plugin set. Useful for keeping a work vault minimal and a personal vault experimental.

Part 8: Sync and Mobile

The desktop app is the workshop. Mobile is the reading room and the capture surface. Most people want both. There are three real options.

Option 1: iCloud Drive (All-Apple, Free)

If you only use Apple devices and your vault is reasonably sized (under 50 GB), iCloud Drive is the simplest path. Free up to 5 GB of iCloud storage; existing iCloud+ users have more.

To set up:

Move your vault folder to ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/[VaultName]/ (Obsidian’s iCloud location). You can also use any folder inside ~/Documents/ if “Documents & Desktop” iCloud sync is on, but the dedicated Obsidian iCloud location is more reliable.
On your iPhone or iPad, open Obsidian. Choose “Create new vault in iCloud” and pick the same vault name. The mobile app will see the synced folder.
Sync is automatic. Save a file on the desktop; it appears on the phone within seconds.

Caveat: iCloud Drive is a file sync, not a real-time collaboration system. If you edit the same file on two devices simultaneously, you can produce conflict files. Easy to recover from, but worth knowing.

Option 2: Obsidian Sync (Cross-Platform, Paid)

$4/month (annual) for Standard, $8/month (annual) for Plus. End-to-end encrypted. Works across macOS, Windows, Linux, iOS, and Android.

To set up: enable “Sync” in Settings, create or log into an Obsidian account, choose which vault to sync. The mobile app then sees the synced vault when you log in.

Worth the spend if:

You use both Apple and non-Apple devices
You want true end-to-end encryption (iCloud is encrypted in transit and at rest but Apple holds the keys; Obsidian Sync holds none)
Your vault is large or includes sensitive material
You want one-year version history (Plus tier)

Option 3: Syncthing (Self-Hosted, Free, Technical)

For users who do not want any third-party service touching their files. Syncthing is open-source peer-to-peer file sync. It runs on your devices and syncs the vault directly between them with no server in the middle.

More setup. More moving parts. Total privacy and zero cost. Useful for very specific threat models; overkill for most.

What You Will Not Get on Mobile

The mobile Obsidian app is fully featured for reading, writing, and navigation. What it does not give you is a Claude Code session on your phone. Claude Code is a desktop CLI.

The practical pattern: produce on your laptop with Claude Code, consume on your phone with Obsidian. Look up a note in line at the coffee shop, append a thought while waiting at the dentist, voice-memo a half-formed idea on a walk. The vault is wherever you are. The AI is on the laptop you walk back to.

Anthropic does offer a “remote” command that allows Claude Code sessions to run in the cloud, which opens up phone-driven workflows once you have the basics down. Start with the laptop-Claude / phone-Obsidian split first. Add remote later if you want it.

Tip: Whatever sync method you choose, do not put your vault in a path that is also being synced by a second service. If iCloud Drive and Dropbox both watch the same folder, they will quietly fight over file ownership and corrupt your vault. One sync system per vault.

Part 9: Putting It All Together

Here is what a Claude Code + Obsidian pairing looks like once fully configured. This is the layout I actually run.

my-vault/
├── .claude/
│   ├── settings.json             # Claude Code permissions and hooks
│   └── skills/                   # Claude Code specialist roles
├── .obsidian/
│   ├── config                    # Obsidian core settings
│   ├── plugins/                  # Community plugins (Dataview, Excalidraw, etc.)
│   ├── themes/                   # Theme files
│   └── workspace.json            # Saved pane layouts
├── .mcp.json                     # Claude Code MCP server connections
├── CLAUDE.md                     # Brain file Claude Code reads on every session
├── Inbox/                        # New notes land here before being filed
├── Daily/                        # Daily notes (auto-created by core plugin)
├── Projects/                     # Active projects, one folder each
├── Research/                     # Research briefs, mostly by Claude Code
├── People/                       # One note per person of strategic relevance
├── Reference/                    # Long-lived reference material
└── Archive/                      # Notes you do not need active

The system in motion:

CLAUDE.md tells Claude Code what this folder is for, your conventions, and how to write notes that fit the vault’s structure. See the Claude Code Setup Guide for how to configure this file.
Claude Code produces notes - research briefs, meeting summaries, drafts, decision logs - into the appropriate folder.
Obsidian renders every file the moment it lands, makes it searchable across the entire vault, and shows you the graph of how it connects to everything else.
Wikilinks between notes turn the vault into a navigable network rather than a pile of folders.
Frontmatter on each note (date, status, tags, source) makes the vault filterable and queryable.
Sync mirrors the vault to your phone for reading and capture; the laptop stays the production surface.
Backlinks show you, on any note you open, every other note in the vault that touches it.

What you have after a month of running this: a knowledge base of hundreds to thousands of well-structured notes you did not have to write by hand, fully searchable, visually mapped, organized by your own preferences, and ready to be read by the AI as context for every new conversation.

What you have after six months: a personal knowledge environment that knows its way around your own thinking. Notes you forgot you wrote, surfacing through backlinks you never had to create. An AI that walks into every new session with the full institutional memory of everything you have built. A graph of your own work that reveals patterns you cannot see from the inside.

That is the payoff. The price of entry is fifteen minutes and a free app.

What Comes Next

You now have a working Obsidian vault paired with Claude Code, and a clear understanding of every concept that matters in the first six months. The next step is to use it for something real.

Open the vault tomorrow morning. Ask Claude Code to write the first research brief on a topic you care about. Watch it appear in Obsidian as it is being written. Click into it. Notice the table render, the headings format, the links light up. Add a wikilink to a related concept. Open the graph view. See your vault have its first connection.

That moment - the first time you watch the system click into place - is when the workflow stops being theoretical and starts being yours.

If you want to see what a production-grade AI system looks like - one that runs an actual agency with 27 agents and zero employees, with vaults like this at the core - I share the full architectures, templates, and live builds inside the Built, Not Hired community.

Join Built, Not Hired - $49/month, founding member pricing.

Or if you want a ready-to-deploy system you can install today, browse the AI Blueprint Templates - complete agent configurations, skills, automation workflows, and the vault structures that pair with them.