# Core Components of LoopX: Architecture and Module Breakdown

> Discover the core components of LoopX: Registry, Control Plane, and Runtime. Understand its architecture and module breakdown for declarative policies and efficient execution.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: architecture
- Published: 2026-08-15

---

**LoopX consists of three primary architectural layers: a JSON-based Registry for declarative policies, a Control Plane with a turn-driver execution engine and quota management, and a Runtime layer handling state projection, persistence, and goal archival.**

LoopX is a lightweight, open-source control-plane framework designed to coordinate long-running agent goals through declarative policies and stateful execution. According to the huangruiteng/loopx source code, the framework organizes its core components into distinct modules that separate policy definitions from execution logic. Understanding these components is essential for extending the system or debugging agent orchestration flows.

## Runtime Layer: State Management and Goal Lifecycle

The Runtime layer handles the persistence, validation, and archival of goals throughout their lifecycle.

### Runtime Module (loopx/runtime.py)

The [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) module serves as the primary interface for loading and validating goals, managing the runtime directory structure, and archiving completed goals. It provides the `archive_runtime_goal` function for safely moving finished goals to archival storage while maintaining reproducible history.

```python
from loopx.runtime import archive_runtime_goal

result = archive_runtime_goal(
    registry_path=Path("/path/to/registry.json"),
    runtime_root_override=None,
    goal_id="my-goal-id",
    archive_root=Path("~/loopx-archive"),
    allow_registered=False,
    execute=True,          # Set False for a dry‑run

)
print(result["archive_path"])

```

### State Projection (loopx/state_projection.py)

State projection monitors the active state of executing goals and detects mismatches between intended and actual next actions. The `next_action_projection_warning` function in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) compares the active state's next action against the latest run's recommended action and the agent lane's intended action, generating warnings when discrepancies occur.

```python
from loopx.state_projection import next_action_projection_warning

warning = next_action_projection_warning(
    active_state_next_action="run analysis",
    latest_run_recommended_action="run analysis",
    agent_lane_next_action=None,
)

if warning:
    print("⚠️ Projection mismatch:", warning["message"])
else:
    print("✅ Projections aligned")

```

### State Refresh (loopx/state_refresh.py)

The [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) module generates refreshed state snapshots, updates front-matter metadata, and writes shared runtime projections. This ensures that the current state remains synchronized across different views of the system.

## Control Plane: Execution Engine and Resource Management

The Control Plane implements the core execution logic, managing how agents take turns, consume resources, and adhere to orchestration policies.

### Turn Driver (loopx/control_plane/turn_driver/driver.py)

At the heart of the Control Plane is the turn driver located in [`loopx/control_plane/turn_driver/driver.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/driver.py). This module implements the core execution loop that coordinates agent turns, manages work-item contracts, and processes todo items. It acts as the central dispatcher for agent activities.

### Quota and Settlement (loopx/control_plane/quota/settlement.py)

Resource limits are enforced through the quota system in [`loopx/control_plane/quota/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/settlement.py). This module tracks resource consumption, calculates spend, and writes settlement records to prevent budget overruns. The settlement system ensures that agents operate within defined financial or computational constraints.

### Orchestration Policies (loopx/orchestration.py)

The [`loopx/orchestration.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/orchestration.py) module normalizes orchestration policies such as spawn limits, sub-agent modes, and explore-harness profiles. The `compact_orchestration_policy` function standardizes raw policy dictionaries into a consistent format for the execution engine.

```python
from loopx.orchestration import compact_orchestration_policy

raw_policy = {
    "allowed": True,
    "max_children": "3",
    "explore_harness": {"enabled": True, "profile": "adaptive-resilient"},
}
compact = compact_orchestration_policy(raw_policy)
print(compact)

```

## Registry and Agent Management

Declarative configuration and agent identity management are handled through the Registry components.

### JSON Registry (loopx/registry.py)

The [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) module manages the JSON-based registry that stores goal definitions, capabilities, and quotas. It provides utilities for goal lookup, path resolution, and safe write operations through functions like `read_json` and `find_registry_goal`.

```python
from loopx.registry import read_json, find_registry_goal

# Load the top‑level registry JSON file

registry_path = Path("/path/to/registry.json")
registry = read_json(registry_path)

# Look up a goal by its ID

goal = find_registry_goal(registry, "my-goal-id")
print(goal["description"])

```

### Agent Registry and Onboarding (loopx/agent_registry.py & loopx/agent_onboarding.py)

Agent identities are tracked and normalized through [`loopx/agent_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_registry.py), while [`loopx/agent_onboarding.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_onboarding.py) handles the initialization flow for new agents entering the system. These modules ensure that only properly registered and validated agents can participate in the execution loop.

## Interfaces and System Utilities

LoopX exposes management capabilities through CLI commands and provides observability through a lightweight HTTP server.

### Slash Commands and CLI (loopx/slash_commands.py)

User-facing interaction occurs through [`loopx/slash_commands.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/slash_commands.py), which exposes commands for installing goals, querying status, and managing the LoopX environment. These commands serve as the primary administrative interface for the framework.

### Status Server (loopx/status_server.py)

For real-time monitoring, [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) provides a lightweight HTTP endpoint that surfaces current LoopX status. This enables external tools and dashboards to observe system health without directly accessing the runtime state.

### Helper Utilities (loopx/paths.py)

Supporting functionality resides in [`loopx/paths.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/paths.py) and related utility modules, handling path resolution, markdown rendering, file locking, and other cross-cutting concerns required by the core components.

## Summary

- **Runtime Layer**: Manages goal persistence and archival through [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), with state projection and refresh capabilities in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) and [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py).
- **Control Plane**: Houses the turn-driver execution engine in [`loopx/control_plane/turn_driver/driver.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/driver.py) and resource enforcement via [`loopx/control_plane/quota/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/settlement.py), alongside orchestration policy normalization.
- **Registry System**: Provides JSON-based goal storage and lookup through [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py), with agent identity management split between [`loopx/agent_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_registry.py) and [`loopx/agent_onboarding.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_onboarding.py).
- **Interfaces**: Exposes management commands via [`loopx/slash_commands.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/slash_commands.py) and operational visibility through [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py).

## Frequently Asked Questions

### What is the primary function of the LoopX turn driver?

The turn driver, implemented in [`loopx/control_plane/turn_driver/driver.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/driver.py), serves as the central execution engine that coordinates agent turns, processes work-item contracts, and manages the todo queue. It implements the core control loop that determines which agent acts next and validates that actions comply with established policies and quotas.

### How does LoopX handle completed or stale goals?

Completed goals are processed through the `archive_runtime_goal` function in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), which safely moves goal data from the active runtime directory to a configurable archive location. This archival process preserves the full execution history while freeing runtime resources, supporting both dry-run validation and destructive execution modes.

### What mechanism prevents agents from exceeding resource limits?

LoopX enforces resource constraints through the quota system located in [`loopx/control_plane/quota/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/settlement.py). This module calculates real-time spend against defined limits and writes settlement records that block further execution when thresholds are reached, ensuring agents operate within budgetary and computational boundaries.

### How are agent identities managed in LoopX?

Agent identities are normalized and tracked through [`loopx/agent_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_registry.py), which maintains a registry of valid agents, while [`loopx/agent_onboarding.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_onboarding.py) handles the registration workflow for new agents. This separation ensures that agents must complete onboarding validation before being recognized by the turn driver and registry systems.