# How to Debug LoopX: A Complete Guide to Troubleshooting the AI-Agent Orchestration Framework

> Debug LoopX easily with this comprehensive guide. Master dry-run flags, status server, and layered architecture for efficient AI agent orchestration troubleshooting.

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

---

**Debug LoopX effectively by leveraging its dry-run flags, status server endpoints, and layered architecture—trace issues from CLI validation through runtime resolution to state file parsing.**

LoopX is a modular AI-agent orchestration framework built around a **runtime directory**, a **global registry**, and CLI commands that manipulate goal state. Knowing how these components interact makes debugging straightforward. This guide walks you through the architecture, common failure modes, and practical troubleshooting techniques based on the `huangruiteng/loopx` source code.

## Understanding LoopX Core Architecture

LoopX organizes functionality into discrete layers. When something breaks, you can trace the problem through these five core components:

| Component | Responsibility | Key Source File |
|-----------|--------------|---------------|
| **Runtime manager** | Resolves active runtime root, validates goal IDs, archives completed goals | `archive_runtime_goal` in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) |
| **State refresh** | Reads goal markdown state, updates *Next Action* section, builds refresh records | `refresh_state_run` in [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) |
| **State projection** | Detects gaps between public-safe representation and active state | `state_projection_gap_warning` in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) |
| **Registry** | Stores goal metadata, resolves state-file locations, lists registered agents | `registry_goals` / `load_registry` in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) |
| **Status server** | Exposes HTTP endpoint reporting runtime and registry health | `main` in [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) |
| **CLI front-ends** | Thin wrappers invoking services (`loopx refresh-state`, `loopx status`, etc.) | [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) |

## The Five-Layer Debugging Workflow to Debug LoopX

Trace any issue through these layers, from surface symptoms to root cause.

### 1. CLI Invocation Layer

Verify arguments like `--dry-run` and `--goal-id`. The CLI performs early validation through `validate_goal_id_path_segment` and `validate_public_safe_text`. Errors at this layer indicate malformed user input.

### 2. Runtime Path Resolution Layer

The runtime root derives from the registry via `resolve_runtime_root`. If a goal directory is missing, inspect the [`registry.json`](https://github.com/huangruiteng/loopx/blob/main/registry.json) entry directly. Use `loopx status --verbose` to print resolved paths.

### 3. State File Parsing Layer

Functions like `parse_frontmatter`, `extract_section_lines`, and `replace_next_action_section` manipulate markdown. Failures here typically stem from malformed frontmatter or missing `## Next Action` headings.

### 4. Projection and Repair Layer

`state_projection_gap_warning` highlights todo-expansion gaps. If you see `requires_todo_expansion` in markdown output, investigate the *Agent Todo* section of the state file.

### 5. Status Server Layer

The HTTP `/status` endpoint mirrors `loopx status` output. Query it directly:

```bash
curl http://localhost:8000/status | jq .

```

## Common Debugging Scenarios and Solutions

| Situation | Recommended Action | Why It Works |
|-----------|------------------|--------------|
| **Unexpected classification** | Run `loopx refresh-state --dry-run` and inspect generated markdown for "classification" | Dry-run bypasses state mutation, revealing classification logic |
| **Goal directory not found** | Verify `registry_goals` entry and `resolve_runtime_root`; use `loopx status --verbose` | Runtime raises `FileNotFoundError` only after failing to locate `runtime/goals/<goal-id>` |
| **Next Action not updating** | Check `replace_next_action_section` return value `(new_text, updated_flag)` | When `dry_run=True`, function returns updated text without writing; `False` flag means section already matches |
| **Projection gap persists** | Examine `state_projection_gap_warning` warning object for `requires_todo_expansion`, `user_open`, `agent_open` | Projection collapses gaps only after parsing todos cleanly |
| **Global registry sync fails** | Inspect `runtime_projection_route` object via `compact_runtime_projection_route` | Route status `"missing"` or `"single_runtime"` disables global sync intentionally |
| **Performance bottlenecks** | Enable status server (`loopx status-server &`) and monitor `runtime_projection_route.projection_enabled` | Server aggregates metrics without re-invoking full refresh pipeline |

## Practical Code Examples to Debug LoopX

These commands demonstrate the complete debugging workflow:

```bash

# Dry-run a state refresh—see every decision without touching files

loopx refresh-state \
    --registry /path/to/registry.json \
    --goal-id my-goal \
    --dry-run \
    --classification "state_refreshed"

# Inspect the generated markdown output

cat /tmp/loopx/run-20231101T120000Z/refresh-state.md | less

# Start status server and query for JSON runtime snapshot

loopx status-server &
curl http://localhost:8000/status | jq .

# Archive workflow: dry-run first, then execute

loopx archive-goal \
    --registry /path/to/registry.json \
    --goal-id my-goal \
    --dry-run

# Execute after verification

loopx archive-goal \
    --registry /path/to/registry.json \
    --goal-id my-goal \
    --execute

```

## Key Source Files for Debugging

Start your investigation at the CLI wrapper, follow calls into `state_refresh.run`, then into lower-level helpers:

| File | Purpose |
|------|---------|
| [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) | Goal ID validation, runtime root resolution, goal archiving |
| [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) | Core refresh routine, markdown parsing, record building |
| [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) | Gap detection and action recommendations |
| [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) | Global registry loading and goal metadata resolution |
| [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) | HTTP health endpoint implementation |
| [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) | Command-line entry point and argument parsing |
| [`loopx/paths.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/paths.py) | Runtime and archive directory location helpers |
| [`loopx/feedback.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/feedback.py) | Public-safe vs. local-control text validation |

## Summary

- **Debug LoopX systematically** by tracing through five layers: CLI → runtime → state parsing → projection → status server
- **Use `--dry-run` flags** extensively to inspect logic without mutating state
- **Query the status server** via HTTP for lightweight runtime health checks
- **Inspect return tuples** from functions like `replace_next_action_section` to verify whether updates occurred
- **Validate registry entries** in [`registry.json`](https://github.com/huangruiteng/loopx/blob/main/registry.json) when paths fail to resolve

## Frequently Asked Questions

### How do I debug LoopX without modifying any files?

Use the `--dry-run` flag on any mutating command. In `loopx refresh-state --dry-run`, the system generates all intermediate outputs—including the refreshed markdown—to temporary directories without writing to goal state files. You can then inspect these temporary files to verify classification logic and next-action generation.

### Why does LoopX say my goal directory is missing when it exists?

The runtime manager resolves paths through `resolve_runtime_root` based on registry entries, not filesystem scanning. Check that your [`registry.json`](https://github.com/huangruiteng/loopx/blob/main/registry.json) contains the correct goal entry via `registry_goals`, and verify with `loopx status --verbose` to see the exact path resolution. Mismatches between registry paths and actual directory locations cause this error.

### What does `requires_todo_expansion` mean in LoopX output?

This flag from `state_projection_gap_warning` indicates that the *Agent Todo* section contains unparsed or malformed bullet lines. The projection logic cannot collapse gaps until todos parse cleanly. Inspect the markdown state file's todo section for formatting issues like inconsistent indentation or missing bullet characters.