# LoopX

> A lightweight, local-first state kernel and control plane for long-running AI agent work, keeping goals, todos, gates, evidence, and handoffs stable across Codex, Claude Code, Cursor, and other agent runtimes.

LoopX is an open-source, MIT-licensed local control plane for loop engineering — the discipline of running AI agents on multi-day, multi-turn objectives without losing state, scope, or human oversight. Built by Huang Ruiteng and released under the GitHub handle `huangruiteng`, it sits above agent runtimes like Codex, Claude Code, and Cursor rather than replacing them. The project reached v0.4.2 in August 2026 and has accumulated over 2,900 GitHub stars.

## What It Is

LoopX is a durable state kernel that tracks the five questions every long-running agent loop needs answered: what is the objective, what happens next, what needs human judgment, what evidence changed, and may the loop continue. It stores this control state locally in a compact layer — goals, typed todos, ownership claims, leases, evidence logs, quota, and handoff contracts — and exposes it through a CLI that any agent runtime can call. The README describes it as "an agent-native Kanban for long-running work" where cards carry identity, authority, evidence, and continuation, and moves are validated operators such as `claim`, `gate`, `monitor`, and `writeback`.

## How the Control Plane Works

The core execution model is a tight loop of five CLI primitives:

- `loopx quota should-run` — decides whether a registered agent should act now
- `loopx todo claim` — assigns ownership of the current work slice
- `loopx todo update` — records what changed after a turn
- `loopx refresh-state` — prepares context for the next turn
- `loopx quota spend-slot` — accounts for a completed, validated slice

When a user gate blocks one lane (e.g., a decision requiring human judgment), LoopX routes the agent to a separately audited safe fallback and surfaces a concrete question for the owner rather than stalling the entire loop. The kernel separates the generic control plane (goals, gates, quota, handoff) from domain-specific capability packs (issue fixing, ML experiments, auto research, content operations), making it extensible without coupling domain logic to the scheduler.

## Agent Runtime Integrations

LoopX is explicitly agent-agnostic. The README documents integration paths for:

- **Codex App** — heartbeat automation driven by `quota should-run.scheduler_hint`
- **Codex CLI** — packaged install path with a static command facade
- **Claude Code** — opt-in adapter enabling `/loopx <task>` and `/loop` commands
- **OpenCode** — static command facade with optional goal bridge
- **Cursor and custom runners** — shell or scheduler integration via `loopx doctor` and `loopx connect`

Peer agents coordinate through typed claims and leases; no durable leader identity is required. The cross-runtime implementation review demo shows Claude implementing while Codex reviews, with LoopX keeping ownership, evidence, quota, and handoff explicit throughout.

## Evidence and Showcases

The project's README presents trajectory evidence from real long-running loops. The OpenViking Issue-Fix arc and an Auto ML Experiment arc each span what the README describes as 200+ hours of elapsed loop lifetime across many bounded turns, decisions, and evidence updates — clarifying that elapsed lifetime is wall-clock project time, not continuous model execution. An Auto Research showcase demonstrates proposer, executor, and evaluator/promoter agents iterating in parallel while todo, quota, evidence, and targeted wake remain visible in one graph. The creator's public OpenViking contributions are linked as verifiable output.

## Update: LoopX v0.4.2

The latest release is v0.4.2, published on August 6, 2026. The v0.4.x line ships a durable state kernel for goals, typed todos and decision scopes, peer claims and leases, evidence and writeback, quota-aware scheduling, and cross-turn continuation. Guided start, recurring heartbeat, isolated Codex CLI turns, evidence-backed Issue-Fix admission, optional Explore and auto-research paths, public validation canaries, and a read-first multi-project dashboard all build on the shared control state. The README notes that the next milestones are simpler installation and host packaging, broader typed runtime adapters, stronger terminal acceptance across repeated public loops, and a more polished management surface.

## Setup Path

LoopX requires Python 3.11+, `curl`, `tar`, and a macOS or Linux shell. Installation without cloning takes a single `curl` command piped to bash, followed by `loopx doctor` to verify the environment. Connecting to a project is `loopx connect` from the project root. A guided start path (`loopx start-goal --guided`) handles projects without existing state. Local runtime state (`.loopx/`, `.codex/goals/`, live goal state files) is kept ignored and never committed.

## Features
- Durable long-running goal state kernel
- Typed todos with ownership claims and leases
- Concrete user gates for human-in-the-loop decisions
- Quota-aware scheduling and auto-wake
- Evidence logs and validated writeback
- Cross-turn and cross-agent handoff contracts
- Agent-agnostic runtime bridges (Codex, Claude Code, Cursor, OpenCode)
- Peer multi-agent coordination with soft ownership
- Issue-Fix capability with rolling repository context
- Auto Research with proposer/executor/evaluator agent roles
- ML Experiment tracking with hypothesis and evidence lineage
- Explore Graph and configurable Explore Harness
- Read-first multi-project dashboard
- Lark/Feishu Kanban projection adapter
- Public/private boundary validation
- Reward Memory experiment support (default-off)
- Beginner presets for daily triage and changelog drafts
- loopx doctor diagnostics and guided start path

## Integrations
Codex App, Codex CLI, Claude Code, OpenCode, Cursor, Lark (Feishu), WeChat, GitHub, OpenViking

## Platforms
MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.4.2

## Links
- Website: https://huangruiteng.github.io/loopx/
- Documentation: https://huangruiteng.github.io/loopx/docs/
- Repository: https://github.com/huangruiteng/loopx
- EveryDev.ai: https://www.everydev.ai/tools/loopx