A low-memory macOS CLI that asks GPT-5.6 Terra whether an explicitly enabled Codex task legitimately finished or needs a loud human alarm.
Do you run agents while you sleep?
We all hate it when an agent stalls prematurely. For example, it can stop to ask you about an external blocker.
That is why I made a simple CLI that literally alarms you in the middle of the night.
How can it determine whether an agent has legitimately finished a task? After five minutes of inactivity, a GPT-5.6 Terra agent validates the task state and starts the alarm when human action is required.
launchd
runs one short metadata check every 30 seconds. No watcher process stays in memory between checks. After five minutes without canonical-task progress, one bounded codex exec
process classifies the stop. The evaluator process exits after its decision and is forcibly terminated after 120 seconds.
The evaluator uses:
gpt-5.6-terra
;- normal/default service speed, isolated from the user's Priority/Fast configuration;
- medium reasoning;
- a read-only temporary working directory;
- a closed JSON output schema;
--ephemeral
, so no evaluator rollout session is saved;- at most 10 recent user messages and 18 recent useful session snippets by default.
Each user message is capped at 12,000 characters. Evidence snippets include recent assistant messages, turn-completion messages, reasoning summaries, and tool results. Each evidence item is capped between 1,800 and 6,000 characters by type. Context extraction streams the canonical JSONL and keeps bounded ring buffers.
./codex-stall-watch install
Installation compiles the 52 KB native alert helper with the macOS Command Line Tools already present on this Mac.
codex-stall-watch on codex://threads/01234567-89ab-4def-8123-456789abcdef --name "Production deployment"
codex-stall-watch rename 01234567-89ab-4def-8123-456789abcdef "New title"
codex-stall-watch status
codex-stall-watch silence 01234567-89ab-4def-8123-456789abcdef
codex-stall-watch off 01234567-89ab-4def-8123-456789abcdef
The native alarm dialog has one button: Silence alarm. This stops the sound for the current canonical-session version. New canonical task progress invalidates the prior Terra decision and automatically re-arms the monitor.
For overnight use, an active alarm unmutes macOS, temporarily sets the system output volume to 100%, and plays a gapless alternating 880/660 Hz emergency tone. The tone continues until the user clicks Silence alarm or runs codex-stall-watch silence
. The monitor restores the prior volume and mute state when the alarm stops. This cannot override a disconnected speaker, a Mac that is powered off, or audio routed to headphones.
Terra can return:
legitimate_finish
: stay quiet until new canonical progress;alarm
: start the loud alarm;wait
: perform one bounded recheck after 60 to 600 seconds.
An evaluator timeout, CLI failure, malformed result, ambiguous evidence, or low-confidence finish fails closed to alarm
. Prompt and evidence files exist only in a mode-700 temporary directory and are deleted after evaluation. The alarm does not display evaluator evidence or secret values.
off
is different from silence
: off
removes the task's explicit opt-in.
on <url|id> [options] Enable a task (`--after`, `--name`, `--snippets`)
rename <url|id> <title> Set the title used in status and alarms
off <url|id> Disable a task
silence [url|id] Stop an alarm without disabling monitoring
status Show all enabled tasks
check Run one check now
test-alarm [seconds] Test the sound for 1 to 30 seconds
install Install and start the launchd timer
uninstall Remove the installed timer and CLI
State is stored in ~/.local/state/codex-stall-watch
. The LaunchAgent is ~/Library/LaunchAgents/com.local.codex-stall-watch.plist
.
The fast test uses an isolated fake Codex session:
./tests/test.sh
The live smoke test makes one real ephemeral Terra decision and confirms that a blocking approval request triggers an alarm decision without saving a session or leaving an evaluator process:
./tests/live-terra-smoke.sh
The timeout smoke test uses a fake hanging evaluator. It confirms forced termination and fail-closed alarm behavior:
./tests/timeout-smoke.sh