Skip to main content

dsh-plugins/loop

44Stars4Forks1Issues0Watchers

Adds session-level recurring alarm clocks to DeepSeek Harness: automatically sends reminder messages to agents at set intervals. Ideal for long-running tasks requiring agents to proactively revisit work, such as polling checks and periodic reviews.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the Ephemeral-AI-Lab/dsh-plugins monorepo — stars and activity count the whole repository.

Language
Python
License
MIT
Branch
main
dsh-plugindsh-plugin-marketdsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add dsh-loop

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin Ephemeral-AI-Lab/dsh-plugins/loop for me: review the repository at https://github.com/Ephemeral-AI-Lab/dsh-plugins first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

The repository sub-path corresponding to the landing page is loop, the bearing directory in the repository is also loop, npm package name dsh-loop (package.json:3), one of the sub-packages under the Ephemeral-AI-Lab/dsh-plugins monorepo. This encyclopedia focuses on capabilities corresponding to the loop path.

One-Line Positioning

Add a "session-level recurring alarm" to DeepSeek Harness: let agents in the current session automatically receive a user message at your set second-level intervals, periodically turning back to do something—like timed build checks, log polling, or phased reviews.

Core Capabilities

  • Create recurring alarms with natural language or tools: tell the agent "remind me to check task progress every 30 seconds", and the agent will automatically call loop_create(prompt, time_in_seconds) to persist to the database.
  • Three agent tools share one set: loop_create for creating new loops, loop_list for listing active loops in the current session, loop_delete(id) for deleting one (src/tools.ts:33-90).
  • Operate the same backend with /loop command: /loop <seconds> <prompt> to create, /loop list to list, /loop delete <id> to delete (src/commands.ts:13-45).
  • Automatically deliver to agent at scheduled time: pack the prompt as a <heartbeat> user message to the session inbox with wakeup:true, idle agents receive via next-turn, agents in execution receive via next-step, without interrupting current operations (README.md:96-107).
  • State persisted in session event logs: loop definitions and each trigger are written as loop/change session events, timers are process-local, sessions are rebuilt from event logs upon recovery (SPEC.md:115-121).
  • A compact Loop dock on the web: displays active count, each interval, next countdown, complete prompt, with one-click delete button (src/ui/LoopsView.tsx:83-118).

Technical Implementation

  • Language: TypeScript (compiled by tsc to lib/, package.json:11 declares "type": "module")
  • Key Dependencies:
    • @deepseek-ai/cordis (>=4.0.0): host plugin framework, apply(ctx) follows standard Cordis effect
    • @deepseek-ai/dsh-tools / @deepseek-ai/dsh-commands: register three tools with defineTool, register /loop command with ctx.commands.register
    • @deepseek-ai/dsh-session + @deepseek-ai/dsh-session-persistence: write loop state to session event logs and flush
    • @deepseek-ai/dsh-client-ui-slots + @deepseek-ai/dsh-client-ui-conversation: inject Loop dock to conversation.input.dock slot on web side
  • Architecture Pattern: Cordis plugin + cordis.patch.yml injects one line loop into host. apply(ctx) listens to agent/created event, each root agent binds a LoopRuntime, runtime uses setTimeout to schedule next trigger, at trigger time calls agent.send(..., 'next-turn'|'next-step', true) and writes back loop/change event; state exposed to frontend via a loop projection (stateVersion: 1), event type loop/change dynamically registered via runtime's dsh-session module.
  • Entry File: loop/src/index.ts (export name = 'loop', inject = ['tools','commands','agents','sessions','sessionPersistence','sessionProjections'], src/index.ts:13-14)

Applicable Scenarios

When a DSH session requires the agent to proactively periodically look back—for example, letting the agent self-check the latest errors every 20 seconds and give fix suggestions, every 60 seconds pick three weakest points in a draft, every 10 seconds check if the build is still healthy—this plugin can be used: after creating a loop, the agent will self-trigger at the rhythm without your prompting, suitable for long-running scenarios that require continuous state observation.

Pre-dependencies and Compatibility

DependencyMinimum VersionDescription
@deepseek-ai/dsh-tools>=0.1.0-rc.5peerDependencies, registration of loop_create/list/delete three tools depends on it
@deepseek-ai/dsh-commands>=0.1.0-rc.5peerDependencies, /loop command registration depends on it
@deepseek-ai/dsh-session>=0.1.0-rc.5peerDependencies, writing loop/change event depends on it
@deepseek-ai/dsh-session-persistence>=0.1.0-rc.5peerDependencies, runtime's flush depends on it
@deepseek-ai/dsh-session-projection>=0.1.0-rc.5peerDependencies, loop projection registration depends on it
@deepseek-ai/dsh-agent>=0.1.0-rc.5peerDependencies, runtime directly holds Agent instance
@deepseek-ai/dsh-llm>=0.1.0-rc.5peerDependencies, createUserMessage source
@deepseek-ai/dsh-api-remotes + @deepseek-ai/dsh-client-runtime + @deepseek-ai/dsh-client-ui-conversation + @deepseek-ai/dsh-client-ui-slotseach >=0.1.0-rc.5peerDependencies, required for web-side Loop dock injection; package.json:18-25 lists first three in dsh.client.inject, missing any means Web UI won't load
@deepseek-ai/cordis>=4.0.0peerDependencies, host plugin framework
react>=18.2.0peerDependencies, Loop dock is a React component
zod^4.4.3dependencies, projection's schema validation
PlatformDSH Webpackage.json:24 explicitly declares dsh.client.platform: "web", CLI/desktop not declared
Node.jsNot declaredpackage.json has no engines field; only devDependencies has @types/node ^22.20.0
Native ModulesNoneOnly depends on pure JS packages above, no node-gyp build items

Installation

dsh plugin --profile web add github:Ephemeral-AI-Lab/dsh-plugins/loop

Configuration

This plugin requires no additional configuration. After installation, restart DSH and create a new session to use; loop intervals, prompts, and IDs are all determined at runtime through tool calls, no plugin-level config files or environment variables are read.

The only fields validated are time_in_seconds (must be positive integer seconds), prompt (non-empty string), id (non-empty with no leading/trailing whitespace), which are hard constraints of tool input parameters, not configurable items.

FAQ

Q: How do I use it after installation?

A: Restart DSH and create a new session. Typing /loop 10 check the build status in the input box immediately creates the first loop; agents in the session can also use natural language like "remind me to check errors every 20 seconds" to automatically call loop_create. No new preset needed or host configuration to toggle.

Q: How to change a loop's interval or prompt?

A: v1 does not provide loop_update/edit/pause/resume/immediate trigger operations (clearly listed as non-goals in SPEC.md:38-44). Actual practice is to loop_delete first then loop_create again.

Q: Will loops continue running after DSH process is closed?

A: No. Timers are process-local, README.md:119-121 clearly states "a stopped or cold process cannot run timers or wake itself"; upon session recovery, runtime rebuilds next trigger time from loop/change event logs, so missed reminders during sleep are not resent.

Q: Can loops be shared between different sessions?

A: No. SPEC.md:49-58 specifies each loop belongs to the session that created it, other sessions cannot see or delete it; "global loops" is a v2 design goal (see SPEC_V2.md), v1 does not implement this.

Q: If the agent is running another task when a reminder arrives, will it be interrupted?

A: No. Reminders are user messages with wakeup:true, runtime delivers based on agent's current state: 'running' uses next-step, others use next-turn (src/loop.ts:229), i.e., processed at next safe step boundary, not preempting current operation.

Q: Is there visualization on the web side?

A: Yes. DSH Web's conversation input box displays a compact Loop dock above, showing active loop count, each every Xs/m/h interval, next in … countdown, complete prompt, and a one-click delete button; when loops exceed 3, they automatically collapse into "X active loops · next in …" summary (src/ui/LoopsView.tsx:79-100).

Q: Can I use decimals or minute/hour units for intervals?

A: Time unit can only be seconds. time_in_seconds must be a positive integer (src/tools.ts:45, src/loop.ts:369-370), if you need minutes/hours, just convert to seconds and pass that.

Q: How to uninstall?

A: Use the corresponding dsh uninstall command to remove the installation source; after uninstallation, loops still running in the current session stop (runtime disposed with host), new sessions no longer register the three tools loop_create / loop_list / loop_delete and /loop command.

Learning Curve

Beginner — Ready to use after installation, no config files, no native modules, no special preset to create; can send the first /loop 10 check the build status in as fast as 30 seconds.

Known Issues and Limitations

  • v1 has no loop modification/pause/resume/immediate trigger API (SPEC.md:38-44), to change interval or prompt must delete and recreate.
  • Runtime is session-local, process-local: timers don't trigger when DSH process stops or system sleeps, missed reminders are not resent (SPEC.md:42-44, README.md:119-121).
  • Loops belong to the session that created them, cross-session sharing and visualization are v2 design goals (SPEC_V2.md), v1 does not support.
  • Single setTimeout maximum delay is 2,147,483,647 ms (~24.8 days), forced by MAX_TIMER_DELAY_MS (src/loop.ts:17,255-257), intervals exceeding this limit are split into multiple timers rearranged.
  • Only dsh.client.platform: "web" declared (package.json:24), CLI/desktop availability not explicitly in source.
  • Web-side Loop dock only renders when there is at least 1 active loop (src/ui/LoopsView.tsx:77), when there are no loops the area above input box won't appear.
  • Package does not modify DeepSeek Harness host code, all goes through Cordis effect and DSH public APIs (SPEC.md:8-10), but this also means once host changes dsh-session exposed event types, plugin's registration of loop/change will simultaneously become invalid (src/index.ts:18-25).

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/Ephemeral-AI-Lab/dsh-plugins/loop)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory