codex-ralph 0.3.0 → 0.3.1

package/README.md

@@ -8,13 +8,27 @@ 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 start/transition/finish messages.
+
 ## 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=*)
@@ -133,6 +161,7 @@ iteration=1
 while true; do
   remaining="$(remaining_count)"
   if [[ "$remaining" == "0" ]]; then
+    send_telegram "Ralph loop finished all requirements. Session ${SESSION_UUID}."
     echo "All sprint requirements complete."
     echo "<promise>DONE</promise>"
     exit 0
@@ -144,6 +173,7 @@ while true; do
   fi
 
   desc="$(next_description)"
+  send_telegram "Ralph loop starting requirement: ${desc}. Session ${SESSION_UUID}."
   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.1",
   "description": "Ralph Loop sprint runner for Codex.",
   "bin": {
     "ralph-loop": "agent/ralph-loop.sh"