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

> Discover LoopX's main features: persistent goal management, quota-driven scheduling, and typed todo orchestration for reviewable, restartable AI agent workflows. Enhance your agent control.

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

---

**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`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py), [`loopx/project_map.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/project_map.py) |
| **What happens next?** | Ordered todos, ownership, leases | [`loopx/todos.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py), [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) |
| **What needs human judgment?** | User gates | [`loopx/control_plane/todos/user_gate.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/todos/user_gate.py) |
| **What evidence changed?** | Run history, validation | [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py), [`loopx/state_backup.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_backup.py) |
| **May the loop continue?** | Quota, scheduler hints | [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), [`loopx/control_plane/quota/scheduler_hint.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py) and exposes current state through [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/reward_memory/experiment.py) learns from human feedback to improve future recommendations.

### Integration Glue and Worker Bridge

[`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/docs/integrations/worker-bridge-install-contract.md).

### Operator-Facing Presentation Layer

Read-first UI surfaces in [`apps/presentation/dashboard/README.md`](https://github.com/huangruiteng/loopx/blob/main/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:

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

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

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

```

Inspect quota plans and handoff data:

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

```python
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py)**: Core compute-quota logic, focus-wait handling, and `build_quota_plan`
- **[`loopx/todos.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py)**: Todo type definitions, claim/lease semantics, and priority ranking
- **[`loopx/turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py)**: Public-safe helpers for normalizing goal and turn identifiers
- **[`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py)**: State-action projection warnings and evidence integration
- **[`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)**: Persistent registry of goals and metadata
- **[`loopx/ready_score.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/ready_score.py)**: Computes "ready-score" for agent execution decisions
- **[`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py)**: Glue code for arbitrary runtime integration
- **[`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py), preventing race conditions in multi-agent scenarios
- **Quota-driven scheduling** in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) and [`loopx/todos.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) and [`loopx/state_backup.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.