| name | terminal-status-indicators |
| description | Make VS Code terminal tabs show 🔔 + chime the moment an agent session needs you, across many parallel Copilot/Claude terminals. Installs three layers: workspace settings (tab bell icon + audio cue), a shell prompt hook (bell on command completion), and a background /proc-io watcher that rings a terminal's PTY bell when its agent process goes idle after responding. Use in a Codespace / VS Code setup where you run multiple background agent sessions and can't tell which one is waiting for input without clicking through each tab. |
Terminal status indicators — bell + chime + idle-watcher
When you run several background agent sessions across many VS Code terminals, a terminal waiting
for your input looks identical to one actively working. This skill makes the waiting ones
announce themselves: the tab shows a 🔔 and plays a chime the moment the agent goes quiet.
The three layers
| Layer | What it does | Mechanism |
|---|
| VS Code settings | 🔔 icon on the tab + audio chime when a BEL is received; ⟳ running indicator via shell integration | .vscode/settings.json keys (settings-snippet.json) |
| Shell prompt bell | Rings the bell when any shell command finishes (agent done, script complete) | preexec/precmd in ~/.bashrc (interactive shells only) |
| Background watcher | Rings a terminal's bell when its agent process goes idle after responding — even mid-session, before the shell prompt returns | terminal-watcher.py reads /proc/<pid>/io wchar and writes \a to the PTY |
Net effect: actively-working terminals show ⟳; terminals that need you show 🔔 + chime — visible in the
tab strip without expanding each terminal.
Install
One command wires all three layers (idempotent — safe on every Codespace rebuild):
bash setup-terminal-indicators.sh [--project DIR] [--commands "copilot,claude"]
--project DIR — the repo whose .vscode/settings.json to configure (default: $PWD). The merge is
non-destructive: it only adds keys you don't already have.--commands LIST — comma-separated process names the watcher rings for (default copilot,claude;
it's generic — any agent CLI works).
The installer copies the watcher to ~/.local/share/ravenclaude/terminal-watcher.py (a stable path,
independent of the plugin-cache version dir) and adds a marker-bounded block to ~/.bashrc.
Codespace auto-setup
Call the installer from your devcontainer's postCreateCommand so a new Codespace self-configures —
see ../../../../.devcontainer/post-create.sh (this repo
dogfoods it) and the consumer template
../../templates/codespace-copilot/ravenclaude-post-create.sh.
Use (after source ~/.bashrc or a new terminal)
watch-terminals
watcher-log
stop-watching
How the bell reaches VS Code
agent process writes \a to its PTY slave (/dev/pts/N)
↓
VS Code (the PTY master) reads it
↓
VS Code shows 🔔 on the tab + plays the audio cue
The watcher writes a single \a byte to the PTY slave (O_WRONLY | O_NOCTTY). It must run as the
same OS user as the terminal owner (in a Codespace, codespace → codespace, so this holds).
Design & bug history
The watcher's non-obvious correctness decisions — accumulate-across-ticks (streaming responses never
clear a per-tick byte threshold), ring-once-per-PTY (a shell wrapper + the real binary share one PTS),
retry-PTY-resolution, single-instance pidfile guard, no-startup-bell baseline — are documented with
proof-of-failure in
../../knowledge/vscode-terminal-status-indicators.md.
Read that before changing terminal-watcher.py.
Known limitations
wchar counts all writes, not just terminal output. A process that writes heavily to log files
between responses may not settle. CLI agents are quiet between responses in practice; if you see
false idles, raise TERMINAL_WATCHER_IDLE or TERMINAL_WATCHER_MIN_BYTES.- The idle heuristic can't perfectly tell "response done" from "mid-response pause." A single
response with an internal pause longer than
TERMINAL_WATCHER_IDLE (a tool call, a network wait)
can ring twice; conversely the tool errs toward ringing (a missed bell defeats the purpose more
than a rare extra one). TERMINAL_WATCHER_RESET (default 30s) is the window after which a
sub-threshold burst is forgotten — long enough that a real chunked response still accumulates,
short enough that genuinely-stale partial activity doesn't linger. Tune all three to your agents'
cadence.
- Non-interactively-launched agents may have no PTY (
pty=None) and can't be rung; the watcher
keeps retrying resolution but can't invent a terminal.
- The prompt bell fires on every prompt return (including fresh terminal opens) — slightly noisy
but it correctly signals "process done, your turn."
- The
DEBUG trap is global — it overwrites any existing DEBUG trap (e.g. another prompt
framework). If you use starship/oh-my-bash, install this after them or merge by hand.
- Terminals collapsed into one panel icon don't show per-tab indicators. Move agent terminals to
the editor area (right-click tab → Move Terminal into Editor Area) for persistent visibility.
Tuning (environment variables)
| Variable | Default | Meaning |
|---|
TERMINAL_WATCHER_COMMANDS | copilot,claude | process names (matched on /proc/<pid>/comm) to watch |
TERMINAL_WATCHER_POLL | 0.5 | seconds between polls |
TERMINAL_WATCHER_IDLE | 3.0 | seconds of quiet after activity before ringing |
TERMINAL_WATCHER_MIN_BYTES | 500 | cumulative bytes that count as "a real response" |
TERMINAL_WATCHER_RESET | 30.0 | seconds of quiet before a sub-threshold burst is forgotten (kept well above IDLE so a real response with a mid-stream pause still accumulates) |
TERMINAL_WATCHER_PIDFILE | /tmp/terminal-watcher.pid | single-instance lock path |
