dsh-workstate

A structured work-state protocol for handing off AI coding tasks between agents.

dsh-workstate is a local-first plugin for DeepSeek Harness. It captures what an agent is doing now: task state, progress, decisions, failures, verification, changed paths, next actions, and a Git integrity fingerprint. It is not a conversation dump.

中文文档

Why

Normal handoffs preserve prose. Workstate preserves a machine-readable state packet and checks that the workspace still matches before another agent resumes it.

• checkpoint: pause and preserve current work.
• transfer: create a shareable export for another agent or developer.
• resume: validate and inject an existing packet; never changes Git state.
• diff: compare two checkpoints by stable work-item IDs.

Install

Requires Node.js 22.19+ and DeepSeek Harness 0.1.0-rc.6.

dsh plugin --profile web add dsh-workstate

Add this insert to ~/.dsh/profiles/web/cordis.patch.yml, preserving existing rows:

- insert:
    - id: workstate
      name: dsh-workstate

Restart DSH. For a temporary source checkout, point an equivalent patch at the locally installed package.

Commands

/workstate checkpoint [note]
/workstate transfer [target]
/workstate list
/workstate inspect [id]
/workstate diff <from> <to>
/workstate validate [id]
/workstate resume [id]
/workstate resume [id] --allow-diverged

The model also receives workstate_capture, workstate_list, workstate_read, workstate_diff, workstate_validate, and workstate_resume tools.

Storage and safety

Packets use dsh.workstate/v1alpha1 and live under .dsh/workstate/. Checkpoint history is local and gitignored. Only transfer exports are intentionally trackable. Packets contain paths and hashes, never file contents or diffs. Known credential patterns are rejected before persistence.

Resume validation compares Git branch, commit, dirty state and a content fingerprint. Divergence fails closed. The plugin never checks out, resets, stashes, stages, commits, or pushes.

Development

npm install
npm run check

License

MIT