Obsidian Vault Setup¶

This document outlines the recommended setup for the Obsidian Vault to be used collaboratively with the pi-vault-mind multi-agent system. Includes the official Obsidian CLI (1.12+) for plugin/theme management, plus notesmd-cli for headless vault operations.

1. Vault Structure (PARA + Johnny Decimal + LLM Wiki)¶

We combine the PARA method, Johnny Decimal organization, and the LLM-Wiki structure to create a workspace that works for both humans and agents.

Vault/
├── 00 - System/              ← Templates, inbox, daily notes, meta-configuration
├── 10 - Projects/            ← Active projects (PARA)
├── 20 - Areas/               ← Ongoing domains (PARA)
├── 30 - Resources/           ← Reference material (PARA)
│   ├── Inbox/                ← 📥 Drop files here for passive agent ingestion
│   ├── Sources/              ← any2md-processed documents (immutable sources)
│   └── Articles/             ← External references
├── 40 - Archive/             ← Completed/archived items (PARA)
│
├── Agent/                    ← 🤖 Agent-Collaborative Workspace
│   ├── Inbox/                ← Human drops tasks/requests for agents (@agent-vault)
│   ├── Wiki/                 ← Agent-curated structured knowledge
│   │   ├── Concepts/         ← Agent-written concept pages with typed edges
│   │   ├── Entities/         ← People/orgs/systems with `agent:derived-from` links
│   │   ├── Syntheses/        ← Cross-topic analysis pages
│   │   └── Summaries/        ← Source document summaries
│   ├── Journal/              ← Agent activity log (timestamped, append-only)
│   ├── Tasks/                ← Agent task boards (Kanban markdown format or Bases)
│   └── Presentations/        ← NotebookLM-generated podcasts, slides, quizzes
│
├── index.md                  ← Master routing table (agent + human navigable)
└── CLAUDE.md                 ← Agent instructions + domain constraints

2. Obsidian CLI (1.12+) — the official way to script Obsidian¶

The official Obsidian CLI (requires Obsidian 1.12 installer, currently Catalyst/Early access) lets you script everything in Obsidian from the terminal. This is the safest, most direct way to install plugins, themes, and manage vault state.

Install¶

Update to Obsidian 1.12+ via the official installer.
Open Obsidian → Settings → General → Command line interface → enable.
Follow the prompt to register the CLI to your system PATH.
Restart your terminal.

After this, the obsidian command is available everywhere. Test with:

obsidian help
obsidian version

Key commands we'll use¶

Command	Purpose
`obsidian plugin:install id=<id> enable`	Install a community plugin by ID and enable it
`obsidian plugin:enable id=<id>`	Enable an already-installed plugin
`obsidian plugin:disable id=<id>`	Disable a plugin
`obsidian plugins:enabled`	List enabled plugins
`obsidian theme:install name=<name> enable`	Install and activate a community theme
`obsidian workspace:save name=<name>`	Save current layout as a named Workspace
`obsidian workspace:load name=<name>`	Load a saved Workspace
`obsidian search query="..." format=json`	Search the vault, output JSON
`obsidian tasks todo`	List all incomplete tasks
`obsidian task ref="file.md:8" done`	Mark a task done
`obsidian daily:append content="..."`	Add to today's daily note
`obsidian read path=...`	Read a file from the vault
`obsidian append content="..." path=...`	Append content to a file
`obsidian property:set name=... value=... path=...`	Set a YAML property
`obsidian bases`	List all `.base` files

Note: Obsidian must be running for the official CLI to work. For headless operations, use notesmd-cli (see below).

3. `notesmd-cli` (Yakitrak) — headless alternative¶

Yakitrak/notesmd-cli is a Go-based CLI for Obsidian that works without Obsidian running. Renamed from "obsidian-cli" to avoid confusion with the official one. Great for CI, containers, and agent environments.

Install¶

# macOS / Linux
brew tap yakitrak/yakitrak
brew install yakitrak/yakitrak/notesmd-cli

# Windows (Scoop)
scoop bucket add scoop-yakitrak https://github.com/yakitrak/scoop-yakitrak.git
scoop install notesmd-cli

# Arch (AUR)
yay -S notesmd-cli-bin

Key commands¶

Command	Purpose
`notesmd-cli add-vault /path/to/vault`	Register a vault (headless)
`notesmd-cli list-vaults`	List all registered vaults
`notesmd-cli set-default-vault "name"`	Set the default vault
`notesmd-cli create "note.md" --content "..."`	Create a note (Obsidian not required)
`notesmd-cli create "note.md" --content "..." --append`	Append to existing
`notesmd-cli create "note.md" --content "..." --overwrite`	Overwrite
`notesmd-cli move "old.md" "new.md"`	Move/rename (updates wikilinks)
`notesmd-cli delete "note.md"`	Delete a note
`notesmd-cli frontmatter "note.md" --print`	Print YAML frontmatter
`notesmd-cli frontmatter "note.md" --edit --key "x" --value "y"`	Set a property
`notesmd-cli search-content "term" --format json`	Content search, JSON output
`notesmd-cli list "30 - Resources"`	List folder contents
`notesmd-cli print "note.md"`	Print note contents

Use notesmd-cli when Obsidian is not running, for scripts, or in CI. Use the official obsidian CLI when Obsidian is open and you want full feature parity.

4. Required Community Plugins¶

Install via the official CLI (when Obsidian is running):

# Enable restricted mode OFF first
obsidian plugins:restrict off

# Install + enable each
obsidian plugin:install id=obsidian-git enable
obsidian plugin:install id=obsidian-breadcrumbs enable
obsidian plugin:install id=graph-analysis enable
obsidian plugin:install id=actions-uri enable
obsidian plugin:install id=shellcommands enable

Or install via the GUI: Settings → Community Plugins → Browse and search for the plugin by name.

Plugin	Install ID	Why
obsidian-git	`obsidian-git`	Auto-commits vault changes for backup & conflict resolution
Breadcrumbs	`obsidian-breadcrumbs`	Parses typed edges (`agent:related-to`) for graph UI
Graph Analysis	`graph-analysis`	Co-citation discovery on the native graph
Actions URI	`actions-uri`	x-callback-url endpoints for cross-app automation
obsidian-shellcommands	`shellcommands`	Bridge Obsidian events to pi agent workflows

Configuring the shellcommands bridge¶

The obsidian-shellcommands plugin can notify pi-vault-mind on every file save, eliminating reliance on filesystem watchers alone.

Prerequisite: pi must be running (it starts an HTTP server on http://127.0.0.1:11435 automatically when the vault-mind extension loads).

Step 1: In Obsidian, open Settings → Shell commands → New shell command.

Step 2: Configure as follows:

Field	Value
Alias	`Notify pi-vault-mind on save`
Shell command	See platform-specific command below
Platforms	All
Events	File saved

Platform-specific commands:

# macOS / Linux
curl -s -X POST http://127.0.0.1:11435/vault-mind/scan \
  -H "Content-Type: application/json" \
  -d "{\"file\":\"{{file_path:absolute}}\"}"

# Windows (PowerShell)
Invoke-RestMethod -Uri http://127.0.0.1:11435/vault-mind/scan `
  -Method POST `
  -ContentType "application/json" `
  -Body "{\"file\":\"{{file_path:absolute}}\"}"

Step 3: Save the command and verify by saving any markdown file in the vault. Check pi-vault-mind's HTTP endpoint:

curl http://127.0.0.1:11435/vault-mind/status
# Returns: { "running": true, "vaults": [...], "uptime": "120s", ... }

What this gives you: Instead of relying solely on fs.watch (which can be unreliable on WSL, network drives, and some Linux filesystems), every Obsidian file save sends an explicit notification to pi-vault-mind. The watcher still handles deduplication, grouping, and dispatch.

Beta plugins via BRAT (obsidian42-brat)¶

For beta plugins not in the official store, install obsidian42-brat (id: obsidian42-brat) and add beta plugin GitHub URLs via its interface. This is how the user's kb-2024 vault gets plugins like obsidian-excalidraw-plugin, obsidian-style-settings, mermaid-popup, etc.

5. Agent Skills Installation¶

To ensure pi agents know how to interact with these Obsidian-specific formats, install the kepano/obsidian-skills — 5 skills that teach agents Obsidian format.

For pi (recommended — auto-discovered at `~/.pi/agent/skills/<name>/SKILL.md`)¶

# Use the official skills CLI (pi is a first-class target)
DISABLE_TELEMETRY=1 yes y | npx -y skills add https://github.com/kepano/obsidian-skills \
  --skill obsidian-markdown --skill obsidian-bases \
  --skill json-canvas --skill obsidian-cli --skill defuddle \
  -g -a pi --copy -y

# Verify
for s in obsidian-markdown obsidian-bases json-canvas obsidian-cli defuddle; do
  [ -f ~/.pi/agent/skills/$s/SKILL.md ] && echo "✅ $s" || echo "❌ $s"
done

Why the skills CLI? The CLI is the official tool for installing agent skills. It handles agent detection, symlink/copy selection, security risk confirmations, and non-interactive mode (-y). Pi is a first-class target agent (-a pi), so the install lands at the correct path (~/.pi/agent/skills/<name>/SKILL.md).

The yes y pipe handles the security risk assessment confirmation that the CLI presents even with -y. The DISABLE_TELEMETRY=1 prevents anonymous usage data collection.

For OpenCode / Claude Code / Codex¶

# Universal install — auto-detects installed agents
npx skills add https://github.com/kepano/obsidian-skills

# Or target specific agents
npx skills add https://github.com/kepano/obsidian-skills -a opencode
npx skills add https://github.com/kepano/obsidian-skills -a claude-code

The 5 skills: - obsidian-markdown — Obsidian-flavored markdown (wikilinks, embeds, callouts, properties) - obsidian-bases — .base file format (database views, filters, formulas) - json-canvas — JSON Canvas format (.canvas for visual graphs) - obsidian-cli — official Obsidian CLI reference - defuddle — clean markdown extraction from web pages

These are what let the Miner, Broadcaster, and Heavy-Lifter agents produce valid Obsidian content.

6. Synchronization & Collaboration¶

Obsidian Sync (primary)¶

Since you use Obsidian Sync, this should be the primary mechanism for keeping the vault updated across your devices (desktop, mobile). Real-time updates seamlessly for human interaction.

CLI control: obsidian sync on, obsidian sync:status, obsidian sync:history file=..., obsidian sync:restore version=N.

Git & Git Worktrees (long-term & conflict resolution)¶

obsidian-git plugin — auto-commits every N minutes
Git Worktrees for Heavy-Lifter — large refactors in isolated branches, then merged

7. Recommended Obsidian Themes and Workspaces¶

Themes¶

Install via CLI:

obsidian theme:install name="Minimal" enable
obsidian theme:install name="AnuPpuccin" enable

Or via Settings → Appearance → Themes → Manage → Browse.

Workspaces¶

The Workspaces plugin (built-in in Obsidian 1.12+) lets you save pane layouts by name. Useful for: - "Inbox" workspace — only the daily note + Inbox folder - "Research" workspace — split pane with reading on left, notes on right - "Code review" workspace — terminal + vault side-by-side

# Set up your workspaces
obsidian workspace:save name="Inbox"
obsidian workspace:save name="Research"
obsidian workspace:save name="Code"

# Switch
obsidian workspace:load name="Research"

8. Leveraging Latest Obsidian Features¶

Obsidian Bases (`.base`)¶

Bases are database-like views for your markdown files. - Agent Usage: Agents generate .base files in Agent/Tasks/ or Agent/Wiki/ for dynamic tables, boards, galleries. - Structure: YAML for filters, formulas, views (table, cards, list, map, etc.).

CLI:

obsidian bases                       # list all .base files
obsidian base:views file=Tasks.base  # list views in a base
obsidian base:query file=Tasks.base  # query a base, output JSON

JSON Canvas (`.canvas`)¶

Canvas provides an infinite spatial canvas for visual organization. - Agent Usage: wiki_sync(format="canvas") translates the LanceDB entity/relation graph into a .canvas file. - Human Usage: Brainstorming, project architecture, exploring the agent-generated knowledge graph.

Obsidian Flavored Markdown & Callouts¶

Agents use advanced markdown features: - Callouts: > [!info], > [!warning], etc., for syntheses or contradictions - Embeds: ![[Note]] for transcluding summaries - Properties: Strict YAML frontmatter for typed edges

Properties (typed frontmatter)¶

Obsidian 1.4+ has typed properties (text, list, number, checkbox, date, datetime). Useful for typed-edge graphs:

obsidian property:set name="agent:related-to" value="[[X]]" type=list path=Note.md
obsidian property:read name="status" file=Note.md

9. Recommended Obsidian Settings¶

In Settings → Files & Links: - New link format: Shortest possible - Use [[Wikilinks]]: ON - Always update internal links: ON

In Settings → Core Plugins, enable: - ✅ Backlinks - ✅ Outline - ✅ Word count - ✅ File recovery - ✅ Workspaces (built-in 1.12+) - ✅ Bases

10. Plugin compatibility for the user's `kb-2024` vault¶

The user's existing vault at /mnt/c/users/kyleb/iCloudDrive/Documents/Vaults/kb-2024/ has 23 community plugins. Most are compatible with pi-vault-mind. Notable ones to integrate with:

Plugin	ID	Integration
`obsidian42-brat`	`obsidian42-brat`	Install beta plugins — useful for getting pre-release features
`obsidian-tasks-plugin`	`obsidian-tasks-plugin`	Task management — agents can use `obsidian task ref=... done` to toggle
`obsidian-excalidraw-plugin`	`obsidian-excalidraw-plugin`	Visual diagrams — Miner can embed `.excalidraw.md` in synthesis pages
`mermaid-popup`	`mermaid-popup`	Mermaid diagrams — render in pages
`obsidian-style-settings`	`obsidian-style-settings`	Vault-wide theming
`block-link-plus`	`block-link-plus`	Block-level references — useful for transclusion in syntheses
`homepage`	`homepage`	Set a home note — pi-vault-mind writes its landing page here

Setup Script (idempotent, safe to re-run)¶

Here's a one-shot script the user can run after Obsidian is running and the CLI is registered:

#!/usr/bin/env bash
# Install the recommended plugins via the official Obsidian CLI
# Requires: Obsidian 1.12+ running, CLI registered

set -e

PLUGINS=(
  "obsidian-git"
  "obsidian-breadcrumbs"
  "graph-analysis"
  "actions-uri"
  "shellcommands"
)

for p in "${PLUGINS[@]}"; do
  echo "→ Installing $p..."
  obsidian plugin:install id="$p" enable 2>&1 || \
    echo "  (already installed? trying enable:)"
  obsidian plugin:enable id="$p" 2>&1 || true
done

echo ""
echo "→ Installed plugins:"
obsidian plugins:enabled filter=community

Run it with:

chmod +x setup-obsidian-plugins.sh
./setup-obsidian-plugins.sh

Obsidian Vault Setup¶

1. Vault Structure (PARA + Johnny Decimal + LLM Wiki)¶

2. Obsidian CLI (1.12+) — the official way to script Obsidian¶

Install¶

Key commands we'll use¶

3. notesmd-cli (Yakitrak) — headless alternative¶

Install¶

Key commands¶

4. Required Community Plugins¶

Configuring the shellcommands bridge¶

Beta plugins via BRAT (obsidian42-brat)¶

5. Agent Skills Installation¶

For pi (recommended — auto-discovered at ~/.pi/agent/skills/<name>/SKILL.md)¶

For OpenCode / Claude Code / Codex¶

6. Synchronization & Collaboration¶

Obsidian Sync (primary)¶

Git & Git Worktrees (long-term & conflict resolution)¶

7. Recommended Obsidian Themes and Workspaces¶

Themes¶

Workspaces¶

8. Leveraging Latest Obsidian Features¶

Obsidian Bases (.base)¶

JSON Canvas (.canvas)¶

Obsidian Flavored Markdown & Callouts¶

Properties (typed frontmatter)¶

9. Recommended Obsidian Settings¶

10. Plugin compatibility for the user's kb-2024 vault¶

Setup Script (idempotent, safe to re-run)¶

3. `notesmd-cli` (Yakitrak) — headless alternative¶

For pi (recommended — auto-discovered at `~/.pi/agent/skills/<name>/SKILL.md`)¶

Obsidian Bases (`.base`)¶

JSON Canvas (`.canvas`)¶

10. Plugin compatibility for the user's `kb-2024` vault¶