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

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
State refresh	Reads goal markdown state, updates Next Action section, builds refresh records	refresh_state_run in loopx/state_refresh.py
State projection	Detects gaps between public-safe representation and active state	state_projection_gap_warning in loopx/state_projection.py
Registry	Stores goal metadata, resolves state-file locations, lists registered agents	registry_goals / load_registry in loopx/registry.py
Status server	Exposes HTTP endpoint reporting runtime and registry health	main in loopx/status_server.py
CLI front-ends	Thin wrappers invoking services (loopx refresh-state, loopx status, etc.)	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 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:

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:

# 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	Goal ID validation, runtime root resolution, goal archiving
loopx/state_refresh.py	Core refresh routine, markdown parsing, record building
loopx/state_projection.py	Gap detection and action recommendations
loopx/registry.py	Global registry loading and goal metadata resolution
loopx/status_server.py	HTTP health endpoint implementation
loopx/cli.py	Command-line entry point and argument parsing
loopx/paths.py	Runtime and archive directory location helpers
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 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 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.

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