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.6

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

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

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)
• Node.js ≥ 22.12.0

Compatibility has been checked against dsh v0.2.1-alpha.3: the local running Web profile links this checkout and enables the plugin, and this DSH version still supports the plugin's apply, defineTool, ctx.tools.register, and agent lifecycle APIs. This project passes typecheck and build, and all 112 tests pass. Earlier runtime checks on dsh v0.2.0-rc.2 confirmed that the profile loader accepts the bundle, all 12 tools register, and obsidian_list and obsidian_read execute successfully against a temporary vault. 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.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