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.
ⓘ 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
Install
$ dsh plugin --profile web add dsh-loopRun 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 alsoloop, npm package namedsh-loop(package.json:3), one of the sub-packages under theEphemeral-AI-Lab/dsh-pluginsmonorepo. This encyclopedia focuses on capabilities corresponding to thelooppath.
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_createfor creating new loops,loop_listfor listing active loops in the current session,loop_delete(id)for deleting one (src/tools.ts:33-90). - Operate the same backend with
/loopcommand:/loop <seconds> <prompt>to create,/loop listto 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 withwakeup: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/changesession 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
tsctolib/,package.json:11declares"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 withdefineTool, register/loopcommand withctx.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 toconversation.input.dockslot on web side
- Architecture Pattern: Cordis plugin +
cordis.patch.ymlinjects one lineloopinto host.apply(ctx)listens toagent/createdevent, each root agent binds aLoopRuntime, runtime usessetTimeoutto schedule next trigger, at trigger time callsagent.send(..., 'next-turn'|'next-step', true)and writes backloop/changeevent; state exposed to frontend via aloopprojection (stateVersion: 1), event typeloop/changedynamically registered via runtime'sdsh-sessionmodule. - 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
| Dependency | Minimum Version | Description |
|---|---|---|
@deepseek-ai/dsh-tools | >=0.1.0-rc.5 | peerDependencies, registration of loop_create/list/delete three tools depends on it |
@deepseek-ai/dsh-commands | >=0.1.0-rc.5 | peerDependencies, /loop command registration depends on it |
@deepseek-ai/dsh-session | >=0.1.0-rc.5 | peerDependencies, writing loop/change event depends on it |
@deepseek-ai/dsh-session-persistence | >=0.1.0-rc.5 | peerDependencies, runtime's flush depends on it |
@deepseek-ai/dsh-session-projection | >=0.1.0-rc.5 | peerDependencies, loop projection registration depends on it |
@deepseek-ai/dsh-agent | >=0.1.0-rc.5 | peerDependencies, runtime directly holds Agent instance |
@deepseek-ai/dsh-llm | >=0.1.0-rc.5 | peerDependencies, createUserMessage source |
@deepseek-ai/dsh-api-remotes + @deepseek-ai/dsh-client-runtime + @deepseek-ai/dsh-client-ui-conversation + @deepseek-ai/dsh-client-ui-slots | each >=0.1.0-rc.5 | peerDependencies, 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.0 | peerDependencies, host plugin framework |
react | >=18.2.0 | peerDependencies, Loop dock is a React component |
zod | ^4.4.3 | dependencies, projection's schema validation |
| Platform | DSH Web | package.json:24 explicitly declares dsh.client.platform: "web", CLI/desktop not declared |
| Node.js | Not declared | package.json has no engines field; only devDependencies has @types/node ^22.20.0 |
| Native Modules | None | Only 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
setTimeoutmaximum delay is 2,147,483,647 ms (~24.8 days), forced byMAX_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 changesdsh-sessionexposed event types, plugin's registration ofloop/changewill simultaneously become invalid (src/index.ts:18-25).
Small, focused plugins that make DeepSeek Harness more capable, expressive, and pleasant to use.
Quick start · Packages · Development · Documentation
🧠 Give your DSH sessions better tools, durable workflows, and a cleaner path from idea to execution.
⚡ Quick start
Published plugins install directly into a DSH profile with one command. The
examples below target the web profile; replace web with the profile you use.
🐚 Codex Terminal
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
🔐 Codex Coding Plan
Reuse an existing file-backed codex login from the DSH Models page:
dsh plugin --profile web add ./coding-plan/codex
# Grok Coding Plan models from the existing `grok login`
dsh plugin --profile web add ./coding-plan/grok
⏰ Loop
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
🧪 Mock — unstable
dsh-mock is published for early testing. Its commands, API, and UI may
change before a stable release.
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
🧭 Sessions
Inspect, create, read, and message DSH sessions with the current session tools:
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
Restart DSH and create a new session after installing a plugin. If dsh is not
on your PATH, run the same command from a DeepSeek Harness source checkout with
pnpm dsh instead.
Direct npm installation downloads the package for use by your project. DSH profile installation is still required when you want DSH to load the plugin as part of a profile.
📦 Packages
| Package | Status | What it adds | Docs |
|---|---|---|---|
dsh-codex-coding-plan | 🧪 Local · 0.1.0 | Reuses a file-backed Codex ChatGPT login through the existing openai-codex pi-ai provider. | README |
dsh-grok-coding-plan | 🧪 Local · 0.1.0 | Reuses a file-backed Grok subscription login through the existing xai pi-ai provider. | README |
dsh-codex-terminal | ✅ Published · 0.1.3 | Codex-compatible exec_command and write_stdin tools with persistent command sessions. | README · npm |
dsh-loop | ✅ Published · 0.1.3 | Session-scoped recurring alarms, loop tools, slash commands, and a web UI. | README · npm |
dsh-mock | ⚠️ Unstable · ✅ Published · 0.1.0 | Deterministic mock model turns and replay commands routed through the real DSH AgentLoop and ToolRuntime. | README · SPEC · npm |
dsh-sessions | ✅ Published · 0.1.1 | Session discovery, bounded reads, creation, and delivery through session tools and /sessions. | README · SPEC · npm |
🐚 dsh-codex-terminal
Run shell commands like a Codex-style agent: start long-running processes, poll for output, and send input to persistent sessions. PTY transport is used by default with a configured pipe fallback when PTY allocation is unavailable.
⏰ dsh-loop
Create durable, session-local recurring prompts that can be managed through
agent tools, /loop commands, and the web UI. Loops resume with the session
and keep each alarm independent from the others.
🧪 dsh-mock
Exercise deterministic mock model turns through /mock run and /mock replay
while preserving the real DSH AgentLoop, ToolRuntime, policy, and event flow.
⚠️ Unstable: published as
[email protected]for early testing. The command, API, and UI surface may change before a stable release.
Install it into the DSH web profile with one command:
dsh plugin --profile web add [email protected]
🛠️ Development
Each plugin is independently installable and testable. For example:
cd loop
pnpm install
pnpm test
pnpm build
The source tree intentionally stays outside the DeepSeek Harness repository; DSH composes plugins through profile-scoped installation and patch layers.
📚 Documentation
- Codex Terminal documentation
- Coding Plan core
- Codex Coding Plan documentation
- Grok Coding Plan documentation
- Loop documentation
- Mock documentation
- Mock implementation specification
- Sessions documentation
- Sessions specification
- DeepSeek Harness
🤝 Contributing
Issues, ideas, and pull requests are welcome. Keep plugins focused, document their runtime contracts, and include tests for changes to tools, persistence, or UI behavior.
📄 License
Released under the MIT License.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](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.