codex-ralph 0.3.0 → 0.3.2

package/README.md

@@ -8,13 +8,35 @@ Minimal Ralph Wiggum Loop runner that feeds a sprint requirement into Codex, one
 npx codex-ralph --sprint=path/to/Sprint_0001.md --max-iterations=1
 ```
 
+## Telegram progress notifications
+
+If you set Telegram credentials, the loop will send progress messages:
+
+```
+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 progress messages.
+
+Message format:
+
+```
+🧭 ~<session-uuid>~
+📌 <current requirement title>
+🎯 <current index> of <total requirements>
+```
+
 ## Sprint format (Markdown)
 
 Each requirement is a level-2 heading with a checkbox. The loop picks the first unchecked item.
 
 ```markdown
 ## [ ] Requirement description
+
 Description: Free-form task details.
+
+Acceptance criteria: Free-form acceptance criteria.
 ```
 
 ## Behavior

package/agent/ralph-loop.sh

@@ -11,6 +11,32 @@ ROOT_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
 SPRINT_FILE=""
 MAX_ITERATIONS=0
 NOTES_FILE=""
+SESSION_UUID=""
+
+session_uuid() {
+  if [[ -n "${SESSION_UUID}" ]]; then
+    echo "${SESSION_UUID}"
+    return
+  fi
+  SESSION_UUID="$(python3 - <<PY
+import uuid
+print(uuid.uuid4())
+PY
+)"
+  echo "${SESSION_UUID}"
+}
+
+send_telegram() {
+  local message="$1"
+  if [[ -z "${CODEX_RALPH_TG_KEY:-}" || -z "${CODEX_RALPH_TG_CHAT:-}" ]]; then
+    return
+  fi
+  curl -sS -o /dev/null -X POST \
+    "https://api.telegram.org/bot${CODEX_RALPH_TG_KEY}/sendMessage" \
+    -d "chat_id=${CODEX_RALPH_TG_CHAT}" \
+    --data-urlencode "text=${message}" \
+    || true
+}
 
 usage() {
   cat <<USAGE
@@ -23,6 +49,8 @@ Options:
 USAGE
 }
 
+session_uuid >/dev/null
+
 for arg in "$@"; do
   case "$arg" in
     --sprint=*)
@@ -87,6 +115,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
@@ -133,6 +188,8 @@ iteration=1
 while true; do
   remaining="$(remaining_count)"
   if [[ "$remaining" == "0" ]]; then
+    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
@@ -144,6 +201,9 @@ while true; do
   fi
 
   desc="$(next_description)"
+  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.0",
+  "version": "0.3.2",
   "description": "Ralph Loop sprint runner for Codex.",
   "bin": {
     "ralph-loop": "agent/ralph-loop.sh"