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

Your goal	How the team helps
Fix a difficult bug	Investigate the cause, implement a repair and have another member check the edge cases.
Deliver a feature across several parts of a project	Split independent work, coordinate dependencies and assemble a reviewed result.
Understand unfamiliar code	Gather evidence, compare findings and produce an analysis without changing the code when requested.

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; ordinary reports retain lightweight independent review.
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.

Live worker activity · light theme	Accepted results and delivery · dark theme
Follow current operations, elapsed time and recent tool events.	See the accepted result and choose when to bring it into your project.

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

Simplified sidebar layout · preview	Independent verification in progress · dark preview
Keep the goal, parallel work and task controls together.	Echo is checking another member's submission; that submission still awaits acceptance.

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. 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, supported DeepSeek Harness checkout. Exactly two releases are supported: 0.1.5-rc.3 (npm latest, the default host) and 0.1.7-rc.1 (npm next), each 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, supported checkout among ~/.dsh/source/current and the sibling deepseek-harness-015rc3 and deepseek-harness-017rc1 directories; 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.

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.

On both supported hosts 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.

Scope and practical limits

• Local execution. Distributed workers, non-Git projects and Windows execution are not supported. Separate hosts need separate state directories; concurrent recovery of the same database is unsupported. 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 only by 0.1.7. Of the releases checked, only 0.1.7-rc.1 compares the plugin's pinned @deepseek-ai/dsh-* peer ranges with the running release and disables the plugin when they exclude it. 0.1.5-rc.3 has no such check, so nothing stops the plugin loading on another 0.1.5 or 0.1.6 release: there the two-release support is a documented claim, not an enforced one. The profile bundle's requires.harness is declarative on both hosts.
• 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. 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 its session workspace or a root configured in authorizedWorkspaces; a matched grant is recorded as workspaceGrantRoot. Agents cannot grant themselves a new root through swarm tools. Confinement follows Harness's sandbox; 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, a review need, a limit value, a violation, the event that recorded it), never by a snapshot of the whole board. A condition that ends and returns with the same opener is not announced again: its earlier notice is outstanding again, and only that notice's remaining reminders (at most two) bring it back. Stuck work is always named: the stall notices, the mission stall, the dispatch question and the notice that names work no live path advances are each sent whenever their own condition holds, even when a decision already names the same work. The one older exception is a task's stall notice when that task's rejection at the same epoch already told the primary and nothing else waits on it. A submission without a live review keeps the mission from being reported stalled only while the runtime's own review step can still admit a review for it (within a short grace, or while nothing blocks one), and the dispatch question asks about every ready task that did not dispatch, once per epoch, beside the other notices, which still name the rest of the board. One condition can therefore reach the primary as several facts in different words, which is the open item R20: a failed dispatch or an isolation request beside the dispatch question; a start failure or retirement beside the dispatch question and the stall notices; a revoked workspace's request (which names the work it blocked) beside a stall notice for each blocked task and the mission stall; a ceiling or recovery request beside the stall notice of the task it blocked; a blocked review beside the mission stall, and a second mission stall when a withdrawn review changes what is stuck. One wording per condition needs every decision a notice could defer to to stay open exactly while its own cause holds: several causes (a recovery limit, a ceiling, a failed close-out, a revoked workspace, a preparation failure, a rejection) have no durable record of their own to bind that to yet, a request about a member names all of that member's unfinished work, and a deferred notice would have to speak again once what it deferred to closes. Until then no notice stands down for another, so stuck work is never left unnamed. In a burst the later facts ride a wake summary, which names each task and points to swarm_observe with its deliveryId for the full fact and its exits. After upgrading from an earlier build, a condition that is still open, or that fires again, is announced once more under its new key.
• Code structure. src/runtime.ts is still one class of about 3,900 lines. The seven seams it builds (refusals, notices, attempts, workspace admission, declared checks, gates, scheduling) stand on its kernel and the seams below them, and none imports the runtime, not even for a type; the src import graph has no cycle, even counting type-only imports. The workspace engine, notices, types and tools are not split (known limitations).

Details and residual risks are documented in known limitations. Integration evidence is recorded in validation; scripted-provider tests are not model-quality or speed benchmarks.

Documentation and ecosystem

Read more	What you will find
Operations guide · 中文指南	Installation, supported hosts, storage, configuration, recovery and development commands.
Design notes	Collaboration contracts, authority boundaries and design traceability.
Validation	Completed integration checks and the limits of their evidence.
Known limitations	Detailed operating constraints and remaining issues.

Agent Swarm can be paired with dsh-slice-agent-loop for session context management: Swarm coordinates work across members, while the slice policy manages history within each session. See the integration notes.

Contributions are welcome. Development verification requires the repository checkout; start with the development commands. Live-provider checks are opt-in and may incur API charges.

License

MIT · License · Third-party notices