Introduction¶

When performing knowledge base Q&A or using DSH for daily note processing, a common obstacle is that the model is unaware of the files within the vault, and users often forget the complete @ reference path. Manually running find and ls in the terminal to retrieve the directory structure, followed by typing the path into the input box, is repetitive and error-prone.

Obsidian Catalog (dsh-plugin-obsidian-catalog) consolidates this process into a single conversation view: the host side directly reads the vault directory from disk, the panel groups notes by folder, and includes a one-click copy for the @absolute path. Below, I introduce its positioning, capabilities, installation method, and usage considerations.

What is it¶

Obsidian Catalog is a DeepSeek Harness bundle maintained by scy88866-beep that renders an Obsidian vault into a real-time directory panel mounted on the conversation view. It solves two problems: first, it allows both the model and the user to visualize the structure of the vault’s contents; second, it transforms the reference path from “manual typing” to “a single click”.

The panel directly reads the vault directory on disk from the host side, displaying note titles, word counts, relative modification dates, tags, and the title outline (first three levels) for each note. Each note and folder row includes a one-click @absolute path copy button. The vault itself can be switched within the panel, eliminating the need to reinstall the plugin for a second vault.

Core Features¶

Below is an introduction in the order presented by the panel.

• Directory Tree: Groups follow the vault’s directory structure, displaying the number of notes per group; groups and notes can be collapsed independently; two buttons at the top of the panel allow collapsing or expanding all items at once.
• Search: Filters by title, full path, tags, and title text; automatically expands all matched items during search.
• Note Statistics: CJK character count plus Latin word count, relative modification date, and tags read from frontmatter.
• Title Outline: Displays the first three levels of headings for each note, indented by hierarchy, with the leading # removed; headings identical to the note title are skipped.
• @ Path Copy: “Copy @ Path” on note rows copies @D:\Notes\MyVault\folder\note.md; “Copy @ Reference Folder” on folder rows copies @D:\Notes\MyVault\folder (the root directory copies @D:\Notes\MyVault). Both locations flash a confirmation in place.
• Vault Switch: “Select Repository” opens the directory browser; you can paste a path and click Go, use .. to navigate up step-by-step, or directly select a drive letter. Directories that appear to be vaults (containing the .obsidian folder) are marked; “Use this directory” remembers the selection after switching.
• Refresh: Supports on-demand rescanning and polling every 15 seconds; unchanged notes utilize mtime + size caching.

Installation and Enabling¶

The official installation command is as follows:

dsh plugin --profile web add dsh-plugin-obsidian-catalog

If the plugin does not appear, restart DeepSeek Harness, open a session, and select “Knowledge Base Directory / Obsidian Catalog” in the conversation view switcher.

You can also skip npm and install directly from a checkout:

plugin_manager { action: "install_bundle", target: "<absolute path to this repository>" }

Requires DeepSeek Harness 0.2.x.

Vault Selection Order¶

The panel determines which vault to read in the following order:

1. ~/.dsh/obsidian-catalog.json, written by “Use this directory”, format is { "vault": "D:\\Notes\\MyVault" }
2. Environment variable DSH_OBSIDIAN_VAULT
3. Fallback directory <home>\obsidian

Deleting the configuration file reverts to the fallback directory.

HTTP Routes¶

The bundle registers three routes on the host webServer service. Except for vault switching, all are read-only and limited to markdown files within the selected vault:

Implementation Structure¶

The panel only uses --dsw-alias-* theme tokens, so it adapts to the current light or dark theme.

Applicable Scenarios and Considerations¶

Suitable for users who maintain their own Obsidian vaults and wish to reference notes directly within DSH sessions. For scenarios requiring frequent switching between multiple vaults, the internal switching mechanism is more convenient than reinstalling or modifying configuration.

Several points need attention. The plugin runs with the permissions of the current DSH process; please check the source code and license (MIT) before installing. The panel is read-only regarding the vault, performing only stat and read operations without writing files. The word count method counts CJK characters plus Latin words, using the regex [A-Za-z][A-Za-z0-9'’\-]*; scanning is limited to a maximum of 12 directory levels and 5,000 markdown files per round. Every screenshot in the README comes from a synthetic demo vault with six notes, containing no real notes, paths, or usernames.

Conclusion¶

The value of Obsidian Catalog lies in consolidating the steps of “viewing the directory” and “copying the reference” into a single conversation view. You can install it directly to try it out, and the vault path can be specified via an environment variable initially.

Directory Page: https://www.skillhub.cn/plugins/scy88866-beep/dsh-plugin-obsidian-catalog

GitHub: https://github.com/scy88866-beep/dsh-plugin-obsidian-catalog