codex_stuck

Detect whether Codex is running or stuck.

Have you ever experienced Codex running for a long time with no response, wanting to kill it but afraid it's still working silently?

English | 中文

---

Core Idea

A lightweight terminal status display plugin for Codex.

It determines whether Codex is stuck by monitoring:

• Session file status
• Traffic changes
• Silence duration

This plugin was created not only for easily detecting Codex status, but also as a monitor for fully automated operation of cca and ccb.

Solution

1. Inject completion markers (CODEX_DONE) into Codex prompts
2. Monitor session files (~/.codex/sessions/*.jsonl) to detect state
3. Display status in terminal title via OSC sequences

---

Status Icons

Icon	Status	Meaning
▶	Run	Producing output
▷	Think	Pending, low activity
◇	Idle	Long quiet period
□	Free	Waiting for input
■	Stuck	Very long quiet
×	Exit	Process exited

---

Installation

Linux / macOS / WSL

./install.sh

Auto-configures shell (zsh/bash). Restart terminal after install.

Windows (PowerShell)

.\install.ps1

Auto-configures PATH. Restart terminal after install.

---

Usage

After installation, just run:

codex

The terminal title will show real-time status.

---

Uninstall

./uninstall.sh      # Linux/macOS/WSL
.\uninstall.ps1     # Windows

---

Configuration (optional)

Variable	Default	Description
CODEX_STATUS_ICON_STYLE	shape	shape or emoji
CODEX_STATUS_INTERVAL_S	2	Sample interval (seconds)
CODEX_STATUS_MODEL_STUCK_S	900	Stuck threshold (seconds)

---

Related Projects: cca | ccb