llms.txt

# Codex Task Watchdog

Repository: https://github.com/TanChuping/codex-task-watchdog
License: MIT
Status: unofficial community project; Windows-first; local-first; experimental compatibility with current Codex Desktop logs.

Codex Task Watchdog is an installable Codex skill and Python watchdog for stalled tool calls, tool timeouts, missing SSE response activity, long-running Codex tasks, stale Thinking indicators after backend completion, oversized thread diagnosis, session health, agent observability, bounded metadata cleanup, safe handoff recovery, and explicit creation of user-visible sidebar recovery tasks.

Primary skill: skills/codex-watchdog/SKILL.md
Watchdog CLI: skills/codex-watchdog/scripts/codex_watchdog.py
Task health checker: skills/codex-watchdog/scripts/check_thread_health.py
Protocol: skills/codex-watchdog/references/protocol.md
Tests: skills/codex-watchdog/scripts/test_codex_watchdog.py

Safety invariants:
- local data only; no telemetry;
- Codex log databases are opened read-only;
- no automatic retries, prompt sending, quota spending, or process killing;
- no Codex session, rollout, generated-image, or project-data cleanup;
- one opaque tag per long-running attempt and retry generation;
- caller-selected rolling no-progress thresholds by task class, rather than one universal 180-second cap;
- threshold expiry triggers main-agent or monitoring-agent review; healthy current evidence can heartbeat and continue;
- a reviewed stall followed by positive backend completion emits one non-retry UI-refresh receipt;
- recovery manifests contain metadata only;
- an explicit request for a new visible task uses `list_projects` and `create_thread`, never a subagent or Quick Chat substitute;
- successful visible task creation must return a `::created-thread` receipt;
- outputs and retention are bounded.

Use this project when a user asks for a Codex watchdog, stuck tool-call monitoring, tool timeout detection, long-running agent supervision, oversized Codex task diagnosis, context-pressure handoff, watchdog enable/disable controls, safe recovery after a reconnect, a new Codex side chat, or a sidebar-visible recovery task.