1. Project Overview
dsh-superagent-prototype is an open-source TypeScript coding-agent prototype that turns authorized requests for a single GitHub repository into tracked work, executes each task in a dedicated DeepSeek Harness session and directory, and returns results to the original conversation. Repository README
2. Background & Positioning
The project grew out of the DeepSeek Harness team's everyday development work. Its mission is to deliver useful engineering results while minimizing the attention required from teammates. Work begins through explicit requests or written team rules, and communication focuses on actionable questions and usable results. Design philosophy
Its distinguishing emphasis is persistent team workflow: requests, authorization, execution, follow-ups, and delivery are modeled together around one repository. This makes it relevant to developers exploring repository agents beyond an interactive coding session, although the project does not publish comparative performance benchmarks. Domain model
The maintainers explicitly describe it as research code, rather than an official DeepSeek product or production-ready service. The public prototype differs from the internal implementation and the accompanying research article; some ideas discussed in that article remain future directions. Project status
3. Feature Categories
The counts below describe the specific features or resources listed in each category, rather than an official total capability count.
Collaboration and Event Intake
๐ Repository and Chat Inputs โ 4 representative features
- GitHub notification intake for the configured repository.
- Optional Feishu/Lark bot integration.
- Thread subscriptions that deliver follow-up context to existing work.
- Channel-based replies to the conversation associated with a request.
Purpose: connect team conversations to executable work while preserving the context needed to continue it. Domain model
Authorization and Proactive Work
๐ก๏ธ Policy Controls โ 5 representative features
- Allowed-sender lists for each Source.
- Admission tables based on scope, sender membership, and whether the agent is addressed.
- Written rules for inferred proactive requests.
- Three acceptance modes: off, observe, and auto.
- Ticket Mandates that record the authority under which work was accepted.
Purpose: distinguish permission to start work from messages that merely provide context. Authorization guide
Task Execution
โ๏ธ Execution Lifecycle โ 4 representative features
- A dedicated executor session for each Ticket.
- A configurable preparation command for task directories, including Git worktrees.
- Worker concurrency and model configuration.
- Recovery of interrupted assignments and retry handling.
Purpose: keep work items independently traceable and manageable across execution turns and restarts. Execution guide
Human Supervision
๐ Operator Panel โ 6 tabs, with 5 representative examples
- Overview highlights work requiring human attention.
- Source shows integration health and delivery problems.
- Trigger presents threads, incoming events, and subscriptions.
- Eval records decisions, reasons, and matched rules.
- Execution exposes Ticket state, worker activity, and intervention controls.
Purpose: make outstanding decisions and workflow history visible; the sixth tab, Settings, configures sources, evaluation, execution, prompts, and deployment. Panel guide
Customization and Extension
๐งฉ Extension Resources โ 4 representative resources
- Editable team prompt sections.
- Bundled GitHub and Feishu skills.
- An example DeepSeek Harness profile configuration.
- A cookbook for implementing an additional Source plugin.
Purpose: let teams adapt instructions and event integrations to their own repository workflow. Prompt guide, Source cookbook
4. Key Highlights
- Observe before enabling proactive execution. The default observe mode records whether inferred work would be accepted without creating the work, giving operators a way to assess their rules first. Authorization
- Traceable work from request to result. Triggers, decisions, Tickets, and assignments provide a shared vocabulary for understanding what the agent accepted and how it progressed. Domain model
- Separate execution contexts. Each Ticket has its own session and working directory; Git worktrees can supply independent repository checkouts. These are workflow boundaries, not OS security sandboxes. Execution, Deployment
- Attention-focused supervision. The panel prioritizes blocked work and actionable problems, with detailed history available when needed. Panel
- Extensible event sources. The cookbook explains event translation, reply delivery, authorization integration, and Source lifecycle behavior. Cookbook
5. Use Cases by Role
The following are potential applications of the documented workflow, rather than claims of specialized built-in functionality.
| Role | Practical use |
|---|---|
| General developers | Delegate scoped bug fixes or feature work from a repository conversation and review the resulting changes or pull request. |
| DevOps/SRE | Operate the dedicated agent profile, monitor health, and experiment with rule-authorized responses to repository CI events. |
| Security engineers | Review sender permissions, execution credentials, and runtime isolation; assign scoped remediation work through normal repository requests. |
| Data/research scientists | Study event routing, policy evaluation, and task recovery, or delegate code changes in a research repository. |
| Project managers | Review Tickets awaiting decisions, clarify requested outcomes, and follow work through the supervision panel. |
The underlying mechanisms are documented in the domain model, panel guide, and deployment guide.
6. Getting Started
Path 1: Find What You Need
Start with the README, then read the nine numbered documents in order, from philosophy through the Source cookbook. Use Architecture to navigate the implementation and Deployment for operational details.
Path 2: Install and Integrate
The recommended starting point is the agent-assisted SETUP.md. Give your coding agent this instruction:
Read SETUP.md in this repository and set up dsh-superagent with me.
Prerequisites include Node.js 22.19+ on the 22.x line or Node.js 24+, pnpm, Git 2.32+, Python 3.8+, tmux, GitHub CLI 2.48+, a repository on github.com, and a model provider configured in DeepSeek Harness. Feishu additionally requires its bot setup and lark-cli.
For a new installation with no existing superagent profile, the deployment guide provides this sequence, with the repository URL filled in:
npm install -g @deepseek-ai/[email protected]
git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git dsh-superagent
cd dsh-superagent
pnpm install
pnpm build
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"
The profile-creation command replaces an existing profile, so do not reuse it for upgrades. Before starting, follow the remaining deployment steps: configure a dedicated agent GitHub account and CLI credentials, fill in the example profile configuration, and configure Sources, Policy, Execution, and team prompts. The installation commands alone do not complete setup.
Path 3: Contribute
Read the architecture guide before changing behavior. For an integration, follow the Source extension cookbook, including its documentation and test requirements.
From your development checkout, run the repository's combined typecheck, tests, and build:
pnpm check
The reviewed tree does not include a standalone CONTRIBUTING.md. Use the documented development workflow and GitHub's pull request interface for proposed changes.
7. Project Structure
dsh-superagent-prototype/
โโโ README.md # Overview and documentation index
โโโ SETUP.md # Agent-assisted setup workflow
โโโ LICENSE # MIT license
โโโ docs/ # Nine ordered design and operation documents
โโโ examples/
โ โโโ profile.cordis.patch.yml
โโโ prompts/ # Agent instructions and team sections
โโโ skills/ # GitHub and Feishu skills
โโโ locale/ # English and Chinese interface resources
โโโ scripts/
โ โโโ dsh-superagent # Service lifecycle helper
โโโ src/
โ โโโ index.ts # Bundle entry point
โ โโโ core/ # Domain engine and lifecycle rules
โ โโโ app/ # Runtime, storage, API, and orchestration
โ โโโ executor/ # Harness execution adapter
โ โโโ sources/ # GitHub, Feishu, and Source infrastructure
โ โโโ client/ # Web supervision interface
โโโ tests/ # Domain, integration, and interface tests
โโโ cordis.patch.yml # Bundle plugin configuration
โโโ package.json # Dependencies, compatibility, and scripts
The architecture separates domain rules from execution and integration adapters, while the client provides the operator-facing panel. See the source tree and architecture guide.
8. Related Ecosystem
- DeepSeek Harness: the host runtime providing agent sessions, tools, model integration, and the Web interface. Its official homepage links to the runtime repository and developer documentation; its general-purpose capabilities should not be confused with features implemented by this prototype.
- Cordis: the plugin architecture used by the Harness ecosystem and this bundle's configuration. The project's package manifest lists its Harness and Cordis compatibility requirements.
- GitHub and GitHub CLI: the repository collaboration platform and command interface used for agent identity and repository operations.
- Feishu/Lark and lark-cli: optional chat integration for receiving requests and returning replies. Account setup is documented in Deployment.
- Git worktrees and tmux: complementary tools for preparing task checkouts and managing the service process, as shown in the deployment workflow.
9. License
The repository uses the MIT License, with copyright attributed to the DeepSeek Harness Team.
- โ Commercial and private use, modification, copying, distribution, sublicensing, and selling copies are permitted.
- โ Modified versions may be distributed under your chosen terms, provided the required notices remain included.
- โ You may not omit the copyright and permission notices from copies or substantial portions of the software.
- โน๏ธ The software comes without warranty, and the license disclaims author liability.
- โน๏ธ The prototype's license does not replace the terms of external services, model providers, or dependencies.
10. FAQ
Q: Is this an official, production-ready DeepSeek service?
A: No. The README identifies it as a research prototype for reference. Review and adapt its implementation before adopting it.
Q: Does proactive mode mean the agent starts arbitrary work?
A: Inferred work requires the configured admission path, an assessment, matching written rules, and auto mode. Observe mode records potential acceptance without executing it; explicit requests remain available in all three modes. See Authorization.
Q: Can one instance manage multiple repositories or GitHub Enterprise Server?
A: The documented scope is one GitHub repository per instance, and deployment requires github.com. GitHub Enterprise Server is explicitly unsupported. See Deployment.
Q: Are worker directories secure sandboxes?
A: No. Managed sessions run with full access as the operator's OS user; credential wrappers select accounts without isolating processes. The deployment guide recommends a dedicated OS account containing only agent credentials when isolation is needed. See Permissions and isolation.
Q: Is Feishu required, and can I add another integration?
A: Feishu is optional. GitHub is the core repository integration, and the cookbook explains how to implement another Source, including its policy, context, and delivery behavior.
11. Quick Links
- Project repository
- README and project status
- Official project documentation
- Agent-assisted setup
- Manual deployment and troubleshooting
- Contribution guidance: architecture and development workflow
- Source extension guide
- Pull requests and code review
- DeepSeek Harness homepage and community plugin links
- MIT license
No standalone contributing guide or dedicated project discussion forum is linked in the reviewed README; use the repository and the upstream homepage as the documented starting points for participation.
12. Summary
dsh-superagent-prototype offers developers worldwide a concrete reference for combining repository conversations, explicit authorization, persistent task execution, and human supervision. It is useful for teams and researchers studying repository coding agents and extending the DeepSeek Harness ecosystem, with the expectation that its research implementation requires review and adaptation before operational use.