dsh-status
将每个根会话的回合状态发布到一个 JSON 文档中，macOS 灯光守护进程会将其绘制为红绿灯。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:eustace030616-hub/traffic-light#a90f81161452b6c0722ac0f4850abf5493ccbdc4Status 以 dsh-status 发布，当前版本为 0.8.4。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A DSH plugin and a macOS light daemon. The plugin publishes what every session is doing to one small JSON file; the daemon reads that file and draws a traffic light above every window. Two processes, one document, no socket between them.
lib/ — a DSH plugin, installed from the plugin page.mac/ — DSHLight.app, universal and ad-hoc signed. It only ever reads.The plugin — paste this into DSH's plugin page (sidebar → Plugins) and restart DSH:
github:eustace030616-hub/traffic-light
The daemon — nothing to install: it ships inside the same package and the plugin starts it. To run it on its own, clone and open the shipped bundle:
git clone https://github.com/eustace030616-hub/traffic-light.git ~/traffic-light
open ~/traffic-light/bin/DSHLight.app
| You see | It means |
|---|---|
| dark | rest (idle): nothing is pending, which is not a failure |
| yellow, steady | a session is working (working) — including any subagents it has delegated to |
| yellow, pulsing | a session is blocked on you (asking) — 30% → 100% over 1.3 s |
| green | a turn finished and you have not read it (waiting) |
| red | the feed itself cannot be trusted — gone, unreadable or stale |
| red, pulsing | the balance is under the threshold, or the provider will not cover a call |
| You do | It does |
|---|---|
| double-click | switch between DSH and the application you came from |
| single click | says what the light means, beside it, at once — it drifts up and leaves after a second or so, longer for a longer sentence |
| right-click | open the list: Appearance, Account, Quit the light |
| drag | dock to the nearer screen edge, at whatever height you drop it |
A green settles by itself while DSH is in front, because being here is what the reminder was asking for.
Appearance ▸ Account ▸
Size ●━━━━━━━━━━ 20 pt CNY 12.62
Gap ●━━━━━━━━━━ 8 pt ─────────────
Rest ●━━━━━━━━━━ 28% Top up now
Lit ●━━━━━━━━━━ 85% updated 2m ago
─────────────
Reset to default
The sliders apply as they are dragged and are remembered; Reset to default restores 20 / 8 / 28% / 85%.
The account is one line per currency that holds something, with the platform's own top-up page below it.
Click a currency line — the ↻ is the hint — to ask for a fresh balance. The list stays open, and the
figure is rewritten in place when the answer lands.
One file, one direction:
DSH Desktop the daemon (DSHLight)
agent/pre-step a prompt was accepted reads the document every 0.25 s
agent/turn-stopping the ordinary turn end never fetches, holds no credential
agent/status idle | running
approval/request blocked on you
user-questions/… blocked on you
│ ▲
▼ │
lib/index.js — one document per change, and the │
same document re-stamped every 2 s (the heartbeat) │
│ │
▼ │
~/Library/Application Support/dsh-status/state.json ┘
written to a temp file and renamed into place
the daemon's one write, for a balance on demand:
click a currency line → touch <statePath>.refresh → served on the next heartbeat
meta.sessions; the daemon aggregates
blocked > unread finish > working > rest.flock) reading one path. A lock per path is what would have to
move first.updatedAt fresh, point the
daemon at it with --state-file PATH. No code in the daemon changes.~/Library/Application Support/dsh-status/state.json — cat it, or follow it with DSHLight --print.
{ "version": 1, "state": "working", "sessionId": "session-1a2b3c4d", "title": null,
"updatedAt": 1790000000000, "changedAt": 1790000000000, "heartbeatMs": 2000,
"reason": "prompt", "meta": { "cwd": "/Users/you/project" } }
| Field | Meaning |
|---|---|
version | Contract version. Bumped only for a breaking change. |
state | idle | working | waiting | asking. |
sessionId | Session being reported on, or null. |
title | Session title — always null for now (see Known gaps). |
updatedAt | When the publisher was last heard from. Re-stamped every heartbeatMs even when nothing changes — that is what makes staleness work, and why it must never be read as a change time. |
changedAt | When this state was last asserted. The heartbeat leaves it alone, so this — not updatedAt — is what an acknowledgement may be compared against. |
heartbeatMs | The publisher's cadence, so the daemon need not hardcode a staleness rule. |
reason | Which event wrote this: init, session-start, prompt, turn-end, agent-idle, agent-running, approval, question, answered, dispose. Debugging only. |
meta | Extension channel: additive, and unknown keys must be ignored. |
meta.sessions | Every session the publisher watches: { id, state, reason, changedAt, agents? }, where agents is how many subagents of that session are working. Live sessions (asking, working) come first and are never crowded out; a session that has not moved in twelve hours is forgotten. |
meta.account | { fetchedAt, intervalMs, isAvailable, balances: [{ currency, total, granted, toppedUp }] }, or a reason when the lookup failed. Figures are strings; never a credential. |
New information goes into meta, keys are only ever added, and a reader that meets a state it has never
heard of rests rather than alarms — so a new state or key cannot make an older build cry wolf.
| Transition | Trigger |
|---|---|
→ idle | plugin load, a session coming up, dispose |
→ working | agent/pre-step with messages, or agent/status: running |
→ waiting | agent/turn-stopping, or agent/status: idle |
→ asking | approval/request or user-questions/request, counted until the last is answered |
| ignored | a subagent's turn end: a child finishing is not the session finishing. A child's work does count — the session is working while one of its subagents is, and the snapshot says how many (agents) — and an ask is charged to its parent session |
Only the agent's status covers every ending: a turn you stop is aborted, and turn-stopping is never
dispatched for it — which is why a stopped session used to keep the light yellow until DSH restarted.
Every key is optional and validated by hand; an unusable value falls back to the default (lib/config.js).
| Key | Default | Notes |
|---|---|---|
statePath | ~/Library/Application Support/dsh-status/state.json | must be absolute |
heartbeatMs | 2000 | floor of 250 |
launch | true | start the daemon on mount, stop it on dispose |
lightArgs | [] | extra daemon arguments, e.g. --open / --ack-app for a browser-hosted DSH |
balance | true | the only request this package makes |
balanceMs | 300000 | floor of 60000 |
npm test # 68 checks — no DSH, no network, no key
npm run ship # rebuild bin/ from the Swift (npm test fails if it drifts)
./mac/build.sh --run # follow the light in a terminal
open build/DSHLight.app # draw it by hand
pkill -f DSHLight # stop it
| Flag | Effect |
|---|---|
--state-file PATH | which document to read (default: the published path) |
--print | follow in the terminal instead of drawing a window |
--interval SECONDS | poll interval, default 0.25 |
--open PATH | what the double-click opens, default /Applications/DSH Desktop.app |
--ack-app BUNDLE-ID | another application whose return settles a green; repeatable |
--no-ack | keep green until the next prompt instead of settling on return |
--level floating|status|screensaver | how high the window sits, default screensaver |
--size POINTS | lens size for this run, overriding the size slider |
--low-balance POINTS | when a balance turns the light red and breathing, default 8, in the currency holding the most; 0 turns it off |
Worth knowing:
visibleFrame reports the whole screen
in both bar states, and riding the bar produced a laggy light that overlapped it.flock for the life of the process.inject is the only
route that works — and lives in one local for the length of one request. Nothing stores it, and a rotated
key reaches the next request with no restart.ctx.credentials.set(ref, …) if one escapes.title is always null: the session title plainly exists, but which accessor exposes it is unconfirmed,
and a wrong guess would be worse than null.MIT — see LICENSE.