Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
{
"name": "devscope",
"description": "Real-time developer activity monitoring for Claude Code sessions",
"version": "0.25.1",
"version": "0.26.0",
"author": {
"name": "Lucas Dow",
"email": "lucdow7@gmail.com"
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "devscope",
"version": "0.25.1",
"version": "0.26.0",
"description": "Real-time developer activity monitoring for Claude Code sessions",
"author": {
"name": "Lucas Dow",
Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [0.26.0] - 2026-10-07

### Added
- **Quiet while the screen is locked.** Announcements are held and said soon
after you unlock (if the session still waits, no reminder used up), auto voice
is skipped, and an explanation stops after the current piece. Detected
locally: macOS `ioreg` (`CGSSessionScreenIsLocked`) and the screensaver, Linux
logind `LockedHint`; where it cannot tell (SSH, servers, lockers without
LockedHint) speech plays as before. `/devscope:voice when-locked play|quiet`
(default quiet); `status` shows the screen state.

### Fixed
- **Pauses and split phrases in spoken summaries.** Every summary over 200
characters was voiced as two or three separate recordings, with a pause and
restarted intonation between them, and a phrase was cut where no sentence
ended in time. Text that fits one request (440 characters, so every normal
summary) is now one recording, and longer text is split only between
sentences.

## [0.25.1] - 2026-10-07

### Changed
Expand Down
13 changes: 13 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,19 @@ claude plugin disable devscope@devscope # Disable
the next piece while the current one plays. `say` touches `spoke/<claude-pid>` so that
turn's reply is not also summarized; the Stop hook consumes it, a new prompt clears it.
`cli.sh stop` kills every registered `speakers/<pid>` process group.
- **Screen lock** (`_ds_voice_screen_locked`, `_ds_voice_can_play`; voice.json `when_locked:
quiet|play`, default quiet). macOS: `ioreg -n Root -d1` → `"CGSSessionScreenIsLocked"=Yes`, or
`ScreenSaverEngine` running. Linux: logind `LockedHint` of the user's graphical session
(`loginctl show-user $USER -p Display`, falling back to `$XDG_SESSION_ID`). Anything it cannot
read counts as unlocked (SSH, servers, lockers without LockedHint). While locked: `timer.sh`
holds due announcements (re-checks every `DS_VOICE_LOCK_POLL` s, reminder count untouched; the
30-minute stale rule still drops them), `_ds_voice_on_reply_event` and `speak.sh reply` skip auto
voice, `_ds_voice_speak_long` stops before the next piece. Tests use `DS_VOICE_LOCKED_FILE`
(locked while the file exists) and fake `loginctl`/`ioreg` on `PATH`.
- **Pieces** (`_ds_voice_chunks`): each piece is a separate recording and the voice's intonation
restarts at each, so text up to `DS_VOICE_ONE_REQUEST` (440, what voice-audio takes) is never
split; longer text is split only between sentences (first piece about 200 chars), and a single
sentence over 400 at a comma/semicolon/colon, at a word only as a last resort.
- **`progress.json`** is the contract with the devscope-live mod's voice bar: the speak lock
holder (`speak.sh`, `DS_VOICE_PROGRESS_KIND` set) writes `{kind, project, phase:
summarizing|voicing|speaking, piece, pieces, pieceMs, at (epoch ms), pid}` atomically per
Expand Down
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,20 @@ Other commands: `off`, `mute 1h`, `unmute`, `test`, `status`, `finished on` (als

`/devscope:voice explain --short <topic>` (or `--long`) overrides it for one explanation.

### Locked screen

DevScope only talks to someone at the computer. While the screen is locked:

| | What happens |
|---|---|
| Announcements ("a session is waiting") | held, then said a few seconds after you unlock if the session still waits; no reminder is used up |
| Auto voice | skipped; the reply is on screen when you are back |
| An explanation | stops after the piece that is playing |

It is detected locally, with nothing to install: on macOS from `ioreg` (`CGSSessionScreenIsLocked`) and the screensaver, on Linux from logind's `LockedHint` for your graphical session (GNOME, KDE and most lockers set it). Where it cannot tell (an SSH session, a server, a locker that does not set `LockedHint`, such as a bare i3lock) speech plays as before. An announcement held for more than 30 minutes is dropped, as any other that old is. `/devscope:voice when-locked play` turns this off; `when-locked quiet` (the default) turns it back on, and `status` shows whether the screen reads as locked.

Long speech is voiced in as few pieces as possible: text that fits one request (440 characters, so every normal summary) is one piece, and longer text is split only between sentences, so there is no pause mid-sentence.

### Auto voice

`/devscope:voice auto` toggles a short spoken summary whenever Claude finishes a reply: the outcome first, then anything you need to decide, in two or three sentences. It works with the announcer on or off. The reply is sent to your DevScope server to summarize and is not stored; in `private` mode you only hear which project finished, voiced locally.
Expand Down
4 changes: 2 additions & 2 deletions commands/voice.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(bash:*)
description: DevScope voice: explain a topic out loud, auto voice after every reply, announcements when a session waits on you (explain, auto, verbosity, speed, on, off, mute, stop, test, setup)
argument-hint: "[explain [--short|--long] <topic>|auto [on|off]|verbosity [explain|auto] [short|normal|long]|speed [slow|normal|fast|1.35]|status|on|off|mute 1h|unmute|stop|test|setup|finished on|off]"
argument-hint: "[explain [--short|--long] <topic>|auto [on|off]|verbosity [explain|auto] [short|normal|long]|when-locked [quiet|play]|speed [slow|normal|fast|1.35]|status|on|off|mute 1h|unmute|stop|test|setup|finished on|off]"
---

## Your task
Expand All @@ -25,7 +25,7 @@ Three features:
- **Announcer** (`on`/`off`): speaks only after a session has waited on the user past a grace delay (30 s for permission prompts and questions, 10 s for failures, 2 min for finished turns if `finished on`), then reminds every 5 min, up to 3 times. Answering in time keeps it silent.
- **Auto voice** (`auto`, `auto on`, `auto off`; plain `auto` toggles; `replies` is an old name for it): whenever Claude finishes a reply, a two-to-three sentence spoken summary of what it said. The reply is sent to the DevScope server to summarize and is not stored; in `private` mode only "<project> is done" is spoken, locally. A turn that used `explain` is not summarized on top.

`speed slow|normal|fast` sets how fast every voice talks: 1.0x, 1.2x (default) or 1.5x; `speed <number>` sets any rate from 0.5 to 2 (e.g. `speed 1.35`); plain `speed` shows the current one. `stop` ends speech in progress (a long explanation or a summary). `verbosity [explain|auto] short|normal|long` sets how detailed explain and auto voice are (both when no mode is named); plain `verbosity` shows them. `auto off` turns off only auto voice; announcements and `explain` are unaffected. `mute` silences auto voice and announcements. Settings live in `~/.config/devscope/voice.json` (`delays`, `reminder_interval`, `max_reminders`, `speak_replies`, `speed` (a number, 0.5-2), `engine`: `auto`/`server`/`piper`/`system`/`off`, `voice`, `volume` (0.5-3, server default 2), `piper_model`).
`speed slow|normal|fast` sets how fast every voice talks: 1.0x, 1.2x (default) or 1.5x; `speed <number>` sets any rate from 0.5 to 2 (e.g. `speed 1.35`); plain `speed` shows the current one. `stop` ends speech in progress (a long explanation or a summary). `when-locked quiet|play`: by default (`quiet`) nothing is spoken while the screen is locked (macOS `ioreg`/screensaver, Linux logind `LockedHint`): announcements wait until unlock, auto voice is skipped, an explanation stops; `play` ignores the lock. `verbosity [explain|auto] short|normal|long` sets how detailed explain and auto voice are (both when no mode is named); plain `verbosity` shows them. `auto off` turns off only auto voice; announcements and `explain` are unaffected. `mute` silences auto voice and announcements. Settings live in `~/.config/devscope/voice.json` (`delays`, `reminder_interval`, `max_reminders`, `speak_replies`, `speed` (a number, 0.5-2), `engine`: `auto`/`server`/`piper`/`system`/`off`, `voice`, `volume` (0.5-3, server default 2), `piper_model`).

## Explain mode (`explain [topic]`)

Expand Down
21 changes: 19 additions & 2 deletions scripts/voice/cli.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
# /devscope:voice — turn the voice announcer and auto voice (a spoken summary of every reply) on/off,
# mute, test, stop speech, install the Piper voice; `say` speaks text from
# stdin (/devscope:voice explain).
# Usage: cli.sh [status|on|off|mute <30s|15m|1h>|unmute|test|setup|finished on|off|auto [on|off]|speed [slow|normal|fast|<0.5-2>]|verbosity [explain|auto] [short|normal|long]|stop|say]
# Usage: cli.sh [status|on|off|mute <30s|15m|1h>|unmute|test|setup|finished on|off|auto [on|off]|speed [slow|normal|fast|<0.5-2>]|verbosity [explain|auto] [short|normal|long]|when-locked [quiet|play]|stop|say]
set -uo pipefail
VOICE_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck disable=SC1091
Expand All @@ -26,6 +26,7 @@ status() {
echo "Reminders: every $(_ds_voice_int .reminder_interval "$DS_VOICE_REMINDER_INTERVAL")s, at most $(_ds_voice_int .max_reminders "$DS_VOICE_MAX_REMINDERS")"
echo "Auto voice: $(_ds_voice_replies_on && echo on || echo off)"
echo "Verbosity: explain $(_ds_voice_verbosity explain), auto $(_ds_voice_verbosity auto)"
echo "Screen: $(_ds_voice_screen_locked && echo locked || echo unlocked); when locked: $(_ds_voice_conf .when_locked quiet)"
mute=$(_ds_voice_int .mute_until 0)
[ "$mute" -gt "$(date +%s)" ] && echo "Muted for $(( (mute - $(date +%s) + 59) / 60 )) more min"
pending=$(find "$DS_VOICE_PENDING" -name '*.json' 2>/dev/null | wc -l | tr -d ' ')
Expand Down Expand Up @@ -61,6 +62,21 @@ auto() {
esac
}

# What happens while the screen is locked: quiet (default) holds announcements
# until unlock, skips auto voice and stops an explanation; play ignores the lock.
when_locked() {
case "${1:-}" in
'') echo "When locked: $(_ds_voice_conf .when_locked quiet) (screen is $(_ds_voice_screen_locked && echo locked || echo unlocked) now)" ;;
quiet)
_ds_voice_set '.when_locked = "quiet"'
echo "When locked: quiet. Announcements wait until you unlock; auto voice is skipped; an explanation stops." ;;
play)
_ds_voice_set '.when_locked = "play"'
echo "When locked: play. Speech plays whether or not the screen is locked." ;;
*) echo "Usage: when-locked [quiet|play]"; return 1 ;;
esac
}

# How detailed explain and auto voice are: verbosity [explain|auto] [short|normal|long].
verbosity() {
local modes="explain auto" level mode
Expand Down Expand Up @@ -196,6 +212,7 @@ case "${1:-status}" in
auto|replies) auto "${2:-}" ;;
speed) speed "${2:-}" ;;
verbosity) verbosity "${2:-}" "${3:-}" ;;
when-locked) when_locked "${2:-}" ;;
say) say ;;
stop) stop ;;
test)
Expand All @@ -204,6 +221,6 @@ case "${1:-status}" in
"${DEVSCOPE_PRIVACY:-standard}" ;;
setup) setup ;;
*)
echo "Usage: /devscope:voice [status|on|off|mute <30s|15m|1h>|unmute|test|setup|finished on|off|auto [on|off]|speed [slow|normal|fast|<0.5-2>]|verbosity [explain|auto] [short|normal|long]|stop]"
echo "Usage: /devscope:voice [status|on|off|mute <30s|15m|1h>|unmute|test|setup|finished on|off|auto [on|off]|speed [slow|normal|fast|<0.5-2>]|verbosity [explain|auto] [short|normal|long]|when-locked [quiet|play]|stop]"
exit 1 ;;
esac
98 changes: 88 additions & 10 deletions scripts/voice/lib.sh
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,9 @@ DS_VOICE_MAX_REMINDERS=3
DS_VOICE_MIN_REMINDER_INTERVAL=5
# Longest single sleep in timer.sh, so off/unmute/re-arm are noticed promptly.
DS_VOICE_MAX_SLEEP=30
# While the screen is locked, a due announcement is checked again this often,
# so it is spoken soon after the person unlocks.
DS_VOICE_LOCK_POLL="${DS_VOICE_LOCK_POLL:-5}"
# A speech engine or player that hangs longer than this is killed.
DS_VOICE_SPEAK_TIMEOUT=30
# Server voice (Kokoro): default for voice.json `voice`.
Expand All @@ -66,6 +69,8 @@ DS_VOICE_SUMMARY_TIMEOUT=10
# is fetched while the current one plays.
DS_VOICE_CHUNK_FIRST=200
DS_VOICE_CHUNK_MAX=400
# What one voice-audio request takes: text up to this length is never split.
DS_VOICE_ONE_REQUEST=440
# Longest text spoken at once (~3 minutes at 1.2x); the rest is cut.
DS_VOICE_LONG_MAX=3000
# How much of Claude's reply is sent for a summary (the server takes 4000).
Expand Down Expand Up @@ -115,6 +120,38 @@ _ds_voice_verbosity() { # explain|auto
case "$v" in short|normal|long) printf '%s' "$v" ;; *) printf normal ;; esac
}

# --- Screen lock: speak only to someone at the computer ---

# Whether this machine's screen is locked (or, on macOS, its screensaver runs).
# Not locked when it cannot tell: no display session (SSH, a server), or a
# Linux locker that does not set logind's LockedHint (a bare i3lock).
_ds_voice_screen_locked() {
# Test hook: locked while this file exists.
if [ -n "${DS_VOICE_LOCKED_FILE:-}" ]; then [ -e "$DS_VOICE_LOCKED_FILE" ]; return; fi
case "$(uname -s)" in
Darwin)
ioreg -n Root -d1 2>/dev/null | grep -q '"CGSSessionScreenIsLocked"=Yes' && return 0
pgrep -x ScreenSaverEngine >/dev/null 2>&1 ;;
Linux)
command -v loginctl >/dev/null 2>&1 || return 1
local session
# The user's graphical session first: that is where the speakers are,
# even when Claude Code itself runs in an SSH session.
session=$(loginctl show-user "${USER:-$(id -un)}" -p Display --value 2>/dev/null)
[ -n "$session" ] || session="${XDG_SESSION_ID:-}"
[ -n "$session" ] || return 1
[ "$(loginctl show-session "$session" -p LockedHint --value 2>/dev/null)" = yes ] ;;
*) return 1 ;;
esac
}

# Whether speech may play now: not while the screen is locked, unless
# voice.json says `when_locked: play`.
_ds_voice_can_play() {
[ "$(_ds_voice_conf .when_locked quiet)" = play ] && return 0
! _ds_voice_screen_locked
}

_ds_voice_muted() {
[ "$(_ds_voice_int .mute_until 0)" -gt "$(date +%s)" ]
}
Expand Down Expand Up @@ -249,6 +286,9 @@ _ds_voice_on_reply_event() { # event-type hook-input
fi
_ds_voice_muted && return 0
[ "$(_ds_voice_conf .engine auto)" = "off" ] && return 0
# Nobody at the computer: a summary of this reply would be stale by the
# time anyone hears it, and it is on screen anyway.
_ds_voice_can_play || return 0
sid=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null)
[ -n "$sid" ] || return 0
# Private sessions keep the reply on this machine and get the template.
Expand Down Expand Up @@ -745,21 +785,50 @@ _ds_voice_wav_ms() {
echo $(( (size - 44) * 1000 / rate ))
}

# Split a text into pieces of at most DS_VOICE_CHUNK_MAX characters (the first
# at most DS_VOICE_CHUNK_FIRST), ending at sentence ends where possible. One
# piece per line; the text is cut after DS_VOICE_LONG_MAX characters.
# Split a text into the pieces it is voiced in, one per line. Each piece is a
# separate recording, and the voice's intonation restarts at each one, so:
# text that fits one voice-audio request (DS_VOICE_ONE_REQUEST) stays whole;
# longer text is split only between sentences, packing whole sentences up to
# DS_VOICE_CHUNK_MAX (the first piece about DS_VOICE_CHUNK_FIRST, so speech
# starts quickly); a single sentence over the maximum is split at a comma,
# semicolon or colon, and at a word only as a last resort. The text is cut
# after DS_VOICE_LONG_MAX characters, at a piece boundary.
_ds_voice_chunks() {
printf '%s\n' "$1" | tr '\n\r\t' ' ' | awk -v first="$DS_VOICE_CHUNK_FIRST" \
-v max="$DS_VOICE_CHUNK_MAX" -v cap="$DS_VOICE_LONG_MAX" '
-v max="$DS_VOICE_CHUNK_MAX" -v one="$DS_VOICE_ONE_REQUEST" -v cap="$DS_VOICE_LONG_MAX" '
function flush_units(text, i, k, parts, cur, word) {
# A sentence longer than max: clauses first, then words.
if (length(text) <= max) { units[++nu] = text; return }
k = split(text, parts, " "); cur = ""
for (i = 1; i <= k; i++) {
word = substr(parts[i], 1, max)
if (cur != "" && length(cur) + 1 + length(word) > max) { units[++nu] = cur; cur = "" }
cur = (cur == "" ? word : cur " " word)
if (length(cur) >= max / 2 && word ~ /[,;:]$/) { units[++nu] = cur; cur = "" }
}
if (cur != "") units[++nu] = cur
}
{ for (i = 1; i <= NF; i++) w[++n] = $i }
END {
text = ""
for (i = 1; i <= n; i++) text = (text == "" ? w[i] : text " " w[i])
if (text == "") exit
if (length(text) <= one) { print text; exit }
# Sentences, each a unit (or several, when longer than max).
sentence = ""
for (i = 1; i <= n; i++) {
sentence = (sentence == "" ? w[i] : sentence " " w[i])
if (w[i] ~ /[.!?][")]*$/) { flush_units(sentence); sentence = "" }
}
if (sentence != "") flush_units(sentence)
# Pack whole units into pieces; the first is kept short for a quick start.
cur = ""; lim = first; total = 0
for (i = 1; i <= n && total < cap; i++) {
word = substr(w[i], 1, max)
if (cur != "" && length(cur) + 1 + length(word) > lim) { print cur; total += length(cur); cur = ""; lim = max }
cur = (cur == "" ? word : cur " " word)
# A sentence end closes a piece once it is half full.
if (length(cur) >= lim / 2 && word ~ /[.!?:;][")]*$/) { print cur; total += length(cur); cur = ""; lim = max }
for (i = 1; i <= nu && total < cap; i++) {
if (cur != "" && (length(cur) + 1 + length(units[i]) > lim || (lim == first && length(cur) >= first / 2))) {
print cur; total += length(cur); cur = ""; lim = max
}
if (total >= cap) break
cur = (cur == "" ? units[i] : cur " " units[i])
}
if (cur != "" && total < cap) print cur
}'
Expand All @@ -781,16 +850,19 @@ _ds_voice_speak_long() { # text [privacy]
if [ -n "${DS_VOICE_SPEAK_LOG:-}" ] || [ "$privacy" = "private" ] || [ -z "${DEVSCOPE_API_KEY:-}" ] || \
{ [ "$engine" != "auto" ] && [ "$engine" != "server" ]; }; then
while [ "$i" -lt "$n" ]; do
_ds_voice_can_play || { _ds_voice_log "screen locked: speech stopped"; break; }
_ds_voice_progress speaking "$i" "$n"
_ds_voice_speak "${chunks[$i]}" "$privacy"
i=$((i + 1))
done
return 0
fi
_ds_voice_can_play || { _ds_voice_log "screen locked: speech not started"; return 0; }
dir=$(mktemp -d "${TMPDIR:-/tmp}/ds-voice.XXXXXX") || return 0
_ds_voice_progress voicing 0 "$n"
if ! _ds_voice_server_fetch "${chunks[0]}" "$privacy" "$dir/0.wav"; then
while [ "$i" -lt "$n" ]; do
_ds_voice_can_play || { _ds_voice_log "screen locked: speech stopped"; break; }
_ds_voice_progress speaking "$i" "$n"
_ds_voice_speak_local "${chunks[$i]}"
i=$((i + 1))
Expand All @@ -806,11 +878,17 @@ _ds_voice_speak_long() { # text [privacy]
_ds_voice_server_fetch "${chunks[$((i + 1))]}" "$privacy" "$dir/$((i + 1)).wav" 4 &
next=$!
fi
if ! _ds_voice_can_play; then
_ds_voice_log "screen locked: speech stopped"
[ -z "$next" ] || wait "$next"
break
fi
_ds_voice_progress speaking "$i" "$n" "$(_ds_voice_wav_ms "$dir/$i.wav")"
_ds_voice_play "$dir/$i.wav"
i=$((i + 1))
if [ -n "$next" ] && ! wait "$next"; then
while [ "$i" -lt "$n" ]; do
_ds_voice_can_play || { _ds_voice_log "screen locked: speech stopped"; break; }
_ds_voice_progress speaking "$i" "$n"
_ds_voice_speak_local "${chunks[$i]}"
i=$((i + 1))
Expand Down
2 changes: 2 additions & 0 deletions scripts/voice/speak.sh
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ case "${1:-}" in
# A newer reply from the same session replaces this one.
current || return 0
_ds_voice_muted && return 0
# Locked while it waited its turn: skip, as when queued.
_ds_voice_can_play || return 0
# Summarized under the lock, so the progress bar covers it too.
_ds_voice_progress summarizing
text=$(_ds_voice_reply_text "$JOB") || return 0
Expand Down
Loading
Loading