Preface¶

DeepSeek Harness (dsh for short) is an open-source agent runtime developed by DeepSeek, with the core philosophy of “Everything is a plugin”: models, tools, skills, sessions, sandboxes, storage, and UI can all be replaced or extended at the configuration layer without modifying the host source code. The official repository is located at deepseek-ai/deepseek-harness, and it is currently in a preview phase for Harness developers.

In actual usage, it is common to run multiple DSH sessions simultaneously in the same workspace: one for editing documents, one for modifying source code, and one for running tests. The host itself does not coordinate these sessions’ writes to the same file. Two sessions may overwrite the same file sequentially; if a session crashes or is force-killed, there is no built-in cleanup for expired file locks. When you want to edit a file that someone else is working on, you can only wait idly or take a gamble and write directly.

The community directory DeepSeek Harness Plugin Repository features the dsh-file-claim session and messaging plugin maintained by Nwflower. It turns file claiming/releasing, heartbeat takeover, and async pending merge area based on git three-way merge into native DSH tools and write guards. It should be clarified upfront: this directory is an independent website, not officially affiliated with DeepSeek/HyperGAN, and is not an official app store. Whether to install and trust a plugin still depends on reviewing the repository’s source code and license.

As of August 18, 2026, both the directory page and GitHub repository show 6 stars, with the MIT license and JavaScript as the primary language. The installation commands in this article are based on the original text of the directory page, and its functions and usage are cross-referenced with the repository’s README and package.json.

What is dsh-file-claim¶

dsh-file-claim is a Host plugin for DeepSeek Harness that provides file claiming and protection for concurrent sessions sharing the same workspace. The repository address is Nwflower/dsh-file-claim, with the current npm version 0.1.7 and a requirement of node >= 18. It has no Browser-side code, no build steps, only uses Node.js built-in modules, and the documentation states that it is Windows-friendly.

The problem it solves can be summed up in one sentence: first declare “I am editing these paths”, and other sessions’ direct writes will be rejected; if you need to write immediately without blocking, you can put your changes into the pending merge area, and perform a git three-way merge once the holder releases the lock. The project’s README summarizes it as Write in parallel. Never overwrite.

The project documentation also notes that the DSH host has no built-in cross-session file protection; when the author scanned 505 repositories tagged with the dsh-plugin topic during their research, no similar file claiming/coordination plugin was found. This is the project’s own research conclusion, which was also repeated on the directory page, and this article does not treat it as independent third-party statistics.

Core Features¶

The capabilities listed in the repository’s README can be divided into the following sections, all cross-referenced from the Chinese and English READMEs without additional inference:

1. Claiming and Releasing. A session calls claim_files before editing to declare exclusive ownership of files or directories. Repeated claims will be idempotently merged; claiming a directory will overwrite all paths under it; claiming '.' is equivalent to claiming the entire workspace. After finishing edits, use release_files to release specified paths, or release all at once.
2. Heartbeat, Stale Takeover, and Orphan Self-Healing. Heartbeats are automatically refreshed via agent/created and agent/status; when a session exits normally, agent/disposed will release all its claims. If a session crashes or is force-killed, the next session activity will clean up dead records based on process PID, with a fallback scan at the heartbeat interval. The default staleMs is 2 hours, mainly targeting old records without PIDs; such records can be taken over using force.
3. Async Pending Merge Area. When a file is occupied by someone else, you do not need to wait idly. pending_write writes the “modified new content + the git HEAD base at the time” into the pending merge area. After the holder calls release_files, the plugin will perform a three-way merge of current × base × pending using git merge-file: if there are no conflicts, it will write to disk and clear the entry; if there are conflicts, it will write to disk with conflict markers and retain the entry; if the base is missing, it will reject the request without blindly merging.
4. Write Guard. The plugin intercepts write / edit / bash / pwsh via tools/pre-execute. When the target path is claimed by another active session, the call will be rejected, with three suggested solutions: wait for the other party to release, force-take over after the other party’s lock becomes stale, or use pending_write instead. read operations are not intercepted. git commit is not blocked by default; set guardCommit to true to reject commits that explicitly commit paths claimed by other active sessions.
5. Audit Log. Every claim, takeover, release, pending write/merge/discard will append a JSON line to the workspace’s state directory. Heartbeats are intentionally not logged to avoid filling up the log. audit.jsonl will automatically rotate when it exceeds 1MB.

There is also a set of slash commands: /claim, /release, /claim-status, with the same semantics as the tools above, for use when the model is unavailable or for users who prefer to type commands manually. Command execution is only logged to the session log and will not enter the model’s history. The pure logic core claim.mjs can also be used independently of DSH, invoked via node claim.mjs status | audit | claim ....

Installation and Activation¶

The installation command given on the directory page is as follows, run it in the DeepSeek Harness terminal:

dsh plugin add github:Nwflower/dsh-file-claim

For reproducible installations, fix the commit hash as specified on the directory page:

dsh plugin add github:Nwflower/dsh-file-claim#<commit>

There is also a command dsh plugin add dsh-file-claim in the repository’s README, which uses the npm package name. For daily installations, use github:Nwflower/dsh-file-claim from the directory page as the standard. For local checkout development or manual verification, the README provides:

dsh plugin --profile web add -w link:<repository path>

The runtime environment requires DSH and node >= 18. The three-way merge calls git merge-file, so git must be in the PATH.

The plugin runs with the permissions of the current dsh process, and code may be executed during installation. Before installing, you should check the source code repository and the MIT license; only install plugins you trust.

Quick Start¶

The official quick start can be summarized in four steps.

1. Claim first, then edit. To modify a file, call claim_files first to declare exclusive ownership, so other sessions will not be able to write directly to these paths.
2. Your own claims will not block yourself. Writing to a file claimed by another active session will be rejected, with the holder’s information and suggestions included in the rejection message.
3. Do not wait idly when a file is occupied; use pending_write to put your modified content (including the git HEAD base) into the pending merge area. After the other party calls release_files, automatic three-way merge will run for conflict-free changes; resolve conflicts manually with pending_apply if needed.
4. Release after finishing edits. release_files clears the claims, automatically merges eligible pending entries, and surfaces entries that require manual handling.

The minimal call sequence is as follows:

claim_files({ paths: ["README.md", "src/"] })
write / edit ...
release_files({ paths: ["README.md"] })

Typical Usage¶

The two examples below are taken directly from the repository’s README, not made-up scenarios.

Two sessions sharing a workspace. Session A holds README.md, and Session B also wants to edit it:

// Session A
claim_files({ paths: ["README.md"], note: "Rewrite documentation" })
write  ...  README.md          // Allowed: own claim
release_files({ paths: ["README.md"] })

// Session B —— Running concurrently
who_claims({ paths: ["README.md"] })          // → Claimed by A
write ... README.md                           // → Rejected with prompt
pending_write({ path: "README.md", content: "..." })  // Async, non-blocking
// After A releases, the entry will automatically perform three-way merge (or surface for manual pending_apply)

Recovering from a crashed session. After Session A crashes mid-work, the stale record without a PID will expire after staleMs (default 2 hours), then you can take over:

claim_status()
claim_files({ paths: ["README.md"], force: true })

The FAQ adds more details: under normal circumstances, a crashed or force-killed session will be cleaned up immediately via PID on the next session activity, so you do not need to wait the full 2 hours; staleMs is a slow fallback safeguard.

The 8 tools visible to the model are listed below, with the calling session as the identity, no --as flag required:

Configuration, State Directory, and Merge Area¶

Configuration is passed via the plugin bundle’s cordis.patch.yml. The default patch in the repository only inserts the plugin entry, with optional settings documented in comments and the README:

An example of overriding the configuration from the README:

- insert:
    - id: dsh-file-claim
      name: dsh-file-claim
      config:
        staleMs: 3600000        # 1 hour
        guardCommit: true       # Also guard explicit git commits

The claim registry, pending merge area, and audit logs are all stored in .dsh-file-claim/ under the workspace root. The documentation recommends adding this directory to .gitignore. The state persists across restarts, and the plugin will not modify the .git/ directory.

The layout of pending entries is:

pending/<relpath>/content     Pending new file content
pending/<relpath>/base        git HEAD version at write time (merge base)
pending/<relpath>/meta.json   { pender, claimedBy, at, baseSha }

The prerequisite for pending_write is that the target is actively claimed by another session; otherwise, you should first call claim_files and then write directly. The base is only recorded if the path exists in the git HEAD, and entries without a base are intentionally marked as non-automergeable. pending_apply will also reject the request if any session still occupies the target path, until it is released.

Applicable Scenarios and Notes¶

Who this plugin is for can be directly seen from its documentation positioning: multiple DSH sessions (or multiple Agents) sharing a workspace, needing to edit files in parallel without overwriting each other’s changes. Parallel work across multiple repositories is also supported — the claim root is divided by the workspace resolved from the session’s cwd, falling back to cwd if there is no workspace, naturally isolating different repositories.

There are several boundary rules you must remember before using, all taken from the README’s “Write Guard” and “Interception Boundaries” sections, not additional warnings:

1. The guard is a collaborative safeguard, not an enforced lock. Any shell (e.g., echo > file), scripts, external editors, IDEs, and git operations can bypass the tool stack. bash / pwsh will only do its best to parse redirect targets and explicit write command target parameters; if the target cannot be parsed, the request will be allowed (fail-open). The documentation lists this as an intentional design choice rather than a bug.
2. The plugin runs with the permissions of the current dsh process. Check the source code, license, and recent commits before installing; use fixed commit hashes for reproducible installations. The community directory can serve as a discovery entry point, but cannot replace manually auditing the source code.
3. Pending entries will not be blindly merged. Entries will be retained with a reason if the base is missing, the target is still occupied, there are three-way merge conflicts, or the target file is missing. Use pending_show to view details, then process with pending_apply or pending_drop.
4. Whether this set of tools is visible to the model depends on the current deployment’s tool display/restriction policies. The plugin itself is registered globally via ctx.tools.register with the same path as the official toolkits; if you cannot see them in the interface, first check the deployment’s tool filtering rules, rather than assuming the plugin was not installed correctly.

Summary¶

What dsh-file-claim does is very specific: it adds a layer of file claiming for parallel DSH sessions sharing a workspace, routing conflicting changes to the git three-way merge pending area instead of letting later-writing sessions directly overwrite files. It is a community MIT project maintained by Nwflower, and is not an official DeepSeek plugin.

Directory page: https://deepseek-harness-plugin.com/en-US/plugins/dsh-file-claim/

GitHub: https://github.com/Nwflower/dsh-file-claim