dsh-chime

Configuration

Config sources, lowest to highest priority:

1. Built-in defaults (see DEFAULT_CONFIG in src/config.ts) — the plugin always deep-merges with built-in defaults first, so any source only needs to write the keys it wants to change.

2. Plugin-line config field — users override in their own profile layer's cordis.patch.yml using the same line id (chime). Note dsh's patch-layer semantics: a later layer wholly replaces the previous layer's config (no deep merge), but keeps the line's name. For this plugin, the line's name comes from the bundle, so users only need to give the id and the keys to set:

   $DSH_HOME/profiles/ /cordis.patch.yml:

   - id: chime
     config:
       hush:
         armed: true
         from: '22:00'
         to: '08:00'
   

   Config edits trigger plugin hot-reload (HMR), no dsh restart needed.

3. Config file (machine-level override, shareable across profiles): $DSH_HOME/chime.config.json, or another path via the environment variable DSH_CHIME_CONFIG. JSONC supported (comments, trailing commas). The file overrides the line config, also merged key-by-key deep:

   // $DSH_HOME/chime.config.json
   {
     "hush": { "armed": true, "from": "22:00", "to": "08:00" },   // only these keys need to be written
     "kinds": { "blocked": { "tone": { "mode": "file", "file": "~/sounds/urgent.wav" } } }
   }
   

   On invalid config the plugin refuses to load and prints the specific reason (fail loudly, never degrade silently).

Full config reference

{
  "armed": true,                    // master switch
  "channels": {
    "desktop": true,                // desktop notification channel
    "tone": true,                   // tone channel
    "bell": false,                  // terminal bell (BEL, interactive terminals only)
    "toneProgram": "auto"           // Linux audio backend: auto | canberra | paplay | aplay | ffplay
  },
  "lingerMs": 8000,                 // notification display duration (ms)
  "kinds": {
    "done": {
      "armed": true,                // done signal switch
      "title": "任务完成",          // title template
      "message": "会话 {session} 已完成，耗时 {elapsed}",  // body template
      "icon": "",                   // custom icon path (`.ico` required on Windows)
      "urgency": "normal",          // low | normal | critical (Linux only)
      "tone": {
        "mode": "system",           // none | system | file
        "name": "Glass",            // macOS system sound name / Linux canberra theme id
        "file": "",                 // custom sound file (effective with mode=file; Windows: .wav only)
        "volume": 60                // volume 0-100 (macOS / some Linux backends)
      }
    },
    "blocked": { /* pending approval: default title "等待批准", urgency critical */ },
    "failed":  { /* run error: default title "运行出错", urgency critical */ }
  },
  "cadence": {
    "minIntervalMs": 5000,          // minimum interval between same-kind signals
    "burstLimit": 8,                // burst cap: max messages within the window
    "burstWindowMs": 60000          // burst stats window
  },
  "hush": {
    "armed": false,                 // hush window switch
    "from": "22:00",                // start HH:MM (local timezone)
    "to": "08:00",                  // end HH:MM, supports crossing midnight
    "weekdays": []                  // active weekdays [0=Sun…6=Sat], empty = every day
  },
  "bridge": {
    "decisionGraceMs": 600,         // approval grace period (ms)
    "attentionFrom": []             // extra dsh event names treated as "waiting for a human"
  }
}

Template placeholders

Title and body templates support the following placeholders (unprovided placeholders are kept as-is, so typos are easy to spot):

Placeholder	Meaning
{kind}	signal-kind label (完成 / 等待批准 / 出错)
{session}	session id
{project}	project name (only when provided by dsh)
{subject}	subject (e.g. the tool name that requested approval, an error summary)
{detail}	detail (approval reason, error message)
{elapsed}	this turn's elapsed time (done signal, and failed signals sourced from turn/end)
{source}	the event name that triggered the signal
{time}	trigger time HH:MM