How LoopX Is Structured: A Three-Layer Architecture for Long-Running Agents

LoopX is organized into three distinct layers — a public-safe core control-plane, a thin CLI orchestration layer, and an extensible presentation layer — designed to keep runtime logic pure while exposing rich functionality to users and external systems.

This deep dive examines the LoopX repository structure as implemented in huangruiteng/loopx, exploring how its modular design separates concerns between immutable state management, command-line interfaces, and output rendering.

The Three-Layer Architecture

LoopX follows a single-package Python project structure under loopx/ with clear boundaries between layers:

Layer	Purpose	Principal Modules
1️⃣ Core Control-Plane	Public-safe helpers for turns, state, registry, and quota	turn_identity.py, state_refresh.py, state_projection.py, registry.py, quota.py
2️⃣ CLI & Command Orchestration	Click-based commands exposing the core API	cli_commands/, worker_bridge.py, visible_multi_agent_launcher.py
3️⃣ Presentation & Extensions	Rendering projections, static sites, and optional sinks	presentation/, visible_governance.py, upgrade.py

This layered architecture ensures that sensitive runtime details never leak into public interfaces while maintaining flexibility for extension.

Core Control-Plane Layer

The foundation of LoopX's structure resides in its public-safe core modules that model agent execution semantics.

Turn Identity and State Management

Every agent execution in LoopX is framed as a turn with a validated, public-safe identifier:

from loopx.turn_identity import normalize_turn_instance_id

turn_id = normalize_turn_instance_id("my-turn-01")

# Returns a normalized, validated turn instance identifier

Source: [loopx/turn_identity.py](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py)

State management follows an immutable state graph pattern across three specialized modules:

• state_refresh.py — Persists and refreshes state snapshots
• state_projection.py — Creates public-safe views of internal state
• state_migration.py — Evolves state schemas over time

Registry, Quota, and Lifecycle Gates

The core layer enforces resource boundaries through:

Module	Function
registry.py	Stores and retrieves public-safe objects
quota.py	Enforces resource limits with request-grant semantics
ready_score.py	Calculates numeric readiness metrics for turns
promotion_gate.py	Determines promotion eligibility based on ready scores

from loopx.registry import Registry
from loopx.state_projection import project_state

registry = Registry()
registry.register("turn", turn_id, {"status": "running"})

proj = project_state()  # Public-safe projection of entire system

CLI and Command Orchestration Layer

All user-facing interaction flows through loopx/cli_commands/, a directory of thin Click wrappers that parse arguments, delegate to core helpers, and emit structured output.

Core Command Modules

Command	Purpose	Source File
turn	Starts agent turns with validated IDs	[cli_commands/turn.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/turn.py)
todo	Manages task lists attached to turns	[cli_commands/todo.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/todo.py)
project_lifecycle	Installs/upgrades project skills	[cli_commands/project_lifecycle.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/project_lifecycle.py)
quota_request	Requests additional resources	[cli_commands/quota_request.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/quota_request.py)
presentation	Generates UI artifacts from state	[cli_commands/presentation.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/presentation.py)

Worker Bridge and Multi-Agent Launcher

Two specialized modules extend CLI capabilities:

• worker_bridge.py — Connects CLI processes to background workers for long-running tasks
• visible_multi_agent_launcher.py — Spawns coordinated tmux sessions for interactive multi-agent debugging

# Start a new turn via CLI

loopx turn --instance-id my-turn-01

# List todos for current turn

loopx todo list

# Request additional quota

loopx quota request --memory 2GB

Presentation and Extensions Layer

LoopX treats all UI surfaces as projections of public-safe state, enabling multiple output formats without core changes.

Static Site Generation and Sinks

• presentation/static_site.py — Renders markdown/HTML from state graph
• presentation/sinks/ — Stream output to external services (e.g., openviking_periodic_report.py)

Governance and Self-Upgrade

Module	Responsibility
visible_governance.py	Runtime governance checks
upgrade.py	Self-upgrade logic encapsulated

# Generate static site from current state

loopx presentation static-site --output ./site

Execution Flow: How Layers Interact

The LoopX structure enforces a unidirectional flow:

1. User invokes CLI command — Click parses arguments in cli_commands/
2. Command calls core helpers — Turn identity, registry, state projection
3. Core manipulates immutable state — May spawn workers via worker_bridge
4. Presentation renders output — Static sites, reports, or interactive sessions

This separation guarantees that runtime logic remains pure, the CLI stays thin, and presentation layers are interchangeable.

Summary

• LoopX structure comprises three layers: core control-plane, CLI orchestration, and presentation/extensions
• Core modules in loopx/ enforce public-safe contracts — no credential leakage
• CLI commands in cli_commands/ are thin Click wrappers delegating to core helpers
• Presentation layer treats UI as state projections, enabling multiple output formats
• Immutable state graph with refresh, projection, and migration lifecycle
• Worker bridge and multi-agent launcher support background and interactive execution

Frequently Asked Questions

What is the purpose of turn identity in LoopX?

Turn identity provides a validated, public-safe identifier for each agent execution cycle. The normalize_turn_instance_id() function in loopx/turn_identity.py ensures consistent naming conventions while preventing identifier collisions across long-running agent sessions.

How does LoopX prevent sensitive data from leaking through its CLI?

All CLI commands delegate to core helpers that enforce public-safe contracts. The core control-plane never exposes internal state directly; instead, state_projection.py creates sanitized views. This architecture guarantees that credentials and runtime internals remain isolated from user-facing interfaces.

Can LoopX be used programmatically without the CLI?

Yes — the core modules are designed for direct import. Python scripts can use from loopx.turn_identity import normalize_turn_instance_id, from loopx.registry import Registry, and other core helpers without invoking any Click commands, enabling integration into larger applications.

What role does the worker bridge play in LoopX architecture?

The worker bridge connects synchronous CLI processes to asynchronous background workers. Defined in loopx/worker_bridge.py, it enables long-running tasks to execute outside the CLI process lifecycle while maintaining state coherence through the core control-plane's registry and projection systems.

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