codex-ralph 0.3.1 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ Minimal Ralph Wiggum Loop runner that feeds a sprint requirement into Codex, one
 ## Quick start
 
 ```bash
-npx codex-ralph --sprint=path/to/Sprint_0001.md --max-iterations=1
+npx codex-ralph path/to/Sprint_0001.md --max-iterations=1
 ```
 
 ## Telegram progress notifications
@@ -17,7 +17,27 @@ CODEX_RALPH_TG_KEY=123456:bot-token
 CODEX_RALPH_TG_CHAT=123456789
 ```
 
-Provide these as environment variables (e.g., when invoking `npx`). Each session generates a UUID and includes it in start/transition/finish messages.
+Provide these as environment variables (e.g., when invoking `npx`). Each session generates a UUID and includes it in progress messages.
+
+Usage:
+
+```
+npx codex-ralph path/to/Sprint_0001.md
+```
+
+Optional flags:
+
+```
+--max-iterations=10
+```
+
+Message format:
+
+```
+🧭 ~<session-uuid>~
+📌 <current requirement title>
+🎯 <current index> of <total requirements>
+```
 
 ## Sprint format (Markdown)
 

package/agent/ralph-loop.sh

@@ -9,7 +9,7 @@ PY
 )"
 ROOT_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
 SPRINT_FILE=""
-MAX_ITERATIONS=0
+MAX_ITERATIONS=10
 NOTES_FILE=""
 SESSION_UUID=""
 
@@ -40,11 +40,11 @@ send_telegram() {
 
 usage() {
   cat <<USAGE
-Usage: ralph-loop --sprint=PATH [--max-iterations=N]
+Usage: ralph-loop SPRINT_PATH [--max-iterations=N]
 
 Options:
-  --sprint=PATH          Path to the sprint markdown file (required).
-  --max-iterations=N     Stop after N iterations (0 = no limit).
+  SPRINT_PATH            Path to the sprint markdown file (required).
+  --max-iterations=N     Stop after N iterations (0 = no limit, default 10).
   -h, --help             Show this help.
 USAGE
 }
@@ -53,9 +53,6 @@ session_uuid >/dev/null
 
 for arg in "$@"; do
   case "$arg" in
-    --sprint=*)
-      SPRINT_FILE="${arg#*=}"
-      ;;
     --max-iterations=*)
       MAX_ITERATIONS="${arg#*=}"
       ;;
@@ -63,11 +60,20 @@ for arg in "$@"; do
       usage
       exit 0
       ;;
-    *)
+    -*)
       echo "Unknown argument: $arg" >&2
       usage >&2
       exit 1
       ;;
+    *)
+      if [[ -z "$SPRINT_FILE" ]]; then
+        SPRINT_FILE="$arg"
+      else
+        echo "Unexpected argument: $arg" >&2
+        usage >&2
+        exit 1
+      fi
+      ;;
   esac
  done
 
@@ -115,6 +121,33 @@ print(sum(1 for m in items if m.strip() != "x"))
 PY
 }
 
+total_count() {
+  python3 - <<PY
+from pathlib import Path
+import re
+
+path = Path("$SPRINT_FILE")
+text = path.read_text(encoding="utf-8")
+items = re.findall(r"^## \[( |x|X)\] ", text, flags=re.M)
+print(len(items))
+PY
+}
+
+current_index() {
+  python3 - <<PY
+from pathlib import Path
+import re
+
+path = Path("$SPRINT_FILE")
+text = path.read_text(encoding="utf-8")
+items = re.findall(r"^## \[( |x|X)\] ", text, flags=re.M)
+remaining = sum(1 for m in items if m.strip() != "x")
+total = len(items)
+current = total - remaining + 1 if remaining > 0 else total
+print(current)
+PY
+}
+
 next_description() {
   python3 - <<PY
 from pathlib import Path
@@ -161,7 +194,8 @@ iteration=1
 while true; do
   remaining="$(remaining_count)"
   if [[ "$remaining" == "0" ]]; then
-    send_telegram "Ralph loop finished all requirements. Session ${SESSION_UUID}."
+    total="$(total_count)"
+    send_telegram "🧭 ~${SESSION_UUID}~"$'\n'"✅ All requirements completed"$'\n'"🎯 ${total} of ${total}"
     echo "All sprint requirements complete."
     echo "<promise>DONE</promise>"
     exit 0
@@ -173,7 +207,9 @@ while true; do
   fi
 
   desc="$(next_description)"
-  send_telegram "Ralph loop starting requirement: ${desc}. Session ${SESSION_UUID}."
+  total="$(total_count)"
+  current="$(current_index)"
+  send_telegram "🧭 ~${SESSION_UUID}~"$'\n'"📌 ${desc}"$'\n'"🎯 ${current} of ${total}"
   echo "Iteration $iteration - next requirement: $desc"
 
   prompt_tmp="$(mktemp)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-ralph",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Ralph Loop sprint runner for Codex.",
   "bin": {
     "ralph-loop": "agent/ralph-loop.sh"