This is a writeup of how I've set up a single Obsidian vault to serve as a personal operating system — for planning, thinking, running a team, and capturing knowledge. The goal isn't "take better notes." The goal is to have one place that holds everything I need to remember, surfaces what matters today, and shrinks the recurring work of running my life and my job.
- Write once, query many. A person, project, or objective is defined in exactly one place. It surfaces everywhere it's relevant via queries over frontmatter.
- The vault is executable. Markdown isn't just documentation — it's the interface to automations that read and write the same files.
- Capture is cheap; synthesis is valuable. Lowering the cost of capture to near zero lets rollup skills do the hard work of compressing noise into signal.
- Stay in flow; dispatch later. Inline action tags (mine are
;;) let me mark something as actionable mid-sentence without breaking out of the note. A background skill sweeps them up and routes each one — to the ticket system, a queued message, a new vault task, or a research task — so writing is never interrupted by task-management overhead. - Interrupts are data. Every ad-hoc request gets logged, then periodically analyzed for automation candidates. This is how the system improves itself.
- Nothing leaves the vault without review. Drafts live locally; external systems are publishing targets, not sources of truth.
- Git is the time machine. Automatic commits mean full history without ceremony. Experiments are safe; nothing is ever really lost.
- Plain text outlives tools. Every capability below is a convenience layer over markdown files. If the tooling disappears tomorrow, the content is still readable in any text editor.
- One substrate for everything. Meeting notes, OKRs, projects, people, ideas, daily logs, research clippings — all in the same vault, all in plain markdown, all cross-linked.
- Make the vault answer questions, not just store answers. A home dashboard that shows what's overdue, what's due today, what's in progress, and what's upcoming — without me maintaining any of those lists by hand.
- Shrink repetitive work to a single command. End-of-day summary, weekly rollup, OKR check-in, 1:1 prep — tasks that would take 30 minutes become a slash command that produces a draft I review.
- Keep capture frictionless. If capturing a thought, an interrupt, or a task takes more than a few seconds, it won't happen. Everything else is built around making that true.
- Own my data. Plain markdown files in a git repo. No proprietary format, no vendor lock-in, full history, works offline.
The vault is organized by kind of thing, not by project:
| Directory | Purpose |
|---|---|
people/ |
One note per person, cross-linked from everywhere they appear |
projects/ |
Active initiatives, tagged with status |
daily/, weekly/ |
Time-based logs |
ideas/ |
Automation candidates and half-formed thoughts |
Clippings/ |
Web captures, later distilled into reference notes |
.obsidian/plugins/ |
The human UX layer |
.claude/skills/ |
The automation layer |
Every note carries frontmatter (type, tags, created, status fields where relevant). That structured metadata is the glue that lets the vault query itself.
Querying the vault as a live system
- Dataview — the single most important plugin. Turns frontmatter into a queryable database. Every dashboard, index, and roster is a live query, not a hand-maintained list.
- Tasks — a global task queue with overdue / due-today / in-progress views.
- Omnisearch — ranked full-text search.
- Smart Connections — semantic similarity between notes, surfaces related thoughts without explicit links.
Capture and authoring speed
- Templater — scripted note creation with variables.
- NL Dates — natural-language date input (
@today,@next friday). - Obsidian Linter — frontmatter normalization on save.
- Paste Image Rename / Unique Attachments — keeps assets tidy without thinking about it.
Navigation and visual scanability
- Homepage — boots into the dashboard rather than whatever was open last.
- File Explorer Plus / Note Count / Folder Collapse — a better sidebar.
- Icon Folder, File Color, Rainbow Sidebar, Pretty Properties — visual cues that make large vaults navigable at a glance.
- Custom Sort / Sort & Permute Lines — deliberate ordering where it matters (roadmaps, priorities).
Specialized content
- Excalidraw — diagrams inline with notes.
- Leaflet — maps.
- Lovely Mindmap — brainstorm canvases.
- Code Styler — syntax highlighting.
Sync and integration
- Git / GitHub Sync — the vault is a git repo; every change commits automatically.
- Local REST API / MCP Tools — exposes the vault to agents and other tools.
- Terminal — run shell commands without leaving the vault.
- Text Extractor — pull text from PDFs and images so they're searchable.
The vault is also a Claude Code project. Slash commands (skills) read and write the same markdown files. A few categories:
- Daily rhythm — morning briefing, today's plan, end-of-day review, evening summary.
- Periodic rollups — weekly and monthly rollups, OKR check-ins, health/quality scoring.
- Team and people ops — team status snapshots, 1:1 balance audits, interview prep packets.
- Capture and triage — quick-capture classification, interrupt logging, interrupt analysis for automation candidates, and sweeping inline
;;action tags out of notes to dispatch them. - Research and synthesis — cross-system research, clipping compilation, draft filing.
- External sync — pulls from calendar, ticket system, chat, email, git hosting; writes back as queued actions.
- Publishing — promotes drafts from the vault to wherever they need to live.
Each skill is a markdown file with a description and a prompt. The agent reads the vault, does the work, and writes results back. The markdown stays the source of truth.
The companion file setup-your-vault.md in this gist is a prompt you can paste into a coding agent to walk you through building a similar vault. It asks one question at a time, skips anything you decline, and won't install things without confirming.
- Open a terminal in the directory where you want the vault (or an existing one).
- Run
claudeto start a session. - Paste the contents of
setup-your-vault.md. - Answer the checkpoints as they come up.
Tip: if you want the prompt available as a reusable slash command, save it to .claude/commands/setup-vault.md in the directory and invoke it with /setup-vault.
cdinto the target directory.- Run
codexand paste the prompt into the chat. - Approve file writes as they're proposed.
Open the agent in the target directory, paste the prompt, and follow along. The prompt is deliberately tool-agnostic — it describes behavior, not tool-specific commands.
- Obsidian installed (the plugin checklist step assumes you'll install plugins through Obsidian's Community Plugins browser yourself — agents can't do that for you).
- Git available on your
$PATH. - A coding agent with file-write access to the target directory.
Expect the full walkthrough to take 15–30 minutes depending on how many optional pieces you opt into.