claude-obsidian

claude-obsidian is a local-first knowledge system for Claude Code and compatible Agent Skills hosts. It turns source material into linked, source-cited Obsidian pages; answers from the evidence already in the vault; and provides explicit workflows for research, retrieval, maintenance, and visual mapping.

Your vault remains a normal directory of Markdown, JSON, and source files. It is not hidden in a plugin cache, locked in a cloud database, or silently uploaded to a model.

From source to living knowledge

Most AI note workflows stop after saving text. claude-obsidian is organized around a repeatable loop: retain the source, ground the claims, connect the knowledge, then put it back to work.

• Capture with context. Bring local sources through a visible inbox and preserve immutable, content-addressed copies before synthesis.
• Ground every important claim. Source and claim ledgers retain authority, freshness, support, contradiction, confidence, and review state.
• Connect what you learn. Build linked pages, indexes, Maps of Content, methodology-aware structures, and Obsidian Canvas views.
• Use the vault again. Query, research, retrieve, lint, and fold what is already known instead of starting every conversation from zero.

See the vault

The output is meant to remain useful with or without an agent: plain Markdown for portability, Obsidian for navigation and visual exploration.

Why it feels different

• Local by default. The vault is user-owned and works as ordinary files. Network egress is a separate, explicit decision.
• Sources survive the summary. Notes point back to durable source evidence; unsupported and contradictory claims remain visible.
• Knowledge compounds deliberately. Ingestion, querying, linting, retrieval, research, and rollups share one provenance-aware model.
• Parallel agents cannot race the vault. Workers return drafts. One orchestrator inspects and applies one recoverable transaction.
• Capabilities are stated honestly. Optional tools are detected, maturity is declared, and missing adapters degrade clearly instead of being simulated.

This is not an automatic transcript recorder, a cloud sync service, a factual oracle, or a substitute for backups and source control.

Quick start

The safest first run uses a source checkout and a separate user vault. Every mutating setup command previews its exact operation before it can apply.

1. Get the product

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

The checkout contains the product. It is not your knowledge vault.

2. Initialize a separate vault

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

Review the JSON plan and copy its approved_plan_sha256, then apply that exact operation:

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply

For an existing Obsidian vault, use the non-destructive adopt workflow described in the installation guide.

3. Start from the vault

Open the new directory in Obsidian, then run Claude Code from that directory with the local plugin:

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

Start with:

/claude-obsidian:wiki

Then place a source in inbox/ and invoke /claude-obsidian:wiki-ingest. Save an answer explicitly with /claude-obsidian:save; ask the vault with /claude-obsidian:wiki-query.

For Codex, OpenCode, Gemini, or ZCode, preview and then apply the portable skill links from the product checkout:

bash scripts/setup-multi-agent.sh --host codex
bash scripts/setup-multi-agent.sh --host codex --apply

Cursor and Windsurf use workspace-local skill discovery. Marketplace setup, every supported host, vault adoption, upgrades, and uninstall steps are covered in the full installation guide.

15 skills, one system

The skills are small enough to invoke directly and coordinated enough to share the same evidence, vault-selection, and mutation rules.

Build and use the wiki

Skill	What it does
wiki	Initializes or adopts a vault, diagnoses readiness, and routes work
save	Saves one scoped answer or insight—never an automatic transcript
wiki-ingest	Turns captured sources into linked pages and provenance records
wiki-query	Answers read-only from relevant vault evidence
wiki-lint	Reports dead links, orphans, metadata gaps, stale indexes, and empty sections

Extend the workflow

Skill	What it adds
autoresearch	Bounded web research with explicit egress and a separate canonical merge
canvas	Wiki-scoped Obsidian Canvas creation and maintenance
defuddle	Clean, readable web content before ingestion
wiki-fold	Extractive, traceable rollups of the operation log
wiki-mode	Generic, LYT, PARA, or Zettelkasten filing conventions
wiki-retrieve	Contextual prefixes, BM25, and optional cosine reranking
wiki-cli	Obsidian CLI reads and search with transaction-safe writes

Reference skills

Skill	What it provides
obsidian-markdown	Correct Obsidian Flavored Markdown, links, embeds, and callouts
obsidian-bases	Native .base tables, cards, filters, formulas, and summaries
think	A structured observe, listen, connect, create, and grow review loop

Claude Code exposes namespaced invocations such as /claude-obsidian:wiki-lint; other hosts use their native Agent Skills invocation. Trigger phrases and exact contracts live in each skills/<name>/SKILL.md.

Trust is part of the architecture

The product never treats a source checkout, plugin cache, or contributor state as the default vault. A vault is selected explicitly, through CLAUDE_OBSIDIAN_VAULT, by the nearest .claude-obsidian.json, or by one unambiguous initialized ancestor. If selection is uncertain, the command exits without writing.

One logical knowledge operation is one recoverable transaction:

1. Read every target and record its expected SHA-256.
2. Let parallel workers return drafts and evidence only.
3. Merge the complete change into one operation bundle.
4. Inspect the bundle, then apply it once.
5. Report the operation ID and exact changed paths.

The core holds one process-lifetime vault lock, journals backups, uses atomic replacement, and restores the prior state if an apply cannot finish. A changed target is a conflict, never a silent overwrite. Git checkpoints, destructive repairs, network egress, and canonical research merges remain explicit operations.

Read the transaction contract, provenance contract, and Compound Vault architecture for the machine-facing detail.

Honest capability boundaries

Input or capability	Current support
Local filesystem sources	Implemented bounded, content-addressed byte capture
Images	Metadata, hash, size, and bounded dimensions when available
PDF and EPUB	Metadata, hash, and size; no built-in semantic extraction
URL and YouTube	Validated consent plans; a configured external runner is required
OCR	Local-file consent plan; a configured external runner is required
BM25 retrieval	Local and deterministic
Contextual prefixes or remote models	Optional and gated by explicit egress consent
Obsidian CLI	Optional for reads/search; filesystem transport remains available

High-risk accepted claims require two independent sources. Unsupported or contradictory evidence stays visible, and a grounded refusal is preferred over an invented citation. Model-based retrieval falls back to deterministic BM25 when the embedding or reranking stage cannot be trusted.

Shape the vault to the way you think

wiki-mode can route new notes using four methodologies without bulk-moving existing knowledge:

Mode	Filing principle
Generic	Sources, concepts, entities, and sessions
LYT	Maps of Content and linked atomic notes
PARA	Projects, Areas, Resources, and Archives
Zettelkasten	Stable identifiers, atomic notes, and dense links

Generic is the default when no mode is configured. Switching modes changes how new notes are routed; it does not silently reorganize old ones. See the methodology modes guide.

Operator reference

The wrapper is python3 scripts/claude-obsidian.py.

Command	Effect
doctor --vault PATH	Show vault selection and readiness
init PATH [--approved-plan-sha256 HASH --apply]	Plan or create a separate vault
adopt PATH [--approved-plan-sha256 HASH --apply]	Plan or adopt an existing Obsidian vault
migrate --vault PATH [--approved-plan-sha256 HASH --apply]	Add v1 ledgers and configuration without rewriting legacy data
transaction inspect BUNDLE --vault PATH	Validate a write bundle without mutation
transaction apply BUNDLE --vault PATH --approved-plan-sha256 HASH	Apply one inspected, recoverable operation
transaction recover --vault PATH [--force-stale-lock]	Restore an interrupted operation
lint --vault PATH [--as-of YYYY-MM-DD] [--exclude GLOB]...	Emit findings deterministic for the declared UTC date
contracts --verify --vault PATH	Execute capability readiness contracts
capture plan --vault PATH [SOURCE ...]	Run a local capture preflight without writes