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

> Configure self-repair for stalled LoopX goals. Learn how to automatically recover by enabling self-repair with three CLI flags for seamless goal re-planning and progress.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/skill_install_readback.py) checks for its presence on startup.

```bash

# 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:

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/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:

```python
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/heartbeat_prompt.py):

```python
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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/registry_admin_configure.py), [`heartbeat_prompt.py`](https://github.com/huangruiteng/loopx/blob/main/heartbeat_prompt.py), and [`primary_action.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.