Set Up and Use dsh-superagent for Proactive GitHub Coding Tasks

What Is dsh-superagent?

dsh-superagent is a proactive coding agent designed to work with one GitHub repository. It is distributed as a bundle for DeepSeek Harness and listens for requests from GitHub and, optionally, Feishu.

When an allowed user asks it to perform work, the system opens a work item, creates a dedicated agent session and directory, completes the task, and replies in the original conversation. A result might include a pull request. A web panel shows items that require attention from a person.

dsh-superagent is a research prototype for reference, not an official DeepSeek product or production-ready system.

The published repository differs from the team's internal version and from the implementation discussed in Exploring Super-agent Design: Towards a More Autonomous Agent System. Some ideas in that article describe future directions and are not implemented in this prototype.

Core Design Principle

The project aims to take as little human attention as possible while delivering as much value as possible. Because a team-wide agent can also consume a team's attention, dsh-superagent follows two important constraints:

• It acts only when someone asks it to act or when a team-defined rule permits the action.
• It speaks only when someone must take action or can use a completed result.

Before deploying the agent, read the philosophy document. It explains this operating principle and the responsibilities of the person running the system.

Key Features

• Single-repository focus: Each deployment works with one GitHub repository.
• GitHub integration: The agent listens for authorized requests originating from GitHub.
• Optional Feishu integration: Teams can also use Feishu as a request source.
• Work-item tracking: An accepted request becomes a work item.
• Isolated execution: Each task runs in its own agent session and directory.
• Conversation-aware replies: Results are returned to the conversation where the request originated.
• Human-attention panel: A web panel identifies work that needs a person's involvement.
• Rule-controlled behavior: The agent acts only in response to a request or an explicit team rule.

Before You Install

Treat the repository as research code. It may contain bugs, inconsistent coding styles, or engineering decisions that are unsuitable for your environment. Review the implementation and adapt it before relying on it.

Setup has many steps, so the project recommends completing it collaboratively with a coding agent rather than manually guessing the required configuration.

Guided Installation and Setup

Step 1: Open the Repository with Your Coding Agent

Make the cloned or checked-out repository available to your coding agent. Then give it the setup instruction recommended by the project:

Read SETUP.md in this repository and set up dsh-superagent with me.

The coding agent should follow SETUP.md as its source of truth.

Step 2: Answer the Setup Questions

The setup flow is designed to ask one short question at a time. Provide the requested information for your repository, integrations, and environment. Avoid skipping the review steps simply because the process is agent-assisted.

Step 3: Review the Complete Plan

After gathering the required information, the coding agent presents the full plan once. Review it carefully before allowing installation or configuration changes. In particular, confirm that the plan matches the repository you intend the agent to manage and the request sources you intend to enable.

Step 4: Let the Agent Install and Configure the Project

Once you approve the plan, the coding agent installs and configures the system according to SETUP.md. Because the README delegates the detailed setup procedure to that file, follow its current instructions rather than relying on undocumented commands.

Step 5: Validate the Project

For development validation, run:

pnpm check

This command runs the typecheck, tests, and build. A successful run provides a combined check of the project's types, test suite, and build process.

Understand the Documentation Before Operating the Agent

The numbered documentation is intentionally cumulative. Read it in order because each document assumes only the material introduced before it:

1. 000 Philosophy: Understand the attention-minimizing operating principle and the operator's responsibilities.
2. 001 Domain model: Learn the project's core concepts and how they relate.
3. 002 Authorization: Determine who is allowed to ask the agent to perform work.
4. 003 Execution: Understand how accepted tasks are executed.
5. 004 Prompts: Review the prompts that guide agent behavior.
6. 005 Panel: Learn how the web panel presents items requiring human attention.
7. 006 Deployment: Follow manual setup, configuration, upgrade, and troubleshooting guidance.
8. 007 Architecture: Study the system's technical structure.
9. 008 Cookbook: Learn how to add a Source.

Basic Usage

Submit an Authorized Request

After setup, an allowed user can ask the agent to perform repository work through GitHub or through Feishu if that optional integration is enabled. A typical request should state the desired repository change and any relevant acceptance criteria.

For example, an authorized user might ask the agent to investigate a repository issue, make an appropriate code change, and return the result. The exact request mechanism and permitted users depend on your configured Source and authorization rules.

Let the Agent Create and Execute the Work Item

When the request is accepted, dsh-superagent opens a work item and performs the task in its own agent session and directory. This execution model keeps the task's working context separate.

Receive the Result in Context

The agent replies in the original conversation rather than forcing users to find results in a separate channel. Depending on the work performed, the response can include a pull request.

Use the Panel for Human Follow-up

Check the web panel for work that requires a person. The panel supports the project's attention-management goal by surfacing items that need human action instead of generating unnecessary communication about every internal step.

Authorization and Safe Operation

Authorization is central to the design. A proactive agent that can act across a team's repository should not accept arbitrary requests. Use the authorization documentation to define who can initiate work and under what conditions.

• Restrict requesters: Allow only intended people or systems to create actionable requests.
• Review team rules: Ensure automated actions occur only under rules the team explicitly wrote.
• Preserve human review: Treat agent-generated changes as work that may require inspection and adaptation.
• Test before broader use: Run pnpm check after development changes and validate behavior in your environment.

Advanced Tips

Use the Deployment Guide for Manual Operations

If you need to perform setup manually, change configuration, upgrade the project, or troubleshoot it, consult 006 Deployment. The README identifies this document as the detailed source for those operational procedures.

Review Prompts When Tuning Behavior

Read 004 Prompts before changing how the agent interprets or executes work. Prompt changes can affect when the agent communicates, how it approaches tasks, and how closely it follows the project's attention-minimizing philosophy.

Study Execution Before Modifying Task Isolation

The system gives each work item its own agent session and directory. Before altering this behavior, review 003 Execution and 007 Architecture so that changes remain consistent with the project's execution and system models.

Add a New Source Carefully

A Source is an integration through which the system can receive work. If you want to add one beyond the provided GitHub and optional Feishu paths, follow 008 Cookbook. Do not bypass the authorization model when introducing a new request channel.

Optimize for Useful Silence

When adapting the system, evaluate both the value of an action and the attention cost of its notifications. Prefer communication when a person must act or when a usable result is ready. This aligns extensions and operational rules with the project's central philosophy.

Development Workflow

After modifying the code, use the project's combined validation command:

pnpm check

Because it runs typechecking, tests, and the build, it should be a routine checkpoint before sharing or deploying changes. Passing this command does not make the research prototype production-ready; you must still review its behavior, security assumptions, authorization, and suitability for your environment.

Conclusion

dsh-superagent provides a research-oriented model for delegating work on a single GitHub repository while minimizing demands on human attention. Start with the guided SETUP.md workflow, read the numbered documentation in order, configure authorization conservatively, validate changes with pnpm check, and use the panel to focus human effort where it is genuinely needed.