# What is LoopX? Understanding the Open-Source AI Agent Control Plane

> Discover LoopX an open-source AI agent control plane. It provides a durable state layer for long-running agents tracking objectives evidence and more. Learn how LoopX separates agent runtime from its state kernel.

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

---

**LoopX is an open-source, provider-neutral control plane that gives long-running AI agents a durable, reviewable state layer, separating agent runtime from a state kernel that tracks objectives, gates, todos, evidence, quota, and hand-offs across turns.**

LoopX is an open-source project developed by huangruiteng that solves the observability and state management challenges of autonomous AI workflows. Unlike monolithic agent frameworks that bundle execution and state, LoopX acts as a local-first control plane that governs when turns should run, who owns them, and what evidence must be captured. According to the `huangruiteng/loopx` source code, it maintains durable state in [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) while remaining provider-neutral to work with Codex, Claude, or custom runtimes.

## Core Architecture: Kernel, Capability, and Provider Pipeline

The architecture follows a strict **kernel → capability → provider** pipeline that decouples execution from state management. As implemented in `huangruiteng/loopx`, the system operates through three distinct layers:

- **Kernel**: Owns the durable state (todos, gates, evidence, quota) and enforces the lifetime-goal invariant.
- **Capabilities**: Define typed outcomes, normalize provider output, and validate transitions before state changes commit.
- **Providers**: Call external services (e.g., Codex, Claude Code) and return observations for normalization.

The data flow works bidirectionally: Agent → Capability → Provider on the runtime side, and Provider readback → Capability transition → Kernel on the control side. This design is formalized in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) and [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md), which specify the write-back contract and store interactions.

### The State Kernel and Local-First Storage

The **state kernel** maintains the single source of truth for loop state. It is a local-first system: the state lives in your project directory at [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) and is never committed to the repository. This keeps long-running work reproducible and auditable while preventing sensitive execution metadata from leaking into version control.

The [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) module handles the critical post-turn phase, merging write-back evidence into durable state after each iteration completes. Meanwhile, [`loopx/turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py) defines the identity of a turn (goal, todo, claim) and serializes it, ensuring that distributed or multi-session agents can resume work with clear ownership chains.

## Six Critical State Dimensions

LoopX makes six key aspects of agent execution visible and durable across turns:

- **Objective**: The active goal, its scope, and authority.
- **Next Step**: Ordered user and agent todos with ownership, claims, and leases.
- **Human Judgment**: Concrete user gates rather than vague "waiting for owner" states.
- **Evidence**: Compact run-history, validation results, blockers, and write-back data.
- **Continuation**: Quota availability, safe fall-backs, scheduler hints, and stop conditions.
- **Runtime Bridge**: Pluggable interfaces for Codex App, Claude Code, and generic workers via `loopx heartbeat-prompt` and `loopx worker-bridge`.

## Working with LoopX: CLI Examples

LoopX provides a comprehensive CLI for managing agent workflows. All commands assume installation via the official install script and execution from a managed project root.

Install LoopX and verify the environment:

```bash

# Install LoopX (no clone required)

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

# Verify project health and current state

loopx doctor                     # Verifies that .loopx/ exists and is healthy

loopx status                     # Shows objective, current gate, next todo

```

Initialize and manage long-running goals:

```bash

# Start a new goal with interactive guidance

loopx start-goal --guided \
  --project . \
  --goal-text "Generate a monthly research report for the team"

# Inspect full execution history

loopx history --goal-id my-project-goal

```

Execute the standard turn-based workflow:

```bash

# Check if the agent should run this turn

loopx quota should-run          # Returns yes/no + scheduler hint

# Claim ownership for the current todo slice

loopx todo claim                # Assigns lease for this turn

# After the agent completes its bounded action:

loopx todo update               # Attach evidence, update status

loopx quota spend-slot        # Record turn consumption for quota accounting

loopx refresh-state             # Merge write-back and prepare next turn

```

Integrate with external surfaces and UIs:

```bash

# Install slash commands for specific hosts (e.g., Pi)

loopx slash-commands --install --surface pi

# Then invoke via: /loopx <task description>

# Launch the operator dashboard

loopx serve-status              # Starts the web UI for monitoring state

# Run a preset workflow (e.g., daily triage)

loopx preset show daily-triage

```

## Key Implementation Files

The following files in `huangruiteng/loopx` implement the control plane logic:

- **[`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py)**: Core runtime helpers and the entry point for all `loopx` CLI commands.
- **[`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py)**: Projects kernel state into read-only views for operators and external adapters like the Lark Kanban integration.
- **[`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py)**: Handles state refresh after each turn, merging write-back evidence into the durable store.
- **[`loopx/turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py)**: Defines turn identity serialization (goal, todo, claim) for session tracking and resume.
- **[`loopx/slash_commands.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/slash_commands.py)**: Implements slash-command integration points for Pi, Discord, and other chat surfaces.
- **[`loopx/visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py)**: Boilerplate for launching multi-agent sessions in tmux with visible state sharing.
- **[`loopx/upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/upgrade.py)**: Self-update logic for the LoopX CLI package.
- **[`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md)**: Formal specification of the kernel, capability, and provider layers.
- **[`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md)**: Contract documentation for state stores, write-back mechanisms, and quota allocation.

## Summary

- LoopX is a **provider-neutral control plane**, not a replacement for agent runtimes, that separates execution from durable state management.
- It maintains **local-first state** in [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) tracking objectives, todos, gates, evidence, and quota across turns.
- The **kernel → capability → provider** architecture normalizes external service outputs into validated state transitions.
- **Six state dimensions** (objective, next step, human judgment, evidence, continuation, runtime bridge) make long-running loops observable and auditable.
- The CLI provides **turn-based workflow commands** (`loopx quota should-run`, `loopx todo claim`, `loopx refresh-state`) for safe, resumable agent execution.

## Frequently Asked Questions

### Does LoopX replace my existing AI agent runtime?

No. LoopX does not replace the agent runtime; it governs when a turn should run, who should own it, what evidence must be captured, and how the loop should continue safely. You can use LoopX with Codex, Claude Code, or custom agent implementations while maintaining a consistent state layer.

### Where does LoopX store its state?

LoopX uses a local-first storage model. The state lives in your project directory at [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) and is intentionally excluded from version control. This keeps execution history and sensitive quota data local while making it reproducible and auditable across sessions.

### How does LoopX handle multi-turn conversations?

LoopX manages multi-turn workflows through explicit identity tracking in [`loopx/turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py) and state refresh mechanics in [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py). Each turn claims a specific todo slice, updates evidence, spends quota slots, and refreshes state before the next iteration, preventing duplicate execution and maintaining clear ownership chains.

### Can I integrate LoopX with my existing project management tools?

Yes. LoopX includes projection adapters that export kernel state to external collaboration tools. The [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) module provides read-only views for operators, and the repository includes specific integrations like the Lark Kanban adapter, allowing you to visualize LoopX todos in external surfaces while maintaining the kernel as the source of truth.