Main Features of LoopX: A Deep Dive into the Stateful AI Agent Control-Plane

LoopX is an open, provider-neutral control-plane that makes long-running AI agent workflows reviewable, restartable, and hand-off-friendly through persistent goal management, quota-driven scheduling, and typed todo orchestration.

LoopX is an open-source framework hosted at huangruiteng/loopx that solves the state management problem for long-running AI agents. Unlike ephemeral chat sessions, LoopX provides a durable, reviewable control-plane that tracks objectives, manages agent turns, and enforces safety boundaries across different LLM providers and runtimes. Understanding the main features of LoopX reveals how it bridges the gap between autonomous agent execution and human operator oversight.

Core Architecture: The Five Questions of State Management

The architecture in huangruiteng/loopx organizes around five fundamental questions that any durable agent system must answer. Each question maps to specific implementation files and runtime behaviors.

Question	Surface Area	Implementation
Objective	Active goal, scope, authority	loopx/turn_identity.py, loopx/project_map.py
What happens next?	Ordered todos, ownership, leases	loopx/todos.py, loopx/quota.py
What needs human judgment?	User gates	loopx/control_plane/todos/user_gate.py
What evidence changed?	Run history, validation	loopx/state_projection.py, loopx/state_backup.py
May the loop continue?	Quota, scheduler hints	loopx/quota.py, loopx/control_plane/quota/scheduler_hint.py

Main Features of LoopX

Goal and Status Management

Persistent goal objects (goal_id, objective, scope) form the identity layer. The system maintains these in loopx/turn_identity.py and exposes current state through loopx/status.py, providing a status server that summarizes runtime conditions without requiring external database dependencies.

Todo Engine with Claim Semantics

The typed todo system in loopx/todos.py handles advancement, blocker, and monitor types with explicit claim/lease semantics. This prevents race conditions when multiple agents or human operators interact with the same goal. The engine supports priority ranking and expiration handling, ensuring that agent work respects ownership boundaries.

Quota Engine and Safe Fallback

loopx/quota.py implements compute-quota accounting with windowed slots, focus-wait handling, and outcome-floor enforcement. The quota engine answers "may the loop continue?" by evaluating quota_status and build_quota_plan. When quotas exhaust or safety conditions trigger, the system provides graceful degradation through self-repair hooks rather than abrupt termination.

Control-Plane Policies and Agent Lanes

Located in loopx/control_plane/*.py, these compact policy objects drive gating decisions and agent-lane selection. The loopx/control_plane/agents/agent_lane_recommendation.py module builds work-lane contracts and recommends actions across different provider adapters (Codex, Claude, OpenCode), maintaining provider neutrality while optimizing execution paths.

Self-Repair and Projection Gap Fixes

loopx/state_projection.py generates state-action projections and integrates evidence updates. When the system detects missing evidence or stalled projections via loopx/control_plane/quota/projection_repair.py, it injects repair hints automatically. This ensures the control-plane maintains coherent state even when individual agent runs fail or produce partial results.

Capability System and Extensions

The provider-neutral capability system in loopx/capabilities/ normalizes provider output into typed transitions. Capabilities like issue-fix, value-connectors, and explore validate execution results and propose next steps. The optional reward-memory experiment in loopx/capabilities/reward_memory/experiment.py learns from human feedback to improve future recommendations.

Integration Glue and Worker Bridge

loopx/worker_bridge.py provides adapters for generic runtimes, allowing arbitrary execution environments to invoke LoopX turn logic. This includes host-command registries and integrations with external systems like Lark Kanban, documented in docs/integrations/worker-bridge-install-contract.md.

Operator-Facing Presentation Layer

Read-first UI surfaces in apps/presentation/dashboard/README.md render control-plane state for human operators. These presentation layers consume state from the kernel without becoming sources of truth, enabling dashboard visualizations and CLI status commands that reflect the actual goal and quota state.

Practical Usage Examples

Install LoopX and initialize a new goal:

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"

cd /path/to/your/project
loopx start-goal --guided --project . --goal-text "Run a multi‑day benchmark"

Inspect current state and manage quota:

loopx status              # Shows goal, quota, next todo

loopx quota should-run    # Asks "should an agent turn run now?"

loopx todo claim          # Claim ownership of the next actionable todo

loopx todo update         # Report changes after agent turn completion

Run the built-in issue-fix capability:

loopx issue-fix https://github.com/owner/repo/issues/123

Inspect quota plans and handoff data:

loopx quota plan

# Example output includes:

#   "state": "focus_wait",

#   "reason": "focus wait: delivery lane has a continuation boundary …",

#   "blocked_action_scope": "delivery_focus"

Integrate from Python using the worker bridge:

from loopx.worker_bridge import run_loopx_turn
run_loopx_turn(goal_id="my-goal", agent_id="codex-app")

Key Implementation Files

• loopx/quota.py: Core compute-quota logic, focus-wait handling, and build_quota_plan
• loopx/todos.py: Todo type definitions, claim/lease semantics, and priority ranking
• loopx/turn_identity.py: Public-safe helpers for normalizing goal and turn identifiers
• loopx/state_projection.py: State-action projection warnings and evidence integration
• loopx/registry.py: Persistent registry of goals and metadata
• loopx/ready_score.py: Computes "ready-score" for agent execution decisions
• loopx/worker_bridge.py: Glue code for arbitrary runtime integration
• docs/architecture.md: High-level design overview of the control-plane model

Summary

• LoopX provides durable, provider-neutral state management for long-running AI agents through a local control-plane
• The todo engine enforces ownership through claim/lease semantics in loopx/todos.py, preventing race conditions in multi-agent scenarios
• Quota-driven scheduling in loopx/quota.py prevents runaway computation and enables safe fallback with focus-wait and outcome-floor enforcement
• Self-repair mechanisms detect projection gaps via loopx/control_plane/quota/projection_repair.py and inject fixes automatically
• The capability system normalizes provider-specific outputs into portable, typed transitions across different LLM services
• Worker bridge adapters allow integration with arbitrary runtimes without vendor lock-in or external database dependencies

Frequently Asked Questions

What makes LoopX different from other agent frameworks?

Unlike frameworks that manage prompts or model-specific tool calling, LoopX functions as a stateful control-plane that persists across turns and runtimes. It answers operational questions like "who owns this task?" and "should the loop continue?" through explicit quota and todo semantics in loopx/quota.py and loopx/todos.py rather than merely wrapping LLM API calls.

How does LoopX handle provider neutrality?

LoopX achieves provider neutrality through its capability system in loopx/capabilities/ and agent-lane recommendations in loopx/control_plane/agents/agent_lane_recommendation.py. These layers normalize provider-specific outputs (from Codex, Claude, etc.) into standard goal states and todos, allowing seamless handoffs between different AI services without code changes.

Can LoopX recover from interrupted agent runs?

Yes. The loopx/state_projection.py and loopx/state_backup.py modules maintain compact run histories and validation states. If a projection gap is detected, loopx/control_plane/quota/projection_repair.py injects repair hints, making workflows restartable and reviewable even after hardware failures or partial completions.

Does LoopX require external databases or cloud services?

No. LoopX has no external runtime dependencies. All state management occurs through the local control-plane using the file-based registry in loopx/registry.py. The loopx start-goal command initializes a local .loopx directory, making it suitable for air-gapped or local-first deployments without network connectivity requirements.

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