dsh-perch-notify

Readme

# dsh-perch-notify

English | 中文在后

Webhook notifications for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) sessions: get a POST when an approval is requested or a turn ends. Works with any profile that runs sessions (`web`, `tui`, `acp`, `sdk`, your own).

Use it with [ntfy.sh](https://ntfy.sh), [Bark](https://bark.day.app), a Slack/DingTalk/WeCom bot URL, or any HTTPS endpoint that accepts a POST.

## Install

```sh
dsh plugin --profile web add github:chenweigao/dsh-perch-notify
```

The package is plain JavaScript with no build step, so a git install needs no `prepare` script and no pnpm build allowlist.

## Configure

Set the destination in the environment before launching dsh:

```sh
export DSH_NOTIFY_URL="https://ntfy.sh/my-topic"     # where notifications go
export DSH_NOTIFY_FORMAT="ntfy"                       # json (default) | ntfy | bark
export DSH_NOTIFY_EVENTS="turn/end,approval/asked"    # optional; this is the default
dsh web
```

Or pin the same values in your profile's `cordis.patch.yml` (patch rows replace whole config values, so restate what you keep):

```yaml
- id: perch-notify
  name: dsh-perch-notify
  config:
    url: https://ntfy.sh/my-topic
    format: ntfy
    events: ['turn/end', 'approval/asked']
    timeoutMs: 8000
```

With no `url` the plugin loads inert and sends nothing.

## What it sends

The plugin observes the session event log (`session/event`) and forwards **lifecycle facts only** — never prompts, replies, tool arguments, or file contents.

`json` format (default) posts:

```json
{
  "event": "turn/end",
  "sessionId": "3d60430f-…",
  "time": "2026-09-21T13:29:56.155Z",
  "text": "dsh 轮次结束：3d60430f · completed",
  "detail": { "turn": 1, "reason": "completed" }
}
```

An approval request arrives as `{"event": "approval/asked", …, "detail": {"toolName": "bash", "reason": "…"}}`.

`ntfy` format posts the text with `Title`/`Tags` headers so phones ring; `bark` format posts Bark's `{title, body}` shape.

Delivery failures are logged to the dsh console and never block or retry the agent.

## Privacy

One outbound POST per matching event to your own endpoint, off by default without a URL. No other network calls, no telemetry, no storage outside dsh's own session log.

## Origin

Built by the author of [Perch](https://github.com/chenweigao/perch), a native macOS workspace for remote agents (including dsh over ACP). If you want approvals and turn completion on your Mac desktop instead of a webhook, that is what Perch does.

---

## 中文

dsh 会话的 webhook 通知插件：审批等待、轮次结束时向你自己的地址发 POST。支持 ntfy / Bark / 任意 JSON 接收端，任何跑会话的 profile（web、tui、acp、sdk）都能用。

```sh
dsh plugin --profile web add github:chenweigao/dsh-perch-notify
export DSH_NOTIFY_URL="https://ntfy.sh/my-topic"
export DSH_NOTIFY_FORMAT="ntfy"
dsh web
```

纯 JavaScript、无构建步骤，git 安装不需要 pnpm allowlist。插件只转发生命周期事实（哪类事件、哪个会话、哪个工具要审批），不发送提示词、回复、工具参数或文件内容；未配置 URL 时完全不动作。

由 [Perch](https://github.com/chenweigao/perch) 的作者构建——如果你想在 Mac 原生界面里直接处理审批和完成通知，而不是走 webhook，那是 Perch 干的事。

## License

MIT