dsh-worktrees adds a project workflow on top of native DeepSeek Harness Workspaces and Sessions. A Project owns a root directory, any number of task worktrees, and all Sessions created in those directories. Harness keeps conversation history; Git keeps source isolation and history; this plugin records and presents the relationship.

Features

• Directory-based Projects: register one Git repository as a Project and native root Workspace.
• Multiple Sessions: start and switch between multiple native DSH Sessions in the project root or any task.
• Task isolation: create each task on a unique branch in a standard external Git worktree.
• Shared project instructions: automatically load AGENTS.md and DEEPSEEK.md from the project hierarchy through DSH's durable instruction loader.
• Persistent history and archive: use native DSH session persistence and archive, with a seven-day plugin archive-index retention policy by default.
• Compact dashboard: a non-destructive floating panel lists Projects, task Workspaces, Sessions, new-session actions, switching, and archive actions.
• Safe creation: clean-source checks, managed subprocess cancellation, atomic state, and rollback on partial failures.

Model

Project (Git repository + native root Workspace)
├── root Session A
├── root Session B
├── Task: login (Git worktree + native Workspace)
│   ├── Session C
│   └── Session D
└── Task: API (Git worktree + native Workspace)
    └── Session E

Project data is stored outside the source repository at <root>/state.json. Version 0.1 state is migrated automatically to the version 0.2 Project model.

Installation

dsh plugin --profile web add dsh-worktrees
dsh --profile web --dump-config
dsh --profile web

For a reviewed GitHub revision:

dsh plugin --profile web add github:Alexis-fish/dsh-worktrees#<commit-sha>

Quick start

In a Session whose directory belongs to a clean Git repository:

/project create My project
/project task create login flow
/project show

Open the Worktree button at the lower-right of the DSH interface. The dashboard can start another Session in the root or task Workspace, open an existing Session, and archive it.

The original short command remains compatible:

/worktree create login flow
/worktree list

If needed, /worktree create automatically registers the current repository as a Project first.

Commands

Command	Description
/project create [name]	Register the current repository as a Project.
/project list	List all managed Projects.
/project show	Show the current Project's task and Session counts.
/project task create <name>	Create a task branch, worktree, and native Workspace.
/project task list	List isolated tasks for the current Project.
/project session list	List root and task Sessions, including archive state.
/project session archive <id>	Archive a Session through the native Workspace registry.
/project cleanup	Remove expired entries from the plugin archive index.
/worktree create <name>	Compatible shorthand for task creation.
/worktree list	Compatible shorthand for task listing.

Project instructions

The bundle extends the built-in agent-instructions row rather than creating a second prompt mechanism. It deliberately recognizes only two project files:

File	Responsibility	Typical content
AGENTS.md	How the agent should work. Stable, portable operating rules.	Coding conventions, required tests, review rules, forbidden operations, definition of done.
DEEPSEEK.md	What DeepSeek is working on. Project-specific context and coordination.	Product goal, architecture map, current milestones, task boundaries, common commands, Worktree and Session conventions.

Keep the files complementary: AGENTS.md owns normative rules, while DEEPSEEK.md owns descriptive project context. Do not repeat or contradict the same instruction in both files.

Example AGENTS.md at the Git project root:

<!-- AGENTS.md -->
# Working rules
- Run tests before committing.
- Keep public changes documented.

Example DEEPSEEK.md:

<!-- DEEPSEEK.md -->
# Project objective
Build the API without breaking the stable client contract.

# Development map
- `packages/api`: public API implementation.
- `packages/client`: stable consumer contract.
- Use one Worktree task per feature and keep related Sessions in that task Workspace.

DSH loads both files from the project root down to each Session directory and records them as durable context. Root files apply project-wide; a nested AGENTS.md adds rules for its module, while a nested DEEPSEEK.md adds module-specific context. Local filename variants are intentionally disabled so every Session sees the same shared source of truth.

Configuration

- id: worktree
  name: dsh-worktrees
  config:
    root: ""
    branchPrefix: dsh/worktree/
    requireCleanSource: true
    archiveRetentionDays: 7
    cleanupIntervalMinutes: 60
    gitCommand: git
    gitGraceMs: 2000
    maxGitOutputBytes: 1048576

Option	Default	Meaning
root	empty	$DSH_HOME/worktrees, falling back to ~/.dsh/worktrees.
branchPrefix	dsh/worktree/	Generated task branch prefix.
requireCleanSource	true	Refuse task creation from a dirty source worktree.
archiveRetentionDays	7	Retain archived Session metadata in the plugin Project index.
cleanupIntervalMinutes	60	Archive-index cleanup interval.
gitCommand	git	Git executable in the Harness execution environment.
gitGraceMs	2000	Git process-tree cancellation grace period.
maxGitOutputBytes	1048576	Retained bytes for each Git output stream.

Retention boundary

DSH currently exposes durable Session creation, listing, history, and archive, but no supported hard-delete method for Session logs. Therefore the seven-day policy removes expired archive metadata from this plugin's Project index; the underlying conversation log remains under the active DSH persistence backend. The plugin deliberately does not delete backend JSONL files directly because doing so could corrupt registry and cache state. Hard deletion can be added when DSH publishes a lifecycle API for it.

Development

npm install
npm run verify
npm pack --dry-run

The plugin targets the current DSH 0.1.0-rc.6 Workspace, Session, Commands, Subprocess, and client-slot contracts. See the official plugin guide, Workspace reference, and client modules reference.

License

MIT © Alexis-fish