DeepSeek Harness Plugin: dsh-agent-project-sync

Introduction¶

DeepSeek Harness (DSH) uses a plugin-based architecture. During local development, developers often need to switch between agent tools such as Codex and Claude Code. Although these tools store sessions differently, they usually record the current working directory (cwd). This plugin reads that metadata to aggregate the project directories scattered across each tool under DSH management, registering them as native Workspaces for unified management and use in DSH.

Core Features¶

harzva/dsh-agent-project-sync is a workflow plugin that primarily provides the following capabilities:

• Automatic Discovery: Automatically discovers project directories for Codex and Claude Code.
• Workspace Registration: Registers discovered directories as native DeepSeek Harness Workspaces.
• Manifest Management: Manages the shared project manifest ($DSH_HOME/agent-project-sync/projects.json) and supports registration through the public ctx.workspaceRegistry API.
• CLI Tool: Provides a local command-line tool (dsh-agent-project-sync) for scanning, listing, and manually registering projects.
• Safety Boundaries:
  • Reads up to 128 KiB from the beginning of each JSONL file and extracts only cwd metadata.
  • All write operations default to dry-run mode.
  • Sync only adds or reuses Workspaces and never deletes existing data, sessions, or project directories.
  • The manifest uses atomic writes, process locks, and user-private file permissions. It contains local absolute paths and should not be committed to public repositories.

Installation and Activation¶

Add the plugin using the official installation command:

dsh plugin --profile web add https://github.com/Harzva/dsh-agent-project-sync/releases/latest/download/dsh-agent-project-sync-0.1.0.tgz

After installation is complete, restart the corresponding profile to use it.

Typical Usage¶

The plugin provides two ways to operate on the project manifest: a local CLI and built-in DSH tools.

Local CLI Tool¶

The local CLI tool scans directories and manages the manifest file.

1. Read-Only Scan:
   View the currently discovered Codex and Claude projects and identify which ones are already Workspaces.

    dsh-agent-project-sync scan

2. Scan and Write Manifest:
   Save the scan results to the shared manifest file.

    dsh-agent-project-sync scan --save --confirm

3. Read Manifest:
   View the shared project manifest for the current DSH home.

    dsh-agent-project-sync list

4. Manually Register a Project:
   Manually add a directory to the manifest. Without --confirm, it only provides a preview.

    dsh-agent-project-sync add /path/to/project --confirm

DSH Tools¶

In the DSH environment, you can directly manage Workspace registration through built-in tools.

• agent_projects_scan: Performs a read-only scan and displays discovered projects.
• agent_projects_list: Reads the shared project manifest for the current DSH home in read-only mode.
• agent_projects_sync: Merges discovery results and registers missing Workspaces (dry-run by default).
• agent_projects_add: Manually adds an existing directory (dry-run by default).

To perform actual writes, set the following parameters when invoking the tool:

{
  "dryRun": false,
  "confirm": true
}

Configuration Notes¶

The plugin supports adjusting behavior through configuration files or environment variables.

Notes and Compatibility¶

• Permissions and Security: The plugin runs through the current DSH process. Ensure the DSH process has permission to read the data directories of the source agents (such as Codex and Claude Code).
• Data Retention: Uninstalling the plugin does not delete existing Workspaces, project directories, or the shared manifest file.
• Manifest Security: The manifest file contains local absolute paths and is machine-local data. It should not be committed to public code repositories.
• Compatibility Baseline: DeepSeek Harness / dsh 0.1.0-rc.8, Cordis ^4.0.1, Node.js ^22.19 || >=24.