Introduction

Commands submitted to DeepSeek Harness (DSH) run by default under the DSH process. When executing long-running tasks such as compilation or data export, closing the DSH process interrupts the task. The dsh-bgjobs plugin uses the Windows Task Scheduler to host background jobs, allowing tasks to run independently outside the DSH process and providing real-time monitoring and management capabilities.

Core Features

  • Independent execution outside the process: Tasks are hosted via schtasks; DSH crashes or shutdown do not affect execution.
  • Real-time output panel: A floating panel in the bottom-right corner of the web page refreshes output in real time, supporting dragging, minimizing, and grouping by workspace.
  • Clean up finished jobs: Supports dragging to delete a single finished job, or batch cleanup (over 24h / all).
  • Completion notification: After a job exits, a Toast is displayed, with support for sending results back to the creating Agent.
  • In-session waiting: Use bgjob_wait to let the Agent wait for results without blocking the conversation. Supports any race semantics (first to finish returns first) and all conjunctive semantics (returns immediately if any job fails).
  • Reconnection continuation: After DSH restarts, tracking is automatically restored, and old task IDs can still query status from disk.
  • Offline management: Task management does not depend on DSH CLI or GUI.
  • Optional sandbox: bgjob_submit_pwsh supports optional sandbox constraints on background job file permissions.
  • MCP invocation hosting: Submit MCP tool calls as background jobs, supporting three states: warm-up / cold start / disabled.
  • Zero residue: Finished tasks automatically delete their scheduled task; done tasks are retained for display by default.

Installation and Activation

Prerequisites: DSH (@deepseek-ai/dsh), PowerShell 7, and Node.js (^22.19.0 or >=24) must be installed, and the system must be Windows.

$pf="web"; dsh plugin --profile $pf add github:bitsmug/dsh-bgjobs || dsh plugin --profile $pf approve-builds koffi; dsh plugin --profile $pf add github:bitsmug/bgjobs && Write-Host "✓ bgjobs安装成功！" -ForegroundColor Green

If you encounter the ERR_PNPM_IGNORED_BUILDS error during installation (dependency on the native library koffi), run this first:

dsh plugin --profile $pf approve-builds koffi

The change takes effect after restarting DSH; the Agent will then have background job management tools.

Usage

The plugin provides the following Agent tools:

  • bgjob_submit(name, command, workdir, [wait], [notify], [notify_mode])
    Submit a background job. command uses bat syntax. The wait parameter controls the number of seconds to wait in place after submission.

  • bgjob_submit_pwsh(name, command, workdir, [wait], [sandbox], [justification], [notify], [notify_mode])
    Submit a background job. command uses PowerShell syntax (supports UTF-8 logs and safe exit codes). sandbox is an optional sandbox configuration.

  • bgjob_submit_mcp(name, workdir, tool, [arguments], server | server_config, [timeout_seconds], [wait], [notify], [notify_mode])
    Submit an MCP tool call as a background job. You must first enable the “MCP Jobs” switch on the settings page.

  • bgjob_mcp_tools(server | server_config, [refresh])
    List the tools registered by the MCP server, useful for confirming tool names and parameter shapes.

  • bgjob_status(jobId)
    Query job status, exit code, and the tail of the logs. Do not continuously poll; use bgjob_wait instead.

  • bgjob_wait(jobId | jobIds, [timeoutSeconds], [logic])
    Wait for jobs to finish and return results. The logic parameter supports any (first to finish, default) or all (all succeed).

  • bgjob_list
    List all jobs submitted in the current session.

Log path: <workdir>\.dsh\bgjobs\<jobId>\stdout.log. The exit code is written to <workdir>\.dsh\bgjobs\<jobId>\exitcode.txt.

Exit code definitions: 0=success, 1=tool error, 2=connection or invocation failure, 3=timeout.

Typical usage example:
Put the long chain “clone the Linux kernel source code to D:\work\linux, then compile with make -j16” to run in the background, and notify me on completion (notify: on-exit).

Notes

  • MCP dependency: The MCP engine depends on @modelcontextprotocol/sdk and yaml, shipped with the package.
  • Build scripts: Installation depends on koffi; if you encounter an error due to ignored build scripts, run approve-builds koffi.
  • Sandbox security: Sandbox security has not been fully validated.
  • Resource management: After a job completes, the scheduled task is automatically deleted by default, but log files remain on disk.

Summary

dsh-bgjobs solves the instability issue of long-running jobs in DSH. By hosting jobs with the Windows Task Scheduler, it ensures continuity and controllability of tasks, while providing robust monitoring, waiting, and notification mechanisms, suitable for scenarios such as compilation, downloads, and batch processing.

Documentation and Source Code:
GitHub | Plugin Directory