In development practice for DeepSeek Harness (DSH), having an AI Agent inspect the current Git state before modifying code is a common requirement. Existing Git tools are often overly complex, or not limited to “inspection” functionality, which can easily cause Agents to perform destructive actions such as committing or switching branches. dsh-workspace-snapshot provides a controlled, read-only solution.

Feature Positioning

dsh-workspace-snapshot is a client plugin for DeepSeek Harness, maintained by txy-ucas. It exposes a workspace_snapshot tool to the model and reports the state of the Git workspace (such as branch, tracking status, and file-change classification) as validated structured data. It is a “probe” rather than a complete workflow, with its core value lying in safely reading state.

Core Capabilities

The plugin mainly provides the following capabilities:

  • Read-only status report: Runs Git commands through ctx.subprocess and reports the current branch, tracking branch, ahead/behind counts, detached HEAD status, and whether the workspace is clean.
  • Path classification: Clearly distinguishes path types, including:
    • changed: Files with changes, with details broken down into indexStatus (staging area status) and worktreeStatus (working tree status).
    • conflict: Files with merge conflicts.
    • untracked: New untracked files.
  • Strict operation restrictions: The plugin declares read-only permissions, and in practice:
    • Never stages files.
    • Never switches branches.
    • Never writes Git configuration.
    • Never creates commits or pushes.
    • By default, Git locks, FSMonitor, and untracked cache are disabled to ensure query results are not affected by environmental interference.
  • Structured output: The returned JSON object includes complete statistics (stagedCount, unstagedCount, untrackedCount, etc.) and path entries, with all paths relative to the repository root and no absolute paths exposed.

Installation and Activation

Before installing, ensure the environment meets the dependency requirements: Node.js ^22.19.0 || >=24.0.0 and DeepSeek Harness 0.1.0-rc.6.

Install using the official prebuilt package:

dsh plugin --profile web add https://github.com/txy-ucas/dsh-workspace-snapshot/releases/download/v0.1.0/dsh-workspace-snapshot-0.1.0.tgz

After installation, verify that the plugin loaded correctly with the following command:

dsh --profile web --dump-config

The output should include the workspace-snapshot configuration line.

Typical Usage

After receiving instructions, the Agent can invoke the workspace_snapshot tool. For example, the instruction received by the Agent may be:

Inspect the Git workspace before making changes.

An example of the canonical object returned by the tool is as follows:

{
  "status": "ok",
  "repositoryRoot": ".",
  "branch": "feature/status-tool",
  "detached": false,
  "upstream": "origin/feature/status-tool",
  "ahead": 2,
  "behind": 0,
  "clean": false,
  "entries": [
    {
      "kind": "changed",
      "path": "src/index.ts",
      "indexStatus": "M",
      "worktreeStatus": "M"
    },
    {
      "kind": "changed",
      "path": "README.md",
      "indexStatus": ".",
      "worktreeStatus": "M"
    },
    {
      "kind": "untracked",
      "path": "notes.txt"
    }
  ],
  "totalPaths": 3,
  "conflictCount": 0,
  "stagedCount": 1,
  "unstagedCount": 1,
  "untrackedCount": 1,
  "omittedPaths": 0,
  "truncated": false
}

Configuration Options

After installation, the plugin uses the default configuration. If adjustments are needed, override them in the --profile web configuration file:

- id: workspace-snapshot
  config:
    timeoutMs: 5000
    maxGitStdoutBytes: 262144
    maxPathRecords: 500
    maxResultBytes: 131072

The configuration fields are described as follows:

Field Default Description
timeoutMs 5000 Timeout for Git command execution, range 100 - 120000 ms.
maxGitStdoutBytes 262144 Upper limit for Git output bytes, range 1024 - 4000000. Exceeding it returns OUTPUT_LIMIT.
maxPathRecords 500 Upper limit for path records retained in memory, range 1 - 10000.
maxResultBytes 131072 Upper limit for the final returned JSON result bytes, range 1024 - 4000000.

Note: The configuration is flat, and if invalid limits are set, the plugin will fail to load.

Applicable Scenarios and Considerations

  • Applicable scenarios: Suitable for scenarios where the Agent needs to assess the current state of the codebase (such as whether there are conflicts or uncommitted changes), especially in read-only deployment environments.
  • Usage limitations: This is a probe tool, not a complete workflow. If the Agent needs to inspect specific changed line content, create commits, or manage branches, a dedicated Git workflow or review plugin should be used.
  • Security: The plugin declares dependencies through inject = ['tools', 'subprocess'] and is activated only when both Cordis services are simultaneously available. The subprocess environment clears all GIT_* environment variables, ensuring query results are not affected by environment variables controlled by users or the model.
  • Provenance checks: It is recommended to review the source code and license before installation. The plugin uses the MIT license and is maintained on GitHub.

dsh-workspace-snapshot provides a secure and controlled way for Agents to obtain a read-only snapshot of the Git workspace, making it a valuable complement to building robust agent workflows.