| name | codex-monitor |
| description | Monitor Codex CLI session status, detect timeouts, errors, and completion. Use when user asks about Codex session status, wants to check if Codex is still running, needs to debug a stalled session, or mentions "codex monitor", "session status", "codex 状态", "session 断了吗". |
Codex Session Monitor
Monitor and analyze Codex CLI sessions from ~/.codex/sessions/.
Quick Start
Run the monitor script:
python3 <skill-dir>/scripts/codex-monitor.py [today|yesterday|YYYY-MM-DD] [--watch] [--last N]
Common Commands
| Command | What it does |
|---|
python3 codex-monitor.py | Show all sessions from today |
python3 codex-monitor.py --watch | Live monitor (refresh every 10s, Ctrl+C to stop) |
python3 codex-monitor.py --last 5 | Show only the last 5 sessions |
python3 codex-monitor.py yesterday | Show yesterday's sessions |
python3 codex-monitor.py 2026-02-20 | Show a specific date |
Status Icons
| Icon | Meaning | Action |
|---|
| ✅ | Completed normally | None needed |
| 🔄 | Still running | Wait or check progress |
| ⏱️ | Timeout/stale (>10min no output) | Likely dead, restart task |
| ⚠️ | Possibly stale (2-10min) | Check soon |
| ❌ | Error | Read error message |
| 📭 | Empty/initialized only | Session didn't start |
Output Includes
- Session ID, start/end time, duration
- Parent → Child Agent tree structure
- Tool call count and token usage
- Rate limit percentage
- Last agent message (truncated)
- Files written by the session
- Error messages if any
Interpreting Results
"Is Codex still running?"
Look for 🔄 (running) status. If you see ⏱️ (timeout), the session likely died.
"Did Codex finish?"
Look for ✅ (completed) and check last_message for the final output summary.
"Why did Codex stop?"
Check for:
- ❌ errors — read the error message
- Rate limit percentage — if near 100%, Codex hit API limits
- ⏱️ timeout — session exceeded time limits
- Token usage — very high output tokens may indicate truncation
Multi-Agent Sessions
The script shows parent-child relationships with indentation. A main session spawns sub-agents (子Agent) for parallel work. Check if all children completed.
