Obsidian Workflow

SwarmVault generates Obsidian-compatible markdown with wiki-links, frontmatter, and optional Dataview blocks. This guide describes the recommended workflow where Obsidian is the IDE, the LLM is the programmer, and the wiki is the codebase.

Setup

Initialize a vault with Obsidian workspace config:

mkdir my-vault
cd my-vault
swarmvault init --obsidian --profile personal-research

This creates a .obsidian/ directory with:

  • app.json — new files go to wiki/insights/, attachments to raw/assets/, wiki-links enabled
  • core-plugins.json — file explorer, global search, graph, backlinks, outgoing links, tags, page preview
  • graph.json — node-type color groups (source, module, concept, entity, rationale, symbol) plus project-based groups, all using Obsidian's native {a, rgb} color format
  • types.json — property type declarations so Obsidian Bases, Dataview, and the Properties sidebar correctly type confidence as number, created_at as datetime, tags as tags, etc.
  • workspace.json — opens wiki/index.md and key index pages on first launch

Open the vault directory in Obsidian. You should see the wiki structure in the sidebar and the graph view available immediately.

Capture

Use Obsidian Web Clipper to clip web articles directly into your vault:

  1. Install the Web Clipper browser extension.
  2. Configure it to save clips into your vault's inbox/ directory (or raw/ directly).
  3. Clip articles from your browser — they arrive as markdown with metadata.

Then import the clips:

swarmvault inbox import

Or let watch mode auto-import:

swarmvault watch

For images in clipped articles, use Obsidian's "Download attachments" command (bind it to a hotkey in Settings → Hotkeys) to pull remote images to raw/assets/ so the vault has local copies.

Ingest

Process sources one at a time with guided sessions. With --profile personal-research, guided mode is already the default for ingest/source commands, so --guide is optional and --no-guide is the opt-out:

swarmvault ingest ./raw/clipped-article.md --guide

The guided flow reads the source, discusses key takeaways, proposes wiki updates for review, and writes a source guide to wiki/outputs/source-guides/. A single source might touch 10-15 wiki pages — summaries, entity pages, concept pages, cross-references.

For batch processing without the guided dialogue:

swarmvault ingest ./raw/
swarmvault compile

Browse

With Obsidian open alongside your terminal:

  • Graph view shows the shape of your wiki — what is connected, which pages are hubs, which are orphans.
  • Wiki pages update in real time as you compile. Follow [[wiki-links]] to navigate between sources, concepts, and entities.
  • Backlinks panel shows every page that references the current one.
  • `wiki/index.md` is the central navigation hub — every page listed with links and summaries.

Query

Ask questions against the compiled wiki:

swarmvault query "What are the key themes?" --save

Answers are saved to wiki/outputs/ by default. Open them in Obsidian to read, annotate, or link to other pages. Supports markdown, report, slides, chart, and image output formats.

Maintain

Periodically health-check the wiki:

swarmvault lint --deep

This identifies contradictions between pages, stale claims, orphan pages with no inbound links, missing cross-references, and coverage gaps. The LLM suggests new questions to investigate and new sources to look for.

Dataview Queries

The personal-research profile enables dataviewBlocks by default, which adds Dataview query blocks to dashboard pages. Install the Dataview plugin in Obsidian to activate them.

Example queries over SwarmVault frontmatter:

TABLE source_type, occurred_at, participants
FROM "wiki/sources"
SORT updated_at desc
LIMIT 25
TABLE occurred_at, participants, container_title
FROM "wiki/sources"
WHERE occurred_at
SORT occurred_at desc

Every dashboard is designed to work as plain markdown first. Dataview blocks are a progressive enhancement, not a requirement.

Slide Decks with Marp

Install the Marp Obsidian plugin to render --format slides output as presentation decks directly in Obsidian:

swarmvault query "Summarize the key findings as a presentation" --format slides

Version Control

The vault is just a directory of markdown and JSON files. Initialize a git repo for version history, branching, and collaboration:

git init
git add -A
git commit -m "Initial vault"

SwarmVault can also install git hooks for automatic refresh on commit and checkout:

swarmvault hook install