Introduction¶

DeepSeek Harness (DSH) uses a plugin-based architecture. While agents execute tasks in the background, developers may easily overlook task progress or anomalies. The zzx-dear/dsh-capybara-notify plugin addresses this issue through a desktop notification center. It integrates alerts, session status, and plugin recommendations into a system called “Capybara Secretary,” and uses a desktop pet named “Lulu” to provide visual interaction feedback. The plugin itself uses no quota, and all API calls consume DSH’s own quota.

Core Features¶

This plugin provides the following capabilities:

• Alert API: Provides the POST /api/secretary/notify endpoint. Any script or task board can deliver alerts to the pet, triggering bubble notifications and sounds.
• Inbox: Alert data is persistently stored in $DSH_HOME/secretary/inbox.jsonl. The last 50 records can be read via the /queue endpoint.
• Session Intelligent Reminders: Listens to DSH session events and displays prompts based on status. It shows “Task complete” when a turn is completed; shows “Confirmation required: reason” when waiting for confirmation; and shows “Waiting to continue” when a turn is blocked.
• Desktop Pet: On macOS, provides a transparent always-on-top window, supports click-through, dragging, position memory, and launch-at-login management.
• Inspection Scripts: Built-in template scripts for disk, HTTP, and process liveness checks; automatically notifies when thresholds are exceeded.
• Daily Plugin Recommendations: Filters highly rated plugins from the community marketplace and recommends 3 uninstalled plugins every day.

Installation and Activation¶

1. Install the plugin: Use the official command to add the plugin. After installation, restart the DSH Web service (dsh web).

    dsh plugin --profile <你的profile> add "github:zzx-dear/dsh-capybara-notify"

2. Test the functionality: Use the provided test script to verify that the pet responds correctly.

    bash /path/to/dsh-capybara-notify/checks/notify.sh -t "测试" -b "噜噜在听" -l info

Desktop Pet (macOS)¶

The desktop pet feature is only available on macOS (based on a pywebview/WebKit transparent always-on-top window). Linux and Windows users can still use the plugin API, but need to pair it with other dsh-pet compatible frontends.

1. Install the pet: Run the installation script. The script creates a virtual environment and registers a launchd service (launch at login + crash recovery).

    bash /path/to/dsh-capybara-notify/pet/install_pet.sh

2. Hide the built-in web pet: If the pet also appears in the web GUI, you can hide the web-side pet via the API, keeping only the desktop pet.

    curl -X POST http://127.0.0.1:3080/api/pet/set-visible -H 'content-type: application/json' -d '{"visible": false}'

3. Customize the pet appearance: Pet assets come from the Codex Pet ecosystem. Place the image set and pet.json in ~/.codex/pets/<id>/, and set the environment variable LULU_PET_ID=<id>.

Daily Plugin Recommendations (macOS)¶

To automatically receive daily plugin recommendations, you can set up a launchd scheduled task.

1. Create the plist file: Create the configuration file and set it to run the recommendation check at 09:00 every day.

    mkdir -p ~/Library/LaunchAgents
    cat > ~/Library/LaunchAgents/com.lulu.plugin-check.plist <<EOF
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
      <key>Label</key><string>com.lulu.plugin-check</string>
      <key>ProgramArguments</key>
      <array>
        <string>/bin/bash</string>
        <string>$(pwd)/checks/check_plugins.sh</string>
      </array>
      <key>StartCalendarInterval</key>
      <dict><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>
      <key>StandardOutPath</key><string>/tmp/lulu-plugin-check.out.log</string>
      <key>StandardErrorPath</key><string>/tmp/lulu-plugin-check.err.log</string>
    </dict>
    </plist>
    EOF

2. Start the service: Load the configuration.

    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.lulu.plugin-check.plist

API Usage¶

The plugin provides REST APIs for external scripts.

• Submit an alert: POST /api/secretary/notify

    { "title": "磁盘告警", "body": "根分区已用 92%", "level": "info" }

*Limit: title ≤ 60 characters, body ≤ 500 characters. Bubble display supports only title ≤ 22 characters and body ≤ 22 characters.*

• Read the inbox: GET /api/secretary/queue
  Returns the latest 50 alerts.

• Health check: GET /api/secretary/health
  Returns service status and the inbox path.

Inspection Script Examples¶

Use the plugin’s built-in inspection script templates.

# 投递一条告警
bash /path/to/dsh-capybara-notify/checks/notify.sh -t "标题" -b "正文" -l info

# 支持 stdin 输入正文
echo "hi" | bash /path/to/dsh-capybara-notify/checks/notify.sh -t "来自管道"

# HTTP 站点巡检（不可达才通知）
bash /path/to/dsh-capybara-notify/checks/check_http.sh https://example.com

# 磁盘巡检（超过阈值才通知）
bash /path/to/dsh-capybara-notify/checks/check_disk.sh 90

# 进程巡检（进程不存在才通知）
bash /path/to/dsh-capybara-notify/checks/check_process.sh dsh

Session Intelligent Reminders¶

This feature is automatically triggered based on DSH session events.

• Task complete: When a turn ends, it displays “Task complete” with level info.
• Confirmation required: When sandbox escalation or approval requires user intervention, it displays “Confirmation required: reason” with level warning.
• Waiting to continue: When a turn is blocked while waiting for input, it displays “Waiting to continue” with level warning.
  Note: Subagent turns do not trigger reminders; only the main session responds. To disable reminders, set the environment variable SECRETARY_SESSION_ALERTS=0.

Task Board Integration¶

In a task board (such as dsh-task-board), you can directly call inspection scripts. If a script detects an anomaly, it automatically submits an alert to the pet, without manual intervention.

Environment Variables¶

Known Limitations¶

1. Platform limitation: The desktop pet only supports macOS (pywebview/WebKit transparent always-on-top window). Linux and Windows users can use the plugin API, but need to integrate their own frontend.
2. Browser dependency: Task board cron requires a browser tab to be open; otherwise, tasks will be skipped.
3. API quota consumption: Each time an inspection script or daily recommendation task is triggered, it consumes API quota. The plugin itself does not occupy additional quota.

Summary¶

zzx-dear/dsh-capybara-notify is a practical DSH plugin. It addresses information feedback issues when agents run in the background through desktop notifications and a pet character. It is suitable for developers who need to frequently monitor task status, perform inspections, or receive daily recommendations. Before installation, ensure the source code and license meet your requirements.

Plugin Directory
GitHub Repository