How to Configure Self-Repair Behavior for Stalled Goals in LoopX: A Complete Guide

LoopX enables automatic goal recovery through three CLI flags (--self-repair-enabled, --self-repair-health, --self-repair-waiting-projection) that trigger re-planning when progress stalls.

The LoopX open-source agent framework includes a built-in self-repair mechanism that detects when goals stop advancing and automatically initiates recovery. This feature prevents agents from wasting cycles on stuck objectives by inserting bounded re-plan segments before new work is selected. Proper configuration requires both enabling the feature at the registry level and ensuring the loopx-self-repair skill is installed.

Core Self-Repair Configuration Flags

All self-repair behavior in LoopX is controlled through the loopx registry admin configure command defined in loopx/cli_commands/registry_admin_configure.py. Three flags determine when and how re-planning occurs:

• --self-repair-enabled — Master toggle for the entire self-repair loop. Defaults to False and must be explicitly enabled.
• --self-repair-health — Minimum health score threshold (0.0–1.0) that the agent must meet before attempting repair. Defaults to 0.7.
• --self-repair-waiting-projection — Number of heartbeat cycles to wait without detecting progress before triggering repair. Defaults to 2.

When a goal stalls for the configured number of cycles, the mechanism in loopx/control_plane/work_items/primary_action.py inserts a bounded self-repair/re-plan segment. This segment executes before the agent selects any new delivery work, ensuring stuck goals are addressed or explicitly abandoned.

Prerequisites: Install the Self-Repair Skill

The self-repair capability ships as a separate skill that must be present in your registry. The installation verification logic in loopx/skill_install_readback.py checks for its presence on startup.

# Verify and install the required skill

loopx skill install loopx-self-repair

Without this skill, the configuration flags will parse but the repair logic will not execute.

CLI Configuration Examples

Apply your desired self-repair settings using the registry admin command:

# Enable with default thresholds

loopx registry admin configure --self-repair-enabled=true

# Custom health threshold and longer grace period

loopx registry admin configure \
    --self-repair-enabled=true \
    --self-repair-health=0.85 \
    --self-repair-waiting-projection=5

The examples/project/configure-goal-smoke.py file in the repository demonstrates these flags in an end-to-end validation test.

Programmatic Configuration Access

Inspect or manipulate self-repair settings from Python using the Registry interface:

from loopx.registry import Registry

reg = Registry.load()

print("Self-repair enabled:", reg.self_repair_enabled)
print("Health threshold:", reg.self_repair_health)
print("Waiting cycles:", reg.self_repair_waiting_projection)

To force a self-repair check manually—useful in testing or debugging scenarios—use the HeartbeatPrompt class from loopx/heartbeat_prompt.py:

from loopx.heartbeat_prompt import HeartbeatPrompt

hb = HeartbeatPrompt()
hb.run_no_progress_self_repair_check()

This method replicates the internal check that runs automatically during the agent's heartbeat loop.

How Self-Repair Integrates with the Control Plane

The self-repair workflow follows a strict sequence defined across multiple modules:

1. Detection — loopx/heartbeat_prompt.py monitors goal progress across each heartbeat cycle.
2. Threshold evaluation — When self_repair_waiting_projection cycles pass without advancement, the system checks self_repair_health.
3. Repair insertion — If health permits, primary_action.py pauses normal work selection and runs the bounded repair segment.
4. Re-planning or abandonment — The repair segment either generates a new plan for the stalled goal or marks it for abandonment.

This design ensures self-repair never interrupts in-flight critical work while preventing indefinite stalls.

Tuning Self-Repair for Production Workloads

Selecting appropriate values depends on your operational constraints:

Scenario	Recommended Settings
Fast-fail development	--self-repair-waiting-projection=1 --self-repair-health=0.9
Resilient long-running tasks	--self-repair-waiting-projection=5 --self-repair-health=0.6
Conservative stability	--self-repair-health=0.95 with default projection

Health thresholds above 0.9 reduce false-positive repairs but may miss recoverable stalls. Waiting projections above 5 increase tolerance for naturally slow goals but delay intervention.

Summary

• Three CLI flags control self-repair: enable toggle, health threshold, and waiting projection cycles.
• loopx-self-repair skill must be installed via loopx skill install before configuration takes effect.
• Source files registry_admin_configure.py, heartbeat_prompt.py, and primary_action.py implement the complete detection and repair pipeline.
• Programmatic access through Registry and HeartbeatPrompt classes supports inspection and manual triggering.

Frequently Asked Questions

What happens if self-repair is enabled but the skill is not installed?

The flags will be accepted and stored in the registry configuration, but the repair logic will silently skip execution. loopx/skill_install_readback.py logs a warning on startup when this mismatch occurs.

Can self-repair trigger multiple times for the same goal?

Yes. Each repair attempt resets the progress tracker. If the new plan also stalls, the counter restarts and another repair cycle may trigger, subject to the same health and projection constraints.

How does the health threshold interact with agent state?

The health score reflects the agent's current operational assessment of itself. A threshold of 0.8 means repair only proceeds when the agent reports 80% or higher confidence in its own state, preventing recovery attempts during systemic degradation.

Where can I observe self-repair activity in logs?

The HeartbeatPrompt class in loopx/heartbeat_prompt.py emits structured log entries at INFO level when no-progress conditions are detected and when repair segments are dispatched. Enable verbose logging with LOG_LEVEL=DEBUG to see full threshold evaluations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}