coder-config 0.40.16 → 0.41.2

package/README.md

@@ -16,6 +16,7 @@ One tool to configure all your AI coding assistants:
 | **Rules & Commands** | Manage project-specific guidelines |
 | **Memory** | Persistent context across sessions |
 | **Workstreams** | Group projects with shared context |
+| **Ralph Loops** | Autonomous development until task completion |
 
 ## Installation
 
@@ -157,6 +158,47 @@ coder-config workstream install-hook --codex
 coder-config workstream install-hook --all
 ```
 
+### Loop Commands (Ralph Loop)
+
+Ralph Loops enable autonomous development - Claude Code runs continuously until a task is completed.
+
+```bash
+coder-config loop                           # List all loops
+coder-config loop create "Task description" # Create new loop
+coder-config loop create "Task" --workstream <name>  # Create loop in workstream context
+coder-config loop start <id>                # Start/resume a loop
+coder-config loop pause <id>                # Pause loop at next safe point
+coder-config loop resume <id>               # Resume paused loop
+coder-config loop cancel <id>               # Cancel loop
+coder-config loop delete <id>               # Delete loop and its data
+coder-config loop approve <id>              # Approve plan (when in plan phase)
+coder-config loop complete <id>             # Mark loop as complete
+coder-config loop status [id]               # Show status (active loop if no id)
+coder-config loop active                    # Show current active loop
+coder-config loop history                   # Show completed loops
+coder-config loop config                    # Show loop configuration
+coder-config loop config --max-iterations 50    # Set max iterations
+coder-config loop config --max-cost 10.00       # Set max cost budget
+coder-config loop config --auto-approve-plan    # Skip manual plan approval
+```
+
+**Three-Phase Workflow**:
+1. **Clarify** - Claude asks questions to understand requirements
+2. **Plan** - Claude creates an implementation plan (requires approval)
+3. **Execute** - Claude implements the plan until complete
+
+**Running a loop**:
+```bash
+export CODER_LOOP_ID=<id>
+claude --continue "Your task description"
+```
+
+**Safety mechanisms**:
+- Iteration limits (default: 50)
+- Cost budget caps (default: $10)
+- Phase gates (manual plan approval)
+- Graceful pause on budget exceeded
+
 ### Registry Commands
 
 ```bash

package/config-loader.js

@@ -30,6 +30,7 @@ const { envList, envSet, envUnset } = require('./lib/env');
 const { getProjectsRegistryPath, loadProjectsRegistry, saveProjectsRegistry, projectList, projectAdd, projectRemove } = require('./lib/projects');
 const { getWorkstreamsPath, loadWorkstreams, saveWorkstreams, workstreamList, workstreamCreate, workstreamUpdate, workstreamDelete, workstreamUse, workstreamActive, workstreamAddProject, workstreamRemoveProject, workstreamInject, workstreamDetect, workstreamGet, getActiveWorkstream, countWorkstreamsForProject, workstreamInstallHook, workstreamInstallHookGemini, workstreamInstallHookCodex, workstreamDeactivate, workstreamCheckPath } = require('./lib/workstreams');
 const { getActivityPath, getDefaultActivity, loadActivity, saveActivity, detectProjectRoot, activityLog, activitySummary, generateWorkstreamName, activitySuggestWorkstreams, activityClear } = require('./lib/activity');
+const { getLoopsPath, loadLoops, saveLoops, loadLoopState, saveLoopState, loadHistory, saveHistory, loopList, loopCreate, loopGet, loopUpdate, loopDelete, loopStart, loopPause, loopResume, loopCancel, loopApprove, loopComplete, loopStatus, loopHistory, loopConfig, getActiveLoop, recordIteration, saveClarifications, savePlan, loadClarifications, loadPlan, loopInject, archiveLoop } = require('./lib/loops');
 const { runCli } = require('./lib/cli');
 
 class ClaudeConfigManager {
@@ -148,6 +149,37 @@ class ClaudeConfigManager {
   workstreamDeactivate() { return workstreamDeactivate(); }
   workstreamCheckPath(targetPath, silent) { return workstreamCheckPath(this.installDir, targetPath, silent); }
 
+  // Loops (Ralph Loop)
+  getLoopsPath() { return getLoopsPath(this.installDir); }
+  loadLoops() { return loadLoops(this.installDir); }
+  saveLoops(data) { return saveLoops(this.installDir, data); }
+  loadLoopState(loopId) { return loadLoopState(this.installDir, loopId); }
+  saveLoopState(loopId, state) { return saveLoopState(this.installDir, loopId, state); }
+  loadHistory() { return loadHistory(this.installDir); }
+  saveHistory(data) { return saveHistory(this.installDir, data); }
+  loopList() { return loopList(this.installDir); }
+  loopCreate(task, options) { return loopCreate(this.installDir, task, options); }
+  loopGet(idOrName) { return loopGet(this.installDir, idOrName); }
+  loopUpdate(idOrName, updates) { return loopUpdate(this.installDir, idOrName, updates); }
+  loopDelete(idOrName) { return loopDelete(this.installDir, idOrName); }
+  loopStart(idOrName) { return loopStart(this.installDir, idOrName); }
+  loopPause(idOrName) { return loopPause(this.installDir, idOrName); }
+  loopResume(idOrName) { return loopResume(this.installDir, idOrName); }
+  loopCancel(idOrName) { return loopCancel(this.installDir, idOrName); }
+  loopApprove(idOrName) { return loopApprove(this.installDir, idOrName); }
+  loopComplete(idOrName) { return loopComplete(this.installDir, idOrName); }
+  loopStatus(idOrName) { return loopStatus(this.installDir, idOrName); }
+  loopHistory() { return loopHistory(this.installDir); }
+  loopConfig(updates) { return loopConfig(this.installDir, updates); }
+  getActiveLoop() { return getActiveLoop(this.installDir); }
+  recordIteration(loopId, iteration) { return recordIteration(this.installDir, loopId, iteration); }
+  saveClarifications(loopId, content) { return saveClarifications(this.installDir, loopId, content); }
+  savePlan(loopId, content) { return savePlan(this.installDir, loopId, content); }
+  loadClarifications(loopId) { return loadClarifications(this.installDir, loopId); }
+  loadPlan(loopId) { return loadPlan(this.installDir, loopId); }
+  loopInject(silent) { return loopInject(this.installDir, silent); }
+  archiveLoop(loopId) { return archiveLoop(this.installDir, loopId); }
+
   // Activity
   getActivityPath() { return getActivityPath(this.installDir); }
   loadActivity() { return loadActivity(this.installDir); }

package/hooks/ralph-loop-preprompt.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Ralph Loop context injection hook
+# Called at the start of each Claude session to inject loop context
+#
+# This hook:
+# 1. Checks if we're in an active loop (via CODER_LOOP_ID env var)
+# 2. Reads the current loop state
+# 3. Outputs loop context including task, phase, clarifications, and plan
+
+LOOP_ID="$CODER_LOOP_ID"
+if [[ -z "$LOOP_ID" ]]; then
+  exit 0
+fi
+
+STATE_FILE="$HOME/.coder-config/loops/$LOOP_ID/state.json"
+PLAN_FILE="$HOME/.coder-config/loops/$LOOP_ID/plan.md"
+CLARIFY_FILE="$HOME/.coder-config/loops/$LOOP_ID/clarifications.md"
+
+if [[ ! -f "$STATE_FILE" ]]; then
+  echo "Warning: Loop state file not found: $STATE_FILE"
+  exit 0
+fi
+
+# Read loop state
+NAME=$(jq -r '.name' "$STATE_FILE")
+PHASE=$(jq -r '.phase' "$STATE_FILE")
+STATUS=$(jq -r '.status' "$STATE_FILE")
+CURRENT_ITER=$(jq -r '.iterations.current // 0' "$STATE_FILE")
+MAX_ITER=$(jq -r '.iterations.max // 50' "$STATE_FILE")
+TASK=$(jq -r '.task.original' "$STATE_FILE")
+CLARIFIED_TASK=$(jq -r '.task.clarified // empty' "$STATE_FILE")
+
+echo "<ralph-loop-context>"
+echo "# Ralph Loop: $NAME"
+echo ""
+echo "**Phase:** $PHASE"
+echo "**Status:** $STATUS"
+echo "**Iteration:** $CURRENT_ITER / $MAX_ITER"
+echo ""
+echo "## Original Task"
+echo "$TASK"
+echo ""
+
+if [[ -n "$CLARIFIED_TASK" && "$CLARIFIED_TASK" != "null" ]]; then
+  echo "## Clarified Task"
+  echo "$CLARIFIED_TASK"
+  echo ""
+fi
+
+if [[ -f "$CLARIFY_FILE" ]]; then
+  echo "## Clarifications"
+  cat "$CLARIFY_FILE"
+  echo ""
+fi
+
+if [[ -f "$PLAN_FILE" ]]; then
+  echo "## Implementation Plan"
+  cat "$PLAN_FILE"
+  echo ""
+fi
+
+echo "## Loop Instructions"
+echo ""
+echo "You are operating within a Ralph Loop - an autonomous development workflow."
+echo "Your current phase is: **$PHASE**"
+echo ""
+
+case "$PHASE" in
+  "clarify")
+    echo "### Clarify Phase"
+    echo "- Ask questions to fully understand the requirements"
+    echo "- Gather any missing information needed for implementation"
+    echo "- Document Q&A in clarifications.md"
+    echo "- When requirements are clear, advance to 'plan' phase"
+    ;;
+  "plan")
+    echo "### Plan Phase"
+    echo "- Review the clarified requirements"
+    echo "- Create a detailed implementation plan"
+    echo "- Break down work into clear steps"
+    echo "- Save the plan to plan.md"
+    echo "- Wait for approval before advancing to 'execute' phase"
+    ;;
+  "execute")
+    echo "### Execute Phase"
+    echo "- Follow the implementation plan step by step"
+    echo "- Implement the required changes"
+    echo "- Test your work"
+    echo "- When complete, set taskComplete=true in state.json"
+    ;;
+esac
+
+echo ""
+echo "## State File Location"
+echo "$STATE_FILE"
+echo "</ralph-loop-context>"

package/hooks/ralph-loop-stop.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Ralph Loop continuation hook
+# Called after each Claude response to manage loop continuation
+#
+# This hook:
+# 1. Checks if we're in an active loop (via CODER_LOOP_ID env var)
+# 2. Verifies the loop is still running
+# 3. Checks budget limits (iterations and cost)
+# 4. Updates iteration count
+# 5. Outputs continuation prompt based on current phase
+
+LOOP_ID="$CODER_LOOP_ID"
+if [[ -z "$LOOP_ID" ]]; then
+  exit 0
+fi
+
+STATE_FILE="$HOME/.coder-config/loops/$LOOP_ID/state.json"
+if [[ ! -f "$STATE_FILE" ]]; then
+  exit 0
+fi
+
+# Check if loop is still active
+STATUS=$(jq -r '.status' "$STATE_FILE")
+if [[ "$STATUS" != "running" ]]; then
+  exit 0
+fi
+
+# Check budget limits
+CURRENT_ITER=$(jq -r '.iterations.current' "$STATE_FILE")
+MAX_ITER=$(jq -r '.iterations.max' "$STATE_FILE")
+CURRENT_COST=$(jq -r '.budget.currentCost // 0' "$STATE_FILE")
+MAX_COST=$(jq -r '.budget.maxCost // 10' "$STATE_FILE")
+
+# Check iteration limit
+if (( CURRENT_ITER >= MAX_ITER )); then
+  echo "Loop paused: max iterations reached ($MAX_ITER)"
+  jq '.status = "paused" | .pauseReason = "max_iterations" | .updatedAt = (now | todate)' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+  exit 0
+fi
+
+# Check cost limit (using bc for floating point comparison)
+if command -v bc &> /dev/null; then
+  if (( $(echo "$CURRENT_COST >= $MAX_COST" | bc -l) )); then
+    echo "Loop paused: budget exceeded (\$$MAX_COST)"
+    jq '.status = "paused" | .pauseReason = "budget" | .updatedAt = (now | todate)' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Update iteration count
+NEW_ITER=$((CURRENT_ITER + 1))
+jq ".iterations.current = $NEW_ITER | .updatedAt = (now | todate)" "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+
+# Check if task is complete (Claude sets this flag)
+PHASE=$(jq -r '.phase' "$STATE_FILE")
+TASK_COMPLETE=$(jq -r '.taskComplete // false' "$STATE_FILE")
+
+if [[ "$TASK_COMPLETE" == "true" ]]; then
+  jq '.status = "completed" | .completedAt = (now | todate) | .updatedAt = (now | todate)' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+  echo ""
+  echo "---"
+  echo "[Ralph Loop COMPLETED]"
+  echo "Task has been marked as complete."
+  echo "---"
+  exit 0
+fi
+
+# Continue loop - output continuation prompt based on phase
+PHASE_PROMPT=""
+case "$PHASE" in
+  "clarify")
+    PHASE_PROMPT="Continue clarifying requirements. Ask any remaining questions needed to fully understand the task.
+
+If requirements are now clear:
+1. Save clarifications to ~/.coder-config/loops/$LOOP_ID/clarifications.md
+2. Update state: jq '.phase = \"plan\"' to advance to planning phase"
+    ;;
+  "plan")
+    PHASE_PROMPT="Continue developing the implementation plan based on clarified requirements.
+
+When the plan is complete:
+1. Save the plan to ~/.coder-config/loops/$LOOP_ID/plan.md
+2. Wait for user approval before advancing to execute phase
+3. If auto-approve is enabled, update state: jq '.phase = \"execute\"'"
+    ;;
+  "execute")
+    PHASE_PROMPT="Continue executing the implementation plan.
+
+When the task is complete:
+1. Verify all requirements have been met
+2. Run any relevant tests
+3. Update state: jq '.taskComplete = true' to mark as complete"
+    ;;
+esac
+
+echo ""
+echo "---"
+echo "[Ralph Loop iteration $NEW_ITER/$MAX_ITER - Phase: $PHASE]"
+echo ""
+echo "$PHASE_PROMPT"
+echo "---"

package/lib/cli.js

@@ -149,6 +149,63 @@ function runCli(manager) {
       }
       break;
 
+    // Loops (Ralph Loop)
+    case 'loop':
+    case 'loops':
+      if (args[1] === 'create' || args[1] === 'new') {
+        const task = args.slice(2).join(' ');
+        const wsIdx = args.indexOf('--workstream');
+        const workstreamId = wsIdx !== -1 ? args[wsIdx + 1] : null;
+        manager.loopCreate(task, { workstreamId });
+      } else if (args[1] === 'start') {
+        manager.loopStart(args[2]);
+      } else if (args[1] === 'pause') {
+        manager.loopPause(args[2]);
+      } else if (args[1] === 'resume') {
+        manager.loopResume(args[2]);
+      } else if (args[1] === 'cancel') {
+        manager.loopCancel(args[2]);
+      } else if (args[1] === 'approve') {
+        manager.loopApprove(args[2]);
+      } else if (args[1] === 'complete') {
+        manager.loopComplete(args[2]);
+      } else if (args[1] === 'delete' || args[1] === 'rm') {
+        manager.loopDelete(args[2]);
+      } else if (args[1] === 'status') {
+        manager.loopStatus(args[2]);
+      } else if (args[1] === 'history') {
+        manager.loopHistory();
+      } else if (args[1] === 'config') {
+        const updates = {};
+        const maxIterIdx = args.indexOf('--max-iterations');
+        if (maxIterIdx !== -1) updates.maxIterations = args[maxIterIdx + 1];
+        const maxCostIdx = args.indexOf('--max-cost');
+        if (maxCostIdx !== -1) updates.maxCost = args[maxCostIdx + 1];
+        if (args.includes('--auto-approve-plan')) updates.autoApprovePlan = true;
+        if (args.includes('--no-auto-approve-plan')) updates.autoApprovePlan = false;
+        if (Object.keys(updates).length > 0) {
+          manager.loopConfig(updates);
+        } else {
+          manager.loopConfig();
+        }
+      } else if (args[1] === 'inject') {
+        const silent = args.includes('--silent') || args.includes('-s');
+        manager.loopInject(silent);
+      } else if (args[1] === 'active') {
+        const loop = manager.getActiveLoop();
+        if (loop) {
+          console.log(`Active: ${loop.name}`);
+          console.log(`  Phase: ${loop.phase}`);
+          console.log(`  Status: ${loop.status}`);
+          console.log(`  Iteration: ${loop.iterations.current}/${loop.iterations.max}`);
+        } else {
+          console.log('No active loop');
+        }
+      } else {
+        manager.loopList();
+      }
+      break;
+
     // Maintenance
     case 'update':
       manager.update(args.slice(1)).catch(err => {
@@ -232,6 +289,30 @@ Workstream Commands:
   Per-session activation (enables parallel work):
     export CODER_WORKSTREAM=<name-or-id>
 
+Loop Commands (Ralph Loop - autonomous development):
+  loop                       List all loops
+  loop create "Task"         Create new loop with task description
+  loop create "Task" --workstream <name>  Create loop in workstream context
+  loop start <id>            Start/resume a loop
+  loop pause <id>            Pause loop at next safe point
+  loop resume <id>           Resume paused loop
+  loop cancel <id>           Cancel loop
+  loop delete <id>           Delete loop and its data
+  loop approve <id>          Approve plan (when in plan phase)
+  loop complete <id>         Mark loop as complete
+  loop status [id]           Show status (active loop if no id)
+  loop active                Show current active loop
+  loop history               Show completed loops
+  loop config                Show loop configuration
+  loop config --max-iterations 50    Set max iterations
+  loop config --max-cost 10.00       Set max cost budget
+  loop config --auto-approve-plan    Skip manual plan approval
+  loop inject [--silent]     Output loop context (for hooks)
+
+  Running a loop with Claude Code:
+    export CODER_LOOP_ID=<id>
+    claude --continue "Your task"
+
 Registry Commands:
   registry                       List MCPs in global registry
   registry add <name> '<json>'   Add MCP to global registry

package/lib/constants.js

@@ -2,7 +2,7 @@
  * Constants and tool path configurations
  */
 
-const VERSION = '0.40.16';
+const VERSION = '0.41.2';
 
 // Tool-specific path configurations
 const TOOL_PATHS = {