Preface¶

When running long tasks in DeepSeek Harness (dsh), the common gap is not “whether you can throw it to the background”, but whether you can continue chatting with it after throwing it out. The built-in background jobs are mostly fire-and-forget: you can see the output and kill the process, but it is difficult to add a follow-up message like “first check the snapshot test” in the same conversation, and it is also difficult to open a sub-session in the Web sidebar. Scheduling plugins are responsible for “when to start”, and status bar plugins are responsible for “displaying progress”. What is really missing is interactive control over a resumable sub-conversation.

dsh-background-agents connects this to the official sub-agent seams: start a continuously working sub-agent, view progress in the sidebar, send messages for guidance at any time, request interruption when necessary, without switching away from the parent conversation. After v0.5.0, a persistent multi-agent team room feature was added, with the message bus and task board using Harness’s own storage, which can be restored after restarting.

The official positioning of DeepSeek Harness is “everything is a plugin”. The community site DeepSeek Harness Plugin Repository collects a number of extensions. It is an independently operated directory and has no affiliation, endorsement or sponsorship relationship with DeepSeek / HyperGAN. This article is collated after cross-checking the directory details page, GitHub README / package.json / cordis.patch.yml, npm release page, and DeepSeek Harness official repository.

What is this¶

dsh-background-agents is a conversation and message plugin maintained by PerryLink, licensed under Apache-2.0, mainly written in JavaScript. Its positioning on the directory page is: providing interactive long-running background agent for DSH – you can start a continuously working sub-agent, view progress in the Web sidebar, send messages for guidance at any time, interrupt when necessary, without leaving the current conversation throughout the process.

The repository README is more specific: it upgrades fire-and-forget background jobs into resumable sub-conversations, and adds progress injection, idle archiving and sidebar panels on the same control surface. The npm package name is also dsh-background-agents, and the current released version is 0.5.1 (2026-08-17). The compatibility statement is DeepSeek Harness 0.1.0-rc.6, with the peer range being >=0.1.0-rc.5 <0.2.0; Node requirement is ^22.19.0 || >=24.0.0. As of 2026-08-18, both the directory page and GitHub show 5 stars. The repository was added to the directory on 2026-08-15.

The maintainer drew a boundary between this plugin and several other community plugins in the README:
- titanwings/dsh-automation is responsible for scheduled new session startup, and this plugin has no cron function;
- vlln/dsh-task-status displays tool-level jobs, and this plugin creates and controls agent conversations;
- YYTbit/dsh-plugin-agent-dashboard focuses on display, while this plugin allows jumping into sub-conversations, sending messages and requesting stops.

Core Features¶

Five Control Tools¶

The plugin provides five tools based on the official sub-agent seams (startContinuable / followup / interrupt / listChildren), and does not perform its own lifecycle routing or kill the process tree:

background_agent: Start a resumable sub-agent. Optional parameters include label, tool_filter, persona, max_depth, and childProvider / childModel to override the model routing of the sub-agent. tool_filter only removes tools from the sub-agent’s视野 and does not grant new tools.
bg_message: Deliver follow-up rounds by agent id.
bg_list: List the status of background agents in this session; when recursive: true, it will bring parentId / depth to view the descendant tree. It will return a clear unrecoverable mark when the directory is unavailable, and will not fabricate an empty list.
bg_result: Read the latest assistant output of the sub-agent. It will mark textSource: 'reasoning' when falling back to reasoning content; ultra-long text will be truncated according to resultMaxChars (default 4000) and marked truncated.
bg_stop: Request interruption of the current round. Stopping equals request interruption, and cleanup work belongs to the continuation manager.

One-shot sub-agents will not appear in bg_list and cannot be delivered by bg_message. Sub-agents inherit the parent session’s model routing by default.

Progress Injection and Idle Archiving¶

autoReport is enabled by default: after each sub-agent round ends, a throttled progress line will be injected into the parent session, with the standardized prefix [background-agent] …. reportDelivery defaults to quiet, which appends this line to the next model request; when set to wakeup, the parent session will start a new round when idle. The minimum interval between two injections from the same sub-agent is controlled by reportThrottleMs, which defaults to 15000 milliseconds.

Idle cleanup is enabled by default (autoArchive: true). Sub-agents that have been quiet for more than idleTimeoutMinutes (default 120 minutes) will be archived, and can be woken up later with bg_message. If autoArchive: false, quiet monitors will pause their residency, and the cleaner will not archive them. The hard upper limit of unarchived background agents per parent session is maxBackgroundAgents, which defaults to 4; this budget is shared with resumable direct sub-agents started by the built-in subagent.

Progress and status do not rely on a separate database. Structured facts are written into the background-agents/fact event of the parent session log (with ignorable: true), and the dashboard and bg_list are rebuilt from the log every time they are opened.

The backgroundAgents session projection folds the parent log into a dashboard row. The Web sidebar panel can view real-time status, jump into sub-conversations, send messages, request stops, and preview results. This part relies on Web client injection (declared in package.json as @deepseek-ai/dsh-client-ui-sidebar, etc.), and the tools themselves can also be used on headless profiles.

Team Rooms (v0.5.0+)¶

The /room command family plus eight room_* tools provide persistent multi-agent rooms: each member is an independent session, with directed/broadcast message bus, shared task board and shared timeline. Data is stored in the team_rooms storage domain, with SQLite or JSONL as the backend, and no additional services are started. Cross-member task handover follows the official approval seam: room_transfer_task will fail and close when there is no answerer authorization.

Team rooms depend on @deepseek-ai/dsh-storage-domain. When there is no storage domain, /room and room_* will be disabled, and the five bg_* tools can still be loaded. The bundle patch will insert storage / storage-json / storage-domain lines; it is safe to override by id on web profiles that already combine these lines, and these lines will fail to load on builds without storage packages, leaving the room half dormant.

The room upper limits can be modified in the configuration, with the default values of maxRooms 16, maxMembersPerRoom 8, and maxRoomsPerMember 4. A single room message exceeding maxMessageChars (default 4000) will be rejected and will not be truncated.

Relationship with Built-in Sub-agent Tools¶

The Harness core already has subagent, send_message, interrupt_agent and the client-side report. The bg_* tools of this plugin are their session-level companions and can be mounted together:
- background_agent and subagent (backgroundMode: 'continuable') use the same startContinuable seam, and additionally perform per-child tool_filter / persona / max_depth verification and per-session upper limit control.
- bg_message / bg_stop have the same semantics as send_message / interrupt_agent, while also maintaining projected facts.
- The built-in report is called by the sub-model itself; this plugin automatically injects throttled progress after each sub-round.

The core tools do not have bg_list, bg_result, idle archiving, and parent-session-folded panels. This plugin also does not perform scheduled triggers, cross-machine/remote agent operations, or modify the official sub-agent activation contract. The provider must point to a provider with prepareContinuable; background_agent will fail continuously if it is missing.

Installation and Activation¶

The installation command given on the community directory page is as follows, which can be run in the DeepSeek Harness terminal:

dsh plugin add github:PerryLink/dsh-background-agents

For reproducible installation, the directory page recommends appending the commit hash to the repository:

dsh plugin add github:PerryLink/dsh-background-agents#commit

Replace #commit with the actual commit hash. As of 2026-08-18, the latest commit on main is 4bcab91f764dc30994119857824e61bb3515f90e, corresponding to the release tag v0.5.1. The plugin runs with the permissions of the current dsh process, and may execute code during installation. You should check the source code repository and license before installation.

The repository README also provides git/npm channels for specifying profiles. The repository has submitted the build artifact lib/, so git installation does not require prepare or allowBuilds. The bundle patch will write the line id: background-agents and set the required item provider to spawn:

# Git channel (tracking main)
dsh plugin --profile web add "github:PerryLink/dsh-background-agents#main"

# Fixed release tag
dsh plugin --profile web add "github:PerryLink/dsh-background-agents#v0.5.1"

# npm channel (released version, currently 0.5.1)
dsh plugin --profile web add dsh-background-agents

Verify the configuration line after restarting:

dsh --profile web --dump-config | grep -A4 'id: background-agents'

The plugin requires the sub-agent spine to be mounted; the README states that any profile based on @deepseek-ai/dsh-base has this. Adjustable items are all Schemastery Config fields, modify cordis.yml or profile overrides, do not modify the source code. Only provider is required, and other items such as autoReport, idleTimeoutMinutes, maxBackgroundAgents, and room upper limits have default values.

Uninstallation:

dsh plugin --profile web remove dsh-background-agents

You can also delete the line from the profile patch.

Typical Usage¶

After installing and confirming that id: background-agents appears in the dump-config, you can directly ask the model to call the tools in any conversation, or follow the example in the README to manually go through the process:

background_agent "watch the repo for test failures and keep me posted" (label: test-watch)
bg_list
bg_message <agentId> "also check the snapshot tests now"
bg_stop <agentId>

The operation sequence can be understood as follows:
1. Use background_agent to start the sub-agent and obtain a stable agent id. Pass in tool_filter when you need to restrict the sub-agent’s tools; the name will be verified against allowedChildTools in the configuration, and an empty or unset value means no additional restrictions.
2. Use bg_list to check the status. The same projection in the Web sidebar can also jump to the sub-session and preview bg_result.
3. When the task direction changes, use bg_message to deliver follow-up rounds without starting a new sub-agent.
4. Use bg_stop when you need to stop the current round. This is an interrupt request, not a process kill.
5. If the storage domain is enabled, use /room create|join|send|tasks and room_post, room_create_task, room_claim_task, room_transfer_task for cross-session collaboration.

The repository also includes an end-to-end demo that does not require an API key, using a scripted LLM to drive the parent session and background sub-agents. The dev/ directory is gitignored, adjust the path according to your local checkout, here is the PowerShell example:

$env:DSH_HOME = 'D:/deepseek-harness/Project/Plugins/dsh-background-agents/dev/dsh-home'
pnpm dsh --profile headless --patch dev/cordis.yml "【Parent Session】Background Agent Demo"

Applicable Scenarios and Notes¶

It is suitable for developers who are already running DeepSeek Harness locally and need to “continue the conversation while letting the sub-agent monitor the repository/run long tasks”. The Web profile can also use the sidebar panel for operations; headless mode mainly uses the five bg_* tools. Enable the team room feature when you need multi-session division of labor and shared task boards. It is not suitable as a scheduled task system, and cannot dispatch sub-agents to another machine.

It is recommended to accept these restrictions before use:
- The plugin has the same permissions as the current dsh process. The permissions declared in the workshop manifest are session:append, subagent:spawn, tools:register. Check the GitHub source code and Apache-2.0 license before installation; for reproducible installation, fix the commit or tags such as v0.5.1.
- The sub-agent is a resumable session within this deployment process. Progress facts are written in the parent session log; team room data is written in the team_rooms storage domain. There is no independent database, and no network requests are sent externally.
- tool_filter will only remove tools, not add new ones. bg_stop does not kill the process tree.
- Without @deepseek-ai/dsh-storage-domain, room-related commands and tools will be unavailable, but the five bg_* tools will still work.
- maxBackgroundAgents counts every resumable direct sub-agent in this session, including those started by the built-in subagent.
- The community plugin directory is not an official app store. The compatibility statement is pinned to the peer range of 0.1.0-rc.6, and you should re-verify after upgrading Harness.

Summary¶

dsh-background-agents complements DSH’s background capabilities from “throwing jobs” to “resumable sub-conversations”: the five bg_* tools follow the official sub-agent seams, and the sidebar can view progress, send messages and request interrupts; starting from v0.5.0, team rooms can be used for cross-session collaboration. It is not responsible for scheduled triggers, nor does it dispatch agents to remote machines.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-background-agents/

GitHub: https://github.com/PerryLink/dsh-background-agents

npm: https://www.npmjs.com/package/dsh-background-agents

Add Interactive Long-Session Background Agents to DeepSeek Harness with dsh-background-agents