dsh-agent-swarm

Agent Swarm for DeepSeek Harness

English · 简体中文

One goal. A coordinated team. Work you can review.

Describe what you want to build, fix or investigate. Agent Swarm brings a team of collaborating agents into DeepSeek Harness, with shared objectives, visible activity, independent review and a clear path back to your project.

/agent-swarm Fix the duplicate search results. Preserve the API, add regression tests, and independently verify the change.

The primary agent inspects your project, organizes the work and chooses the team and resource budgets. You follow the mission in the sidebar and inspect the result when it is ready.

v0.7.0 · MIT · Local Git projects · Native Harness integration

Get started · See the UI · How it works · 中文介绍

Built for work that benefits from a team

You describe the outcome. The primary agent manages the collaboration. There is no required team-size form or token-budget setup before each mission. Members can exchange findings, ask questions, challenge evidence and hand off partial work within the mission's scope.

From your request to your project

1. Start with the project as it is. A private Git snapshot captures tracked changes and non-ignored new files before planning. You do not need to make a manual commit; your branch, index and working files stay in place during capture.
2. Let the team work together. The primary agent plans independently verifiable work and its real prerequisites. An eligible idle member can take a never-started task when its preferred member is busy; explicit bindings and active attempts stay protected. Members use native Harness sessions and separate Git worktrees.
3. Review the actual artifact. A different member reviews submitted work. Code and configuration changes require declared checks even when a task is labelled research. Harness runs them against the exact submitted commit. A report without checks is accepted on the reviewer's judgement, backed by at least one claim the reviewer publishes from its review, and every acceptance records the checks or the claims it rests on.
4. Bring the result back when ready. Once the mission completes, the sidebar offers View changes and Apply result for its accepted code deliverable. Application compares against the original snapshot and preserves your branch and index. It does not stage, commit or push for you.

Existing edits remain part of the baseline, so they are not presented as new swarm output. Detected merge conflicts are reported before applying changes.

Know what is happening

The sidebar answers three practical questions: Who is working? What just changed? What needs attention?

• Recognizable members. Host-assigned names and stable robot portraits make each member recognizable; responsibilities stay in a separate role field. Explicit custom names remain supported. Open a member's conversation to inspect its work.
• Visible execution. See the current operation, how long it has been running and how recently Harness observed it. Fresh activity drives the animation; stale signals are shown as unconfirmed.
• Progress backed by events. Tool results, submissions and acceptance events appear in the feed. Resource usage stays in details instead of masquerading as a completion percentage.
• Control close at hand. Pause, resume or stop a mission from the sidebar. Saved planning requests also expose recovery controls when startup fails.

The UI follows host state without making model requests to render updates. Operation activity is a liveness signal, not a guarantee that useful work has finished.

UI gallery

Captured on September 15, 2026 with simulated tasks and events. The surrounding page is a local preview shell, not the Harness application. Click an image to enlarge it.

Current plugin components — these screenshots render the actual ActivityPanel with simulated data.

Design previews — the shared avatars and live activity components are integrated into the plugin. The complete simplified layout below remains a renderer prototype.

Keep momentum through interruptions

A long task needs more than a launch button. Agent Swarm keeps assignments, evidence, decisions and recovery state on disk so the team can continue through supported interruption and restart paths.

Repair without losing the task's purpose. When an independent review rejects a task, the primary reworks it in place: swarm_control with action: "resume" re-opens the rejected task for its author, who stays pinned to it and resumes from the rejected commit, and re-opens the review that rejected it with the same reviewer, so the resubmission is reviewed at once without a new review task. A task can be reworked maxRework times (default 2; raise it in swarm_control changes); after that, a replacement proposed with replaces answers for every criterion of the task it replaces, the mission criteria it covers included, without copying them; downstream dependencies follow the accepted repair, and accepting it retires the whole chain it replaced. The rejected commit, the rejection reason and the claims of that round stay on the task and its review as archived history: they cannot be challenged again and never block completion. A challenge disputes only a claim a verdict can still judge: a claim the rejection refuted (before the rework too), one a verified claim superseded, one of cancelled work and a review's own evidence are refused with [evidence_not_judgeable], which names where the dispute can still go (a live claim to challenge instead, the primary's rework or replacement, or swarm_escalate to the primary), so such a dispute can no longer cancel the review that rejected a task or re-open accepted work. The primary can also revise execution allowances and unsubmitted task policy on the same task, repair a failed saved plan at a new revision, and strengthen submitted checks in place without changing the artifact.

Bring decisions back to the primary agent. Rejections, blocked work, provider problems and exhausted limits can generate durable notices. The primary agent can revise the plan, arrange a repair or adjust a budget with a recorded reason. Ordinary recovery decisions do not require you to configure the swarm again.

Completion keeps its meaning. Unfinished synthesis and review tasks stay on the board and bring the primary back to repair them. An empty runnable queue cannot silently cancel required work or mark the mission complete.

Keep resource use visible. The primary agent chooses team size, task limits, step and token budgets, recovery allowances and verification timeouts. Usage is tracked across the team, with cache and output breakdowns and the primary conversation's usage shown separately. Resuming does not reset consumption. If a native worker session must be recreated, a durable accounting generation keeps new usage separate from the old watermark while preserving lifetime totals.

Recovery runs within the mission's limits. Notifications remain queued while the primary agent is offline, and a stuck native model call may delay when it can process them. Provider-reported usage and estimates for requests still in flight can also allow a budget overshoot.

Architecture

The primary agent chooses the direction. The runtime coordinates the work. Harness runs the agents.

flowchart TD
    G["Your goal"] --> P["Primary agent · plan, team and budgets"]
    P -->|Plan and decisions| R["Swarm runtime · durable coordination"]
    R -->|Decision notices| P
    R -->|Ready assignments| W["Native workers · parallel collaboration"]
    W -->|Submitted artifact and evidence| V["Independent review + host checks"]
    V -->|Verdict or repair needed| R
    R -->|Accepted deliverable| D["Inspect changes · apply to your project"]

Freedom inside a clear contract. Workers share evidence and propose further work; the runtime checks scope, dependencies and review requirements. Peer messages cannot expand permissions, raise budgets or waive independent review.

Recovery is part of coordination. Durable state links each task to its attempt, artifact and decisions. When an attempt is interrupted, the runtime fences stale writes and uses the supported checkpoint, retry or reassignment path. Cases that need judgment return to the primary agent. Accepted replacements become the prerequisites for downstream work.

Native execution, one visible mission. Harness supplies model execution, sessions, the inbox, tools and sandboxing. The plugin owns mission coordination and verification policy; the sidebar projects mission state and observed activity. Collaboration messages use the native inbox and session log, while coordination records live in SQLite. No Harness core fork is required.

For the implementation contracts and their origins, see design notes.

Get started

Agent Swarm currently ships as a source plugin. You need:

• Node.js ^22.19.0 || >=24.0.0, Git, and macOS or Linux. Work happens in local Git repositories.
• A built DeepSeek Harness 0.2.1-rc.2 checkout. The plugin runs on exactly one release, 0.2.1-rc.2 (npm latest and next), at the commit in the exact compatibility matrix. Point DSH_HARNESS_ROOT (or DSH_SOURCE) at the checkout you mean. Without it the scripts take the first built checkout of that release among ~/.dsh/source/current and the sibling deepseek-harness-021rc2 directory, in that order; a checkout of any other release is skipped.
• A working model configuration in Harness. Credentials stay with the host. Workers inherit the primary conversation's model unless the plan selects another route. A launch checks every member's route first and refuses, rather than downgrades, a model this Harness release does not run or a reasoning effort the model does not take.

git clone https://github.com/TT-Wang/dsh-agent-swarm.git
cd dsh-agent-swarm
export DSH_HARNESS_ROOT="/absolute/path/to/deepseek-harness"
npm run link:dsh
npm run build
node "$DSH_HARNESS_ROOT/apps/cli/lib/bin.js" plugin --profile web add "link:$PWD"

Start Harness from the project you want to work on:

cd /absolute/path/to/your-project
node "$DSH_HARNESS_ROOT/apps/cli/lib/bin.js" --profile web

Open the authenticated launch URL printed by Harness, choose a model in a conversation, and enter /agent-swarm followed by your goal. The command appears in native autocomplete.

Agent Swarm lives in the native right sidebar. The sidebar starts collapsed; send /agent-swarm with your goal to open it automatically, or use the persistent Agent Swarm button at the bottom of the left navigation to open it again. The right sidebar belongs to one conversation: after opening a worker's conversation, open its read-only swarm view with the same button. The UI supports English, Chinese, light and dark themes.

For bundle installation, upgrades, startup recovery and configuration, see the operations guide.

The tests come in two tiers. In a fresh clone, npm ci && npm test runs the hermetic tier, which needs no Harness checkout: package-lock.json pins every package it uses, the 0.2.1-rc.2 Harness packages from npm included. A fresh clone has no node_modules above it, and the hermetic tier and npm run verify refuse a checkout that has one, since packages there would stand in for what npm ci did not install. The host tier and most other suites also need the built checkout, linked with npm run link:dsh after npm ci. npm run verify runs every suite of the gate manifest (the gate block of package.json) whose prerequisites the machine has, and records the others as skipped with the reason. The hosted CI runs it from a fresh clone on macOS, so CI covers only the suites that need no checkout, sandbox or browser; see development and verification.

Scope and practical limits

• Local execution. Distributed workers, non-Git projects and Windows execution are not supported. Separate hosts need separate state directories, which separate Harness homes give them by the plugin's one root rule; concurrent recovery of the same database is unsupported. Up to ba9a758, a root the composed plugin row did not configure stayed in ~/.dsh/agent-swarm whatever DSH_HOME or DSH_AGENT_SWARM_ROOT said: always on the direct mount, and on the bundle mount when a later layer replaced the row's config without both roots. Such an install that ran with another DSH_HOME or with DSH_AGENT_SWARM_ROOT set opens a new, empty store after the upgrade, and nothing on a stock profile says so; nothing adopts the old store, and the storage roots notes give the step that keeps it. Retained worktrees and artifact refs need explicit cleanup; verification checkouts a crash left behind are reclaimed by the mission's next verification that runs declared checks; a registration git left locked before recording its path must be removed by hand.
• Version pin enforced by the host's peer gate. The plugin's @deepseek-ai/dsh-* peer ranges name only 0.2.1-rc.2. The Harness plugin manager compares them with the running release and, when they exclude it, refuses to install the plugin and skips or disables a mounted one, unless its owner exempts that exact plugin version. 0.1.7-rc.1 introduced this gate, so it no longer runs this plugin unless exempted. Earlier releases have no such check: the plugin logs that the host is unsupported and is not expected to work there, so on them the supported release is a documented claim, not an enforced one. The plugin declares no engines.dsh, so the host reads the same ranges npm does; the profile bundle's requires.harness is declarative.
• A Harness home used with 0.1.x moves to 0.2.1-rc.2 once. 0.1.5-rc.3 and 0.1.7-rc.1 are no longer supported; a28b116 is the last plugin revision that runs on them. 0.2.1-rc.2 reads their session logs but writes session events they refuse: a single bash call can make a session unreadable to them. Back up $DSH_HOME/sessions and the plugin's state before the first start on 0.2.1-rc.2, and do not move a home with live missions back; going back also means going back to a plugin revision up to a28b116. See the move notes.
• File deliverables. Members list exact output paths in swarm_submit.deliverables (or optional swarm_verify.deliverables for a separate review report); the host can capture those files even when Git ignores them, without changing the source checkout's ignore rules. Submission returns commit-bound blob IDs and sizes. Reviewers use the pinned source commit and host checks run in a fresh checkout of it, so later author edits cannot change the reviewed report. Reassigned reviews retain saved drafts for the same source. A review that deferred or rejected passes on the record its verdict captured, and a reworked task given to another member starts from its rejected commit; nothing the previous member wrote after its verdict or submission is taken from its worktree, and that member is not stopped. Every task also declares outputs, the files it must produce; the host captures each declared output even when Git ignores it, refuses a submission whose declared output is missing with [output_missing], preserves declared drafts across a handoff, and refuses to launch a plan task that declares none ([] marks analysis-only work). Nothing is inferred from the task text: an ignored file that is neither declared nor listed is not captured. Unlisted ignored collisions stop the workspace switch and name the conflicting paths; arbitrary ignored files and secrets are not swept into snapshots.
• Reviewable evidence. Independent review and host checks make acceptance inspectable; they cannot guarantee that the chosen checks cover every requirement. Captured code and configuration changes need host checks even in a task labelled research, while known report formats remain exempt from code checks; file-format classification is not semantic program analysis. Literal no-op checks are refused, but independent reviewers still judge meaningful coverage. A source without checks is accepted only on the reviewer's judgement backed by the reviewer's published review evidence: at least one claim it published with swarm_publish on that review attempt. A recorded tool run alone, or a reading through swarm_observe (never a recorded run), is refused with [review_evidence_required], so the reviewer inspects the submitted commit in its review checkout. Every acceptance records its basis on task/accepted, its verdict rows, the accepting review and the artifact registry: checks with the host check runs, or review-evidence with the reviewer's claims; an acceptance recorded by an earlier build has none. The owner can add checks to a submitted artifact on its own task instead of cancelling and recreating it. Existing accepted history is not retroactively re-reviewed by an upgrade. Verification copies installed dependencies by default, including common virtualenv interpreters, but may still depend on host system libraries. Unsupported external dependency links require a self-contained installation or an explicit host opt-in; this is not a fresh CI environment.
• Rework in place. Only a task rejected by its own independent review can be reworked; a rejected experiment, or work invalidated after it was submitted, still needs a replacement. The author's steps and recovery credit carry across reworks, so a resume is refused with task_budget_exhausted until the allowance is raised; the re-opened review starts each round with a fresh allowance. A resubmission must change the commit or bring new host-backed claims, otherwise it is refused with [rework_unchanged]. The member a re-opened review is bound to can never take the rework; if it is the only live member left, the task waits until the primary adds a member or reassigns the review.
• Host-added reviews. A deliverable a plan does not pair gets one unassigned independent review at launch, at draft save, and when a draft saved by an older build is listed. Added reviews count against maxTasks. A review counts as a live review path only while a member that is not stopped may own it independently, so a plan whose only live members authored the deliverable wakes the owner with [review_path_missing] after submission. An added review copies no criteria: it checks what its deliverable must satisfy, and an override's acceptance adds review-only criteria. Omitted review override fields default to unassigned, the host's review objective, no extra criteria, the deliverable's maxRecoveryAttempts, and the default maxSteps.
• Acceptance criteria by id. A mission's acceptance items are criteria c1, c2, … in order, and a deliverable cites the ids it satisfies in covers; in a plan a review's covers move to its source, and swarm_propose refuses them on a review. A new deliverable needs covers or its own acceptance; a review and a repair need neither. A task stores only its own criteria: its worker and reviewers see those, the text of the criteria it covers, and everything the tasks it replaces answer for. The primary agent reads the stored task wherever a task is returned to it (the results of swarm_propose, swarm_control and swarm_cancel, swarm_observe, the panel's snapshot and swarm_registry): its own acceptance, its covers and its replaces, with each id resolved by the criteria a fresh swarm_observe overview lists; a worker never reads an id. Completion counts only the ids that accepted deliverables cite, their own and those of the tasks they replace; copied criterion text covers nothing. covers cannot be amended, so a deliverable accepted without them leaves its criteria to another deliverable that cites them. The draft editor lists the criteria as numbered rows, gives each deliverable a Covers box per criterion, and renumbers covers when a criterion is removed; only an automatic launch refuses a criterion no deliverable cites, so a draft launched from the editor with an unchecked criterion runs and cannot complete until another deliverable cites it. Criteria are fixed once a mission exists: a staged-draft repair must resend them unchanged. A store written by an earlier version is rewritten once, when it is opened: each existing task and draft plan task keeps only its own criteria (a repair drops what it inherited from the tasks it replaces, a review what its source already supplies), each deliverable cites by id the mission criteria whose text it had copied, and a staged mission takes the criteria of its saved draft, as its relaunch would have. A saved draft rewritten this way becomes a new revision, so an editor page left open across the upgrade reloads it and cannot save its older copy over the ids.
• Human-controlled workspace access. A mission uses the directory its session started in or a root configured in authorizedWorkspaces; a matched grant is recorded as workspaceGrantRoot. A later working_directory cd does not move it. Agents cannot grant themselves a new root through swarm tools. Confinement follows Harness's sandbox, and each worker starts every activation in its member worktree without the host tools that would move it or schedule a later turn (working_directory, create_worktree, schedule_*); the plugin adds no independent network or credential isolation.
• Observable, bounded recovery. The live UI shows operations and recorded events, not token-by-token output or a guaranteed ETA. Recovery does not promise exactly-once external side effects, arbitrary disk-fault recovery or filesystem-wide atomic application. A scheduling pass stuck in a slow worker call keeps its mission until that call returns at its own time limit; the owner is told once the pass passes its bound, and only while it is still stuck: once the pass has returned, a notice of it the owner has not read is withdrawn and not reminded.
• One notice per fact. The primary is told each fact once, keyed by what opened it (a task at its epoch