Core Components of LoopX: Architecture and Module Breakdown

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

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

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

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

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, while 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, 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 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 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, with state projection and refresh capabilities in loopx/state_projection.py and loopx/state_refresh.py.
• Control Plane: Houses the turn-driver execution engine in loopx/control_plane/turn_driver/driver.py and resource enforcement via loopx/control_plane/quota/settlement.py, alongside orchestration policy normalization.
• Registry System: Provides JSON-based goal storage and lookup through loopx/registry.py, with agent identity management split between loopx/agent_registry.py and loopx/agent_onboarding.py.
• Interfaces: Exposes management commands via loopx/slash_commands.py and operational visibility through 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, 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, 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. 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, which maintains a registry of valid agents, while 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.

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