What Is dsh-at-file? @ File Mentions for the DSH Web UI

dsh-at-file is an @ file mention plugin in the DeepSeek Harness (DSH Plugin) ecosystem that brings Codex-style @file mentions to the web interface: type @ in the composer to search the current workspace and insert a file or directory path, which the plugin verifies before the agent executes. This article is an independent guide based on the official README, covering what it is, core features, installation, typical usage, and common troubleshooting.

What Is dsh-at-file?

dsh-at-file fixes the inefficiency of manually copying file paths into the web interface: typing @ opens a path picker, searches the workspace, and inserts the selection so file references feel as smooth as an IDE. The following positioning and facts come from the official README (source).

dsh-at-file is maintained by fsmargoo, written in JavaScript, and open-sourced under MIT. It provides workspace path references for the DeepSeek Harness web interface. Typing @ opens a candidate menu where plain queries match filenames and queries containing / match path segments in order, so src/view can find src/client/view.ts. Once selected, the path stays visible in the draft's reference bar and can be opened or removed. Before the agent starts a step, the plugin confirms the path exists inside the active workspace and adds a reference message such as <workspace-reference path="docs/spec.pdf" kind="file" />; it does not open the file or list the directory's contents. Note that the README explicitly points out that the latest official DeepSeek Harness now includes built-in @file and @session reference features, so new installations should prefer the official implementation, while this plugin remains available for existing setups and is maintained on a best-effort basis.

What Are the Core Features of dsh-at-file?

dsh-at-file's core capabilities are @-triggered search and insertion, path verification with reference messages, directory navigation, a smart default index, and global-plus-workspace file filters: they turn @ mentions into a stable, predictable interaction. Feature facts come from the official README (source).

• @ path picker: up to 50 candidates with shallow paths first and directories before files at the same depth; exact, prefix, and compact matches rank ahead of looser ones.
• Path verification and reference messages: the plugin confirms the path exists before the agent runs and injects a workspace-reference marker; it never reads file contents or expands directories.
• Directory navigation: pressing ArrowRight on a highlighted directory advances the draft to @path/ without a trailing space and keeps the menu open.
• Smart default index: skips version-control directories, IDE metadata, dependency trees, caches, and build output, plus system metadata files such as desktop.ini, Thumbs.db, and .DS_Store.
• Global and workspace file filters: Exact and Regex matching modes with an independent case-sensitive switch; invalid regular expressions are rejected before saving.
• Index configuration: maxIndexedFiles caps the number of indexed entries, and ignoreDirs replaces the built-in exclusion list entirely.

How to Install and Enable dsh-at-file?

Enabling dsh-at-file takes one step: install the plugin and restart the Web profile, and DeepSeek Harness 0.3.0 or later can use @ references in the composer. Install commands come from the official README (source).

1. Install the plugin: this plugin is a GitHub source with no npm package; use the standard catalog command.

dsh plugin --profile web add github:fsmargoo/dsh-at-file

2. Restart to enable: restart the Web profile so the Host and the browser client load the plugin.

dsh --profile web

3. Update the plugin: use the update command to upgrade to the latest version (the README also offers a tag-archive direct install).

dsh plugin --profile web update dsh-at-file

4. Remove the plugin: remove it when it is no longer needed.

dsh plugin remove dsh-at-file

After installation, return to the web interface and type @ in the composer to open the path picker. The plugin applies to DeepSeek Harness 0.3.0 and later; earlier releases read file content during submission and enforced file-size limits, so behavior differs.

Typical dsh-at-file Usage

Day-to-day usage is a three-step flow — type @, search, select — plus three optional behaviors: directory navigation, pasted-text policy, and file filters. Usage details come from the official README (source).

1. Search and insert a path: type @ in the composer to open the picker, filter candidates by keywords, and select one; the path is inserted into the draft and shown in the reference bar.

Review @docs/spec.pdf

2. Step into directories: when a directory is highlighted, press ArrowRight to enter it; the draft advances to @path/ without a trailing space, and the menu stays open for the next selection. Enter or pointer selection finishes the reference.

3. Handle pasted text: by default, an @path pasted from another application is treated as ordinary text and never opens the picker or creates a reference marker; turn off Ignore @ mentions in pasted text in Settings -> File mentions for the older behavior.

4. Configure file filters and the index: manage filter rules in Settings -> File mentions, and write index configuration to the profile's cordis.patch.yml (usually ~/.dsh/profiles/web/cordis.patch.yml).

cat ~/.dsh/profiles/web/cordis.patch.yml

nano ~/.dsh/profiles/web/cordis.patch.yml

- id: dsh-at-file
  config:
    maxIndexedFiles: 10000

dsh-at-file Troubleshooting

dsh-at-file issues concentrate on four areas — "@ does not open the picker", "broken references or missing files", "unexpected pasted @path behavior", and "deep directories are hard to find" — with symptoms, causes, and fixes below. The troubleshooting basis comes from the official README (source).

1. Symptom: typing @ does not open the picker. Cause: the plugin is not installed or the Web profile was not restarted. Fix: install the plugin and restart the profile (dsh --profile web); versions below 0.3.0 do not support the mechanism.

2. Symptom: a referenced path fails, or files are missing from the candidate list. Cause: the path escapes the workspace, is excluded by a filter rule, or exceeds the maxIndexedFiles cap. Fix: reference only workspace-relative paths, check the File mentions rules and index configuration; reinstalling refreshes the session index cache.

dsh plugin --profile web add github:fsmargoo/dsh-at-file

3. Symptom: a pasted @path opened the picker or became a reference marker. Cause: the default policy should treat it as ordinary text. Fix: confirm that Ignore @ mentions in pasted text is enabled (it is on by default) in Settings -> File mentions.

4. Symptom: files in deep directories cannot be found. Cause: the candidate menu shows at most 50 entries, and deep entries are displaced by shallow paths. Fix: use a query containing / to match path segments in order (such as src/view), or step into the directory first and keep selecting.

Use Cases and Notes

dsh-at-file fits DeepSeek Harness users who heavily reference workspace files in the web interface, especially workflows that prefer Codex-style @ mentions and want to avoid manual path copying. Facts come from the official README (source).

Good use cases: handing file or directory paths to the agent every day; referencing non-text files such as PDFs and images (path only, no content read); and switching between multiple workspaces while keeping separate filter rules per workspace.

Notes and limitations:

• the official DeepSeek Harness now has built-in @file/@session references; prefer it for new installations, while this plugin serves existing setups on a best-effort basis;
• only 0.3.0 and later are supported; earlier releases read file content and enforced file-size limits during submission;
• an @path token cannot contain whitespace or another @ character; absolute paths and paths escaping the workspace are ignored;
• the reference dock only renders tokens present in the current session's settled workspace index, and the picker index is cached for 30 seconds per session.

Project Links

dsh-at-file is an MIT open-source project maintained by fsmargoo, hosted on GitHub.

Visit the plugin detail page for full information: dsh-at-file.

This page is an independent guide rewritten from the plugin's official README — for authoritative documentation and the latest changes, please refer to the source: FSMargoo/dsh-at-file. A plugin is third-party code that runs on your machine once installed; listing it here is not an endorsement — please review the source before installing.