DeepSeek SuperAgent Architecture: How Its Open-Source Coding Agent Works
Updated November 2, 2026 · Research and documentation review
DeepSeek's SuperAgent prototype turns repository activity into ongoing coding work. Its most interesting design choices are not just about writing code: they are about deciding which events deserve action, preserving task context, and knowing when to hand control back to a person.
dsh-superagent is an MIT-licensed research prototype for one GitHub repository, built as a bundle for DeepSeek Harness. It routes authorized requests to separate worker sessions, follows conversations and pull requests, and records work across interruptions. It is not an official DeepSeek product or production-ready software; the public release differs from the team's internal implementation.A coding assistant can fix a bug in a single session. A team needs more: an issue arrives, a fix is reviewed, a check fails, and a comment appears the next day. Someone has to connect those events and decide what happens next. SuperAgent is an attempt to put that coordination into the agent system itself.
This article examines the public prototype and its documentation, then offers a practical framework for evaluating it. Examples are illustrative; we have not run a deployment or measured its performance for this article.
What exactly has DeepSeek open-sourced?
The public project, dsh-superagent-prototype, is a proactive coding agent that works on a single GitHub repository. GitHub provides a source of requests and activity; Feishu can be added as another source. The system can create a work item for an authorized request, execute it in a separate agent session and directory, and respond in the original conversation, including with a pull request.
The project describes itself as research code, not an official product. Its README says the published version is adapted from internal work and differs from both that implementation and the implementation described in its accompanying research. Some research ideas remain future directions. That distinction matters: an architectural idea in a paper is not automatically a feature in this release.
| Layer | Role |
|---|---|
| Model | Processes context and generates decisions or code. |
| DeepSeek Harness | Provides the agent environment, sessions and tools. |
| SuperAgent bundle | Coordinates incoming events, authorization, tasks, workers and delivery. |
| Operator and GitHub | Set access and rules; review and enforce repository controls. |
How does a request become a coding task?
The project's domain model separates the origin of an event from the work it may cause. A Source brings activity into the system. A Trigger represents something that happened. A Ticket represents a piece of work; its Mandate records the basis for taking it on. An Executor works on the ticket in its own session.
The router's job is to decide whether a candidate should start new work, attach to existing work, be ignored, or stop work when appropriate. A worker's job is to carry out an accepted task and report its state. Keeping those jobs distinct allows the system to receive new activity while an implementation task continues.
Example: an issue followed by a review comment
Suppose an allowed teammate mentions the agent in a GitHub issue and asks it to investigate a failing test. The agent accepts the request, prepares a ticket directory and investigates. If it opens a pull request, later discussion can reach the ticket handling that work. An in-scope human follow-up can be handled by the existing executor; a request outside its scope can be handed back for routing. This example illustrates the documented model, not a promise that every fix will succeed.
Who can authorize the agent to act?
The authorization design distinguishes an explicit request from an inferred candidate. An allowed person addressing the agent can create an explicit request. Other activity, such as certain unaddressed messages or messages from listed bots, may become an inferred candidate depending on the source policy. Inferred work needs an assessment against enabled team rules before it can be accepted.
| Accept mode | What happens to inferred work |
|---|---|
off | Inferred activity does not become a candidate. |
observe | Eligible candidates are assessed; a positive decision is recorded as “would accept,” but no inferred work starts. |
auto | A positively assessed candidate can be accepted when an enabled rule matches. |
Explicit requests work in all three modes. The project's recommended starting point is observe, so operators can inspect decisions before enabling proactive acceptance. This is useful for finding noisy rules: a trigger may be technically valid while still wasting a team's attention.
Messages delivered to a subscribed ticket supply context; they do not automatically grant new authority. The host's policy, allowlists and mandate govern authorization, while issue text, comments and quoted documents remain inputs to a decision. A policy change also does not instantly revoke every active mandate; the documentation describes notices and revalidation before certain resumptions. These details are worth reading before assuming that changing a setting immediately stops all existing work.
What happens inside a worker session?
Each ticket gets an executor session and a directory under a configured execution root. A preparation command can create a Git worktree; if no preparation command is configured, the worker starts in an empty directory. A failed preparation is recorded as a failed ticket. See the execution guide for the full lifecycle.
Workers occupy configured concurrency slots while launching or actively working. The design allows one extra slot for a person's message or a status request when normal capacity is full. Other inputs, including CI results, wait for normal capacity. The practical aim is to keep a busy queue from preventing a person from continuing an existing task.
The panel distinguishes work that is queued, working, waiting, awaiting review, blocked or failed. That distinction is useful: an agent that has stopped because it needs a decision should not look identical to one still running a test.
How does SuperAgent handle interruption and recovery?
Long-running agent work needs a plan for things going wrong. The prototype records work before performing actions such as launching an assignment or delivering input. Failed deliveries are retried with backoff; transient provider or network errors receive limited retries. A blocked or failed ticket stops taking automatic input until a person intervenes, a qualifying report arrives, or an operator retries it.
After a host restart, interrupted assignments restart with a recovery note telling the executor to inspect its directory, Git history and GitHub before repeating external actions. Sessions, directories, subscriptions and pending messages are among the state the documentation says survive restart. Retrying a ticket creates a new assignment in the same executor session, directory, branch and pull request.
These mechanisms reduce the chance of losing track of work. They do not make external side effects inherently safe or guarantee exactly-once behavior in every failure scenario. Operators should inspect what actually happened before rerunning an action that could send a message, modify data or trigger a deployment.
What does it take to try the prototype?
The repository provides an agent-assisted setup guide as well as manual deployment instructions. The setup guide lists Node.js 22.19+ or 24+, pnpm, Git 2.32+, tmux, Python 3.8+, GitHub CLI 2.48+, a compatible DeepSeek Harness version and a configured model provider. Check the current files for version changes and platform requirements.
The guide recommends a dedicated GitHub account for the agent, an initially short allowlist, observe mode and human merging. It also describes a separate Harness profile and a prepare command for per-ticket checkouts. Feishu is optional. Review every setup step and credential permission yourself; the article's checklist is not a substitute for the project's deployment instructions.
A first experiment we would run
- Use a disposable or low-risk repository without sensitive data, and give a dedicated agent account only the access the test requires.
- Keep proactive acceptance in
observe; choose one authorized operator and require people to merge changes. - Ask for one bounded task, such as diagnosing a reproducible test failure, with clear acceptance criteria and no deployment.
- Inspect the ticket's routing decision, proposed diff, actual test output, messages and model usage. Record failures as well as successes.
- Review the observed proactive decisions before adding a rule or increasing permissions.
These steps are editorial recommendations, not results from a live test. Choose actual execution isolation and network controls appropriate for your environment; the prototype's directories alone do not supply them.
Can it merge its own pull requests?
The setup guide recommends that people merge until the agent's pull requests have been consistently correct. The execution documentation describes optional auto-merge instructions with conditions, including required approvals, but makes an important distinction: those instructions govern the agent, while GitHub branch protection enforces repository rules. The host has no separate merge-specific decision logic. If approvals are required, enforce them in GitHub and consider dismissing stale approvals. For a manual-only trial, follow the setup instructions to remove the auto-merge paragraph.
How should a team evaluate whether it helps?
Measure the work around a patch, not just the time until a pull request appears. Compare a small set of similar tasks with your usual process and retain unsuccessful or abandoned runs.
| Measure | Question |
|---|---|
| Routing quality | Did it start the right work and attach follow-ups to the right ticket? |
| Reviewable output | Did the diff address the request, with relevant evidence and checks? |
| Human attention | How much time went into clarifications, review and cleanup? |
| Operational behavior | How did it handle failures, permission boundaries, messages and restarts? |
| Cost | What model and infrastructure usage did each accepted task consume? |
A quick pull request that takes hours to correct is not necessarily a productivity gain. Likewise, an agent that correctly stays quiet can be more useful than one that opens a ticket for every event. Record task difficulty and sample size before drawing conclusions.
What are the limits of the public release?
It targets one repository, depends on its surrounding Harness and integrations, and is explicitly described as research software. Its maintainers warn of bugs and inconsistent engineering practices. Some research concepts are not implemented in the public code. We have not found a basis in the project's documentation for a general productivity percentage or an assurance that it can independently manage a production repository.
The architectural contribution is more specific: the project makes task ownership, authorization, continuity and human attention visible as engineering problems. Teams can study those choices even if they decide not to deploy this particular prototype.
Frequently asked questions
Is DeepSeek SuperAgent a new model?
No. The published project is an agent-system prototype packaged for DeepSeek Harness. It needs a configured model provider; the model and the orchestration system are separate layers.
Is SuperAgent open source?
Yes. The public repository is MIT-licensed. The published code is adapted from the team's internal implementation and is not identical to it.
Does observe mode stop all work?
No. It prevents inferred candidates from being accepted as proactive work while recording positive assessments; explicit requests can still be accepted.
Can SuperAgent work across many repositories?
The public README describes the prototype as a coding agent for one GitHub repository. Do not assume broader multi-repository orchestration is included.
Is a separate worktree enough to secure it?
No. The project's execution guide says the directories and command wrappers are not a security boundary. Workers run commands as the operator's operating-system user, so isolation and permissions need separate attention.
See available plans and current terms on our pricing page.
View pricing →