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 12 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.
• 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 (default, pure filesystem)

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, property:set/property:remove delegate to it and everything else stays on FsAccess; 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, …).

Update

Re-running add pulls the latest (latest):

dsh plugin --profile web add dsh-obsidian

Or pin a specific version:

dsh plugin --profile web add dsh-obsidian@0.2.8

Restart the harness (dsh web) or refresh the Web UI after updating; verify with dsh plugin --profile web list.

Uninstall

dsh plugin --profile web remove dsh-obsidian

Configuration

In the DSH v0.2.2-rc.1 Web UI, open Plugins → dsh-obsidian → obsidian component → Configure and select Save configuration after editing. Leave vaultPath blank to auto-detect a vault. The DSH host log records the resolved path. You can also edit the profile's cordis.patch.yml.

Key	Default	Description
vaultPath	(auto-detected)	Absolute path to the vault; leave empty to auto-detect the currently-open vault from obsidian.json
useCli	false	Delegate property:set/property:remove to the obsidian CLI when available
vaultWorkspaceOnly	false	Expose obsidian_* tools only to agents whose session working directory is inside the vault; agents without a working directory receive no tools
excludeDirs	[".obsidian", ".git", ".trash"]	Directories excluded from search and list

Paths and Windows compatibility

• Tool paths are vault-relative and are always returned with /; inputs may use either / or \\.
• Tool path arguments must be relative. Unix absolute paths, Windows drive-letter paths, and UNC absolute paths are rejected; the configured vaultPath may be a local Windows path or a UNC vault root.
• Windows note identity is case-insensitive and recognizes .md, .MD, and other case variants; Unix keeps case-sensitive behavior and the existing .md semantics.
• Search removes \\r from CRLF lines while preserving Unicode paths and content. ripgrep is an optional accelerator: if it is unavailable or fails, the built-in scanner is used automatically.
• Vault discovery prefers the platform-native obsidian.json location (Windows %APPDATA%, macOS Library/Application Support, Linux .config) before trying other known locations. .exe/.cmd CLI forms are supported and filesystem access remains the fallback.

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; Windows recognizes mixed-case .md extensions)
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 [[wikilinks]] in pure filesystem)
obsidian_delete	Trash a note into .trash/ (reversible, never permanently deletes)
obsidian_set_property	Set or update a single frontmatter property (YAML) on a note
obsidian_delete_property	Remove a frontmatter property from a note
obsidian_tags	List all tags in the vault with usage counts

All tool path arguments are relative to the vault root (e.g. Folder/note.md); paths returned to the agent always use /.

Safety

• Path containment — every path argument is resolved and checked to stay inside the vault root; escapes (../, Unix/Windows absolute paths, or UNC 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)
• The plugin requires Node.js ≥ 22.12.0. Running dsh v0.2.2-rc.1 from npm or source requires Node.js ≥ 24.9.0.

dsh-obsidian@0.2.6 was verified on macOS with the npm release of dsh v0.2.2-rc.1. All 12 tools registered in the default mode, and obsidian_write, obsidian_list, and obsidian_read ran successfully against a temporary vault. The Web profile also verified vaultWorkspaceOnly: tools were visible only to sessions whose initial working directory was inside the vault. The type check, build, and all 112 tests passed.

Earlier checks verified Web profile loading on dsh v0.2.1-alpha.3, as well as bundle loading, registration of all 12 tools, and listing and reading notes in a temporary vault on v0.2.0-rc.2. Earlier version checks covered v0.1.7-rc.2, v0.1.5-alpha.1, v0.1.3-alpha.2, v0.1.3-alpha.1, v0.1.2-rc.1, v0.1.2-alpha.5, v0.1.2-alpha.4, v0.1.2-alpha.3, v0.1.2-alpha.2, v0.1.2-alpha.1, v0.1.1-rc.2, and v0.1.0-rc.8.

Development

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

Changelog

0.2.8

• Add a DSH Web configuration form for the vault path, Obsidian CLI, workspace scope, and excluded directories. Saved settings take effect immediately, and the host log records the resolved vault path. Issue #5

0.2.7

• Fix slow obsidian_backlinks queries in large vaults by indexing note paths once per call. Note moves reuse the same index when updating links. Issue #4
• Support cancellation during obsidian_backlinks, obsidian_search, and obsidian_tags scans.

0.2.6

• Add the optional vaultWorkspaceOnly setting to expose obsidian_* tools only to agents whose working directory is inside the vault. It defaults to false to preserve cross-workspace access.

To show Obsidian tools only in DSH workspaces inside the vault, set this in the active profile's cordis.patch.yml:

- id: obsidian
  config:
    vaultPath: /absolute/path/to/ObsidianVault
    vaultWorkspaceOnly: true

0.2.5

• Fix double quoting of Windows .cmd scripts so commands work when script paths or arguments contain spaces or Unicode characters.

0.2.4

• Harden Windows compatibility: standardize agent-facing paths on /, accept \\ inputs, and reject drive-letter/UNC absolute path escapes.
• Fix Windows search, backlink, move/delete result paths, and wikilink rewriting; cover CRLF, Unicode, and mixed-case Markdown extensions such as .MD.
• Support Windows .exe/.cmd forms for ripgrep and the Obsidian CLI, with automatic fallback to built-in implementations when unavailable or failing.

0.2.3

• Fix source typecheck/build compatibility after dsh v0.1.2-alpha.2/alpha.3 stopped re-exporting JsonValue from @deepseek-ai/dsh-tools, while preserving compatibility with older dsh releases.

0.2.2

• obsidian_tags and inline #tag extraction now support CJK and other Unicode characters.
• obsidian_backlinks / obsidian_move resolve [[wikilinks]] uniquely following Obsidian's rules: same-named notes are no longer over-matched, and ambiguous links are no longer mis-rewritten.
• obsidian_set_property / obsidian_delete_property preserve existing YAML comments, anchors/aliases, and block formatting instead of re-serializing.
• Reliability: atomic writes when obsidian_move updates links, fallback for cross-filesystem moves/deletes, and consistent search results with or without ripgrep.

License

MIT © 2026 MingZeng