mingzeng21/dsh-obsidian

Connect DeepSeek Harness (dsh) to a local Obsidian vault. Because an Obsidian vault is just a folder of Markdown files on disk, your dsh agent can search, read, write, move, and trash notes directly — no MCP server, no OAuth.

中文 | English

What it does

Once dsh-obsidian is installed, your dsh agent can read and write a local Obsidian vault directly. On startup the plugin detects your vault (or reads the path you configured) and mounts 9 obsidian_* tools covering search, read, write, append, move, delete, and backlink lookups.

Features

• Zero server — reads/writes the vault filesystem directly; no Local REST API community plugin, no standing MCP server.
• Optional Obsidian-native ops — when the obsidian CLI is available, backlinks and move delegate to it (link-aware moves); otherwise everything falls back to a pure filesystem implementation.
• Safe by default — deletes move notes into .trash/ (reversible), paths can't escape the vault root, and .obsidian/ is never touched.

How it works

dsh agent calls obsidian_* tools
   │
   ▼
VaultAccess interface
   ├─ FsAccess   — node:fs + hand-written frontmatter/wikilink parsing (always available)
   └─ CliAccess  — when the obsidian CLI is detected, delegates backlinks/move to it (everything else stays on fs)

On startup the plugin resolves the vault root as "explicit vaultPath wins, else auto-detect from obsidian.json"; when useCli is on and the CLI is detected it enables CliAccess, and any CLI failure silently falls back to FsAccess.

Install

dsh plugin --profile web add dsh-obsidian

Replace web with the profile you run your agent in (web, headless, tui, …).

Uninstall

dsh plugin --profile web remove dsh-obsidian

Configuration

Key	Default	Description
vaultPath	(auto-detected)	Absolute path to the vault; leave empty to auto-detect the currently-open vault from obsidian.json
useCli	true	Delegate backlinks/move to the obsidian CLI when available
excludeDirs	[".obsidian", ".git", ".trash"]	Directories excluded from search and list

Tools

Tool	Purpose
obsidian_list	List notes in the vault (filter by subdirectory, limit results)
obsidian_search	Full-text search with match lines + context (case-insensitive, .md only)
obsidian_read	Read a note (body + parsed frontmatter)
obsidian_frontmatter	Read only a note's YAML properties
obsidian_backlinks	Find notes linking to a note via [[wikilinks]]
obsidian_write	Create or overwrite a note (creates parent directories)
obsidian_append	Append text to the end of a note
obsidian_move	Move/rename a note (updates links when the CLI is available)
obsidian_delete	Trash a note into .trash/ (reversible, never permanently deletes)

All tool path arguments are relative to the vault root (e.g. TradeArena/deploy.md).

Safety

• Path containment — every path argument is resolved and checked to stay inside the vault root; escapes (../ or absolute paths) are rejected.
• Reversible delete — obsidian_delete only moves notes into the vault's .trash/, never permanently deletes.
• Hands off .obsidian/ — search and list exclude .obsidian/, .git/, and .trash/ by default.
• Preserves frontmatter and wikilinks — reads/writes don't break YAML properties or [[links]] (unless the task explicitly asks).

Requirements

• DeepSeek Harness (dsh)
• Node.js ≥ 22.12.0
• Obsidian CLI (optional, for link-aware moves and CLI backlinks)

Development

npm install
npm run build      # tsdown → lib/
npm run typecheck  # tsc --noEmit
npm test           # vitest

License

MIT © 2026 MingZeng