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

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

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

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

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 tracks registered agents and normalizes agent identities
• 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) normalizes execution policies that govern sub-agent behavior. It compacts raw policy definitions into standardized structures using compact_orchestration_policy():

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) 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) 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) manages goal validation, directory structures, and archival operations with safety checks for registered entries.
• State Projection and Refresh (loopx/state_projection.py, 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, loopx/agent_registry.py) provides JSON-based persistence for goals and normalized agent identity tracking.
• Orchestration (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 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) 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. 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 coordinates the actual execution of work items, making it essential for running goals rather than just defining or archiving them.

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