# Core Modules and Components of LoopX: Runtime, Control Plane, and Registry Explained

> Explore the core LoopX modules: Runtime, Control Plane, and Registry. Understand goal lifecycle, turn-based execution, and agent tracking in this technical deep dive.

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

---

**LoopX organizes its architecture into four distinct layers: a Runtime for goal lifecycle management, a Control Plane for turn-based execution and quota enforcement, State Management components for projection and refresh operations, and Registry modules for agent tracking and JSON-based policy storage.**

LoopX is a lightweight control-plane framework that coordinates long-running agent goals through declarative policies and turn-driven execution logic. The core modules and components of LoopX provide a self-contained system for defining, executing, and archiving autonomous workflows. The architecture clearly separates responsibilities between runtime operations, state persistence, and policy enforcement across the top-level `loopx` package.

## Runtime Module: Goal Lifecycle and Archival

The **Runtime** module in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) handles the loading, validation, and archival of goals. It manages the runtime directory structure and ensures completed goals are safely archived with full reproducibility.

The module provides `archive_runtime_goal()`, which validates goal state before moving it to an archive location:

```python
from loopx.runtime import archive_runtime_goal
from pathlib import Path

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"])

```

This function performs safety checks via the `allow_registered` parameter to prevent accidental archival of active registry entries, and returns a dictionary containing the `archive_path` and operation status.

## State Management: Projection and Refresh

LoopX implements a two-part state management system through **State Projection** and **State Refresh** modules.

**State Projection** ([`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py)) projects the active state of a goal and detects gaps between expected and actual next actions. The `next_action_projection_warning()` function identifies mismatches for human-in-the-loop review:

```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"])

```

**State Refresh** ([`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py)) generates refreshed state snapshots, updates front-matter metadata, and writes shared runtime projections to disk. Together, these modules enable continuous state consistency checks and automated documentation updates.

## Control Plane: Execution Engine and Quotas

The **Control Plane** sub-package (`loopx/control_plane/`) implements the core execution engine that drives goal completion.

The **Turn Driver** ([`loopx/control_plane/turn_driver/driver.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/driver.py)) orchestrates the execution loop, managing work-item contracts and todo processing across agent turns. It coordinates the sequencing of operations according to declarative policies loaded from the registry.

**Quota and Settlement** ([`loopx/control_plane/quota/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/settlement.py)) enforces resource limits and calculates spend. This module writes settlement records to track resource consumption against defined quotas, preventing runaway execution through hard limits on compute or API usage.

## Registry and Agent Management

The **Registry** system provides persistent storage and lookup capabilities for goals and agent configurations.

**Registry I/O** ([`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)) handles JSON-based registry operations through `read_json()` and `find_registry_goal()`. It resolves paths, normalizes registry structures, and provides utilities for safe writes with private-data scrubbing capabilities:

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

registry_path = Path("/path/to/registry.json")
registry = read_json(registry_path)
goal = find_registry_goal(registry, "my-goal-id")
print(goal["description"])

```

**Agent Identity** is managed through two complementary modules:
- [`loopx/agent_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_registry.py) tracks registered agents and normalizes agent identities
- [`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 components maintain a canonical record of agent capabilities and lifecycle states within the registry structure.

## Orchestration and Policy Configuration

The **Orchestration** module ([`loopx/orchestration.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/orchestration.py)) normalizes execution policies that govern sub-agent behavior. It compacts raw policy definitions into standardized structures using `compact_orchestration_policy()`:

```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)

```

This processing enforces constraints on spawn limits, sub-agent execution modes, and explore-harness profiles (such as `adaptive-resilient`), ensuring that agent trees respect organizational boundaries and resource policies defined in the registry.

## CLI and Observability Interfaces

LoopX exposes user-facing interaction points through **Slash Commands** and a **Status Server**.

**Slash Commands** ([`loopx/slash_commands.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/slash_commands.py)) provide the CLI entry points for installing, querying, and managing goals from the terminal. These commands wrap the core Python API into shell-accessible operations.

**Status Server** ([`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py)) runs a lightweight HTTP endpoint that surfaces current LoopX status. This enables external monitoring tools and dashboards to query the health and state of active goals without accessing the filesystem directly.

## Summary

The core modules and components of LoopX work together to provide a complete agent coordination platform:

- **Runtime** ([`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py)) manages goal validation, directory structures, and archival operations with safety checks for registered entries.
- **State Projection and Refresh** ([`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py), [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py)) enable continuous state monitoring, mismatch detection, and automated markdown reporting.
- **Control Plane** (`loopx/control_plane/`) contains the turn driver execution loop and quota enforcement systems that prevent resource overconsumption.
- **Registry System** ([`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py), [`loopx/agent_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_registry.py)) provides JSON-based persistence for goals and normalized agent identity tracking.
- **Orchestration** ([`loopx/orchestration.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/orchestration.py)) compacts and validates policies governing sub-agent behavior and resource limits.

## Frequently Asked Questions

### What is the primary responsibility of the LoopX Runtime?

The Runtime module in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) manages the entire goal lifecycle outside of active execution, including loading goals from disk, validating their structure, managing the runtime working directory, and archiving completed goals through the `archive_runtime_goal()` function. It ensures that completed work is preserved immutably while preventing accidental modification of registered active goals.

### How does LoopX detect state mismatches during execution?

LoopX uses the State Projection module ([`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py)) to compare the active state next-action against the latest run's recommended action and agent lane expectations. The `next_action_projection_warning()` function returns structured warning objects when these projections diverge, enabling human-in-the-loop intervention before execution continues on inconsistent state.

### Where are resource quotas and spending tracked in LoopX?

Resource quotas are enforced within the Control Plane sub-package, specifically 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 registered quota limits and writes settlement records to track consumption. The turn driver consults these quotas before scheduling additional work items to prevent budget overruns.

### Can LoopX operate without the Control Plane components?

While the Runtime, Registry, and State Management modules can function independently for goal definition and archival, the Control Plane (`loopx/control_plane/`) is required for active execution. The turn driver in [`loopx/control_plane/turn_driver/driver.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/driver.py) coordinates the actual execution of work items, making it essential for running goals rather than just defining or archiving them.