Nwflower/dsh-file-claim
40Last commit Aug 14, 2026
dsh-file-claim DSH plugin
dsh-file-claim provides a coordination protocol for parallel DSH sessions to avoid overwriting each other's files. It offers claim/release tools, heartbeat-based stale detection, and an async pending merge area with git 3-way merge.
How to install the dsh-file-claim DSH plugin
dsh plugin add dsh-file-claimCopying does not run this command. Review the repository and version before installing the dsh-file-claim DSH plugin.
dsh-file-claim DSH plugin data source
dsh-file-claim DSH plugin snapshot date: Aug 16, 2026
discovered
What the dsh-file-claim DSH plugin can do
- Claim and release exclusive ownership of file paths before editing, with directory and workspace-wide claims.
- Automatic heartbeat refresh via agent lifecycle events; stale claims cleared on next activity or by heartbeat interval.
- Asynchronous pending merge area: write into a pending area and auto-merge via git 3-way merge when the owner releases.
- Write guard that denies writes to files actively claimed by another session, with hints for wait, takeover, or pend.
- Audit log of all claim/release/pending mutations for traceability and post-crash reconciliation.
Where the dsh-file-claim DSH plugin fits
- Two sessions editing the same file: one claims, the other uses pending_write to avoid blocking.
- Recovering from a crashed session: its claims become stale or are cleared immediately, allowing takeover.
- Coordinating multiple agents working on a shared codebase without file conflicts.
- Using /claim-status to inspect current claims and pending area for debugging.
Who the dsh-file-claim DSH plugin is for
- Developers using DSH for parallel agent workflows in the same workspace.
- Users who need robust file-level coordination without external lock servers.
dsh-file-claim DSH plugin limitations
- Write guard is cooperative (fail-open): it does not prevent direct file system writes outside DSH.
- Git 3-way merge requires git installed on PATH; pending merge may require manual resolution for conflicts.
- Only supports Node >=18; no browser side or build step needed.
- State directory (.dsh-file-claim) should be added to .gitignore to avoid clutter.
dsh-file-claim DSH plugin: from the repository README
Quoted from the Nwflower/dsh-file-claim README, the upstream source of the dsh-file-claim DSH plugin. Copyright remains with the original authors.
> **Write in parallel. Never overwrite.** > File claim / protection for concurrent DeepSeek Harness (DSH) sessions working the same workspace. When several DSH sessions run in parallel against one workspace, they have no awareness of each other: two sessions can overwrite the same file, a crashed session leaves stale state behind, and a session that wants to edit a file another session owns can only wait or guess. `dsh-file-claim` turns a proven coordination protocol into native DSH tools, lifecycle events, and a write guard — so parallel agents cooperate instead of clobbering each other. ```text claim_files({ paths: ["README.md"] }) # "I'm editing this" write / edit ... # writes to files claimed by others are denied release_files({ paths: ["README.md"] }) # "done — pending edits auto-merge now" ``` ## Table of Contents - [Features](#features) - [Why](#why) - [Install](#install) - [Quick Start](#quick-start) - [Usage Examples](#usage-examples) - [Tools](#tools) - [Commands](#commands) - [Write Guard](#write-guard) - [Configuration](#configuration) - [Audit Log](#audit-log) - [Pending Merge Area](#pending-merge-area) - [Enforcement Boundary](#enforcem
Read the full READMERepository license: MIT
dsh-file-claim DSH plugin questions
How do I install dsh-file-claim?
Run `dsh plugin add dsh-file-claim` in your DSH environment. This installs the package from npm. You need DSH with Node >= 18 and git available on PATH.
What happens if a session crashes while holding a claim?
The heartbeat mechanism detects the crash: the agent lifecycle event `agent/disposed` auto-releases all claims. Additionally, the staleMs timeout (default 2 hours) clears claims without a heartbeat. You can also force takeover with `claim_files(force: true)`.
Can I write to a file claimed by another session?
The write guard denies the write with a hint. You can either wait for the owner to release, use `pending_write` to put your edited content into the pending area for later auto-merge, or take over the claim if it's stale.
How does the pending merge work?
When you call `pending_write`, the plugin records your edited content plus the git HEAD base. When the original owner releases, it performs a git 3-way merge (current × base × pending). If conflict-free, it applies automatically; otherwise, you can run `pending_apply` manually to resolve conflicts.
Is the write guard secure? Can it be bypassed?
The write guard works at the DSH tool layer and is cooperative (fail-open). It does not prevent direct file system writes outside DSH tools. For full enforcement, consider using workspace isolation. The guard is disabled by setting `guard: false` in plugin config.