Introduction
"Keep the loop moving. Keep the judgment human."
This is article #168 in the "One Open Source Project a Day" series. Today's project is LoopX — a long-horizon agent control plane, 5,288 Stars, Apache-2.0, authored by huangruiteng.
LoopX addresses a problem that a single session can't solve: an agent can finish a task in one conversation, but what about work that spans days or weeks? Objectives shift, evidence goes stale, decision gates appear, agents hand work off to other agents… chat memory and a timer are nowhere near enough to govern any of that.
LoopX isn't an agent framework. It's a control plane running on top of your existing agent harnesses (Codex App / Claude Code / OpenCode / etc.): it owns the persistent state, decides "what happens next, whether to continue, and what needs human judgment," while the agent harness executes one bounded turn at a time.
What You'll Learn
- LoopX's core concepts: the roles of Goal / Gate / Todo / Evidence / Quota
- The Five Questions framework for the control plane
- Integration patterns with nine agent harnesses
- Available capability paths (Issue Fix / Explore / Auto Research, etc.)
- Quick start: install, connect a project, run your first loop
Prerequisites
- Experience with Claude Code, Codex, or similar AI coding agents
- Basic familiarity with long-horizon work management (goals, task decomposition, review workflows)
- Python fundamentals
Project Background
Overview
LoopX's core mental model is an agent-native Kanban for long-running work.
A regular Kanban manages human tasks. LoopX "cards" carry: identity (who owns this task), authority (who can claim it), evidence (what was accomplished), and continuation (context for the next step). "Moving a card" isn't clicking a button — it's a validated operator like claim, gate, monitor, or writeback. The board is a projection view; LoopX state is the source of truth.
Author / Team
- Author: huangruiteng
- Primary language: Python 3.11+
- License: Apache-2.0 (from v0.4.8; earlier releases under MIT)
- Website: huangruiteng.github.io/loopx
- User manual: Feishu Wiki
Project Stats
- ⭐ GitHub Stars: 5,288+
- 🍴 Forks: 476+
- 📄 License: Apache-2.0
- 📅 Created: 2026-05-31
Core Concepts
LoopX compresses control-plane responsibilities into five questions:
| Question | What LoopX keeps visible |
|---|---|
| What is the objective? | The active goal, explicit scope, and current authority |
| What happens next? | Ordered user and agent todos, ownership, claims, and leases |
| What needs human judgment? | Concrete user gates — not a vague "waiting for owner" |
| What evidence changed? | Compact run history, validation, blockers, accepted writeback |
| May the loop continue? | Quota, capabilities, safe fallback paths, scheduler hints |
These five questions map to five product promises: long-horizon state / semantic decisions / human-agent collaboration / recovery / governance.
The Control-Plane Stack
objective / issue / project
│
▼
LoopX state: objective + gates + todos + scope + evidence + quota
│
├─ human judgment needed? ── yes ──▶ ask a concrete question and wait
│
├─ safe fallback available? ────────▶ run one bounded agent slice
│
▼
Codex / Claude Code / Cursor / shell agent executes one turn
│
▼
write evidence + handoff + next todo ──▶ quota decides the next tick
The agent harness executes the work. LoopX governs the state that lets work continue across runs.
Four-Layer Responsibility Separation
| Layer | Responsibility |
|---|---|
| Kernel | Owns durable Goal, Todo, Gate, Evidence, Quota, Recovery, Scheduling state |
| Capability | Defines a stable, provider-neutral contract for one bounded, verifiable caller outcome |
| Provider | Calls external systems and returns bounded observations and readback |
| Extension | Packages and operates an optional Provider with install/upgrade/rollback lifecycle |
Execution path: Agent → Capability → Provider. Control path returns: Provider readback → Capability transition → Kernel.
Quick Start
Installation
# Requires Python 3.11+
python3 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor
macOS/Linux: POSIX shell. Windows: PowerShell 7 (no compatibility layer needed).
Connect a Project
cd /path/to/your-project
loopx connect
loopx status
For a first-time setup, use the guided path:
loopx start-goal --guided --project . --goal-text "Your long-running objective"
The Core Loop — Five Steps
Any custom runner calls these five commands:
loopx quota should-run # should this registered agent act right now?
loopx todo claim # claim the current work slice
loopx todo update # record what changed
loopx refresh-state # prepare context for the next turn
loopx quota spend-slot # account for a completed, validated slice
Integration with Nine Agent Harnesses
| Agent Harness | Recommended entry |
|---|---|
| Codex App | Ask the agent to run loopx connect, then use $loopx <task> or /skills
|
| Codex App (SSH) | loopx agent-onboard --agent-type codex-app-ssh |
| Codex CLI | Connect inline, then $loopx <task> or /skills
|
| Claude Code | Install the opt-in adapter, then /loopx <task> + /loop
|
| KunlunCode |
loopx-kunluncode connect + native Goal Pro |
| OpenCode | Install the static command facade; opt into --with-goal-bridge for recurring goals |
| Pi |
loopx slash-commands --install --surface pi, then /loopx <task>
|
| ZCode | loopx slash-commands --install --surface zcode |
| DeepSeek Harness (dsh) |
loopx[deepseek-harness] + loopx turn run-once
|
| Cursor / shell / custom | Manual loopx connect + call LoopX from your runner |
All integrations share the same control-plane state. Switching harnesses doesn't lose Goal state.
Capability Paths
LoopX wraps generic control-plane primitives into capability paths with concrete owned outcomes:
| You need to... | Capability | Command |
|---|---|---|
| Turn a public issue into a reviewable, evidence-backed change | Issue Fix | loopx issue-fix |
| Qualify the exact final diff before delivery | Change Quality | loopx capability show change-quality-qualification |
| Explore uncertain research without losing hypotheses and findings | Explore | loopx capability show explore |
| Rebase decisions on current evidence and verified outcomes | Decision Context | loopx capability show decision-context |
| Produce scheduled or triggered reports with receipts | Periodic Report | loopx capability show periodic-report |
List all installed capabilities:
loopx capability list --format json
Auto Research: Parallel Multi-Agent Work
LoopX ships a built-in KNN demo that shows proposer / executor / evaluator/promoter agents working in parallel:
# Browse available presets
loopx preset list
loopx preset show daily-triage
# See the Auto Research demo path
# demo/auto_research/README.md
Evidence of Long-Running Work
LoopX is explicit: these are not one-turn demos.
OpenViking open-source contribution arc (200+ elapsed hours)
The author manages their own contributions to the OpenViking repository using LoopX, spanning 200+ hours of elapsed project time across many bounded turns. The Issue Fix capability maintains rolling repository context, revision-stamped fix knowledge, and reviewer-facing preferences across that window.
Auto ML Experiment (200+ elapsed hours)
A redacted owner-run showcase: in a 200+ hour elapsed window, hypotheses, matched evidence, invalid lineages, running replicates, and promote/stop gates stay visible in one graph.
Independent user cases from the community:
- One user: 13h+ C++ precision improvement task, stayed aligned across multiple stages, triggered public research, improved final precision
- One user: 4-day unattended run, ongoing useful work, periodic report surface
- One user: 7 merged PRs, Engine refactor, reported 1B+ token scale
Dashboard and Observability
# Launch local dashboard (PWA mode)
loopx dashboard
Or build the experimental Tauri desktop window:
cd apps/desktop/loopx-control-plane
npm install
npm run dev
Session dash for tracking multi-goal fleet progress:
loopx dash
Daily state inspection:
loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal
loopx diagnose
loopx review-packet # compact owner-facing view: decisions, evidence, gates
Resources
- 🌟 GitHub: huangruiteng/loopx
- 📦 PyPI: loopx
- 🌐 Website: huangruiteng.github.io/loopx
- 📖 User manual (Feishu): CaL5wMk9ui17ngkWzeUcMlAYnZg
- 📚 Developer Book: Chinese · English
- 💬 Discord: discord.gg/XmGgQyCFZd
Summary
LoopX represents a clear-eyed engineering judgment: the agent problem isn't just "can it do this in one turn" — it's "after multiple days, multiple runs, and multiple harnesses, can you still tell where the work is, what changed, and who does what next?"
Three things worth noting:
"Control plane" vs. "agent framework" is a deliberate positioning. LoopX doesn't execute work — it manages state. This is the same design thinking as Kubernetes being an "orchestration plane" rather than a "container runtime." It means you can swap agents (Codex today, Claude Code tomorrow) without losing Goal state or evidence history.
The Five Questions framework is an actionable design. Many systems claim to "support long-horizon agents," but "long-horizon" stays vague. LoopX breaks it down into five concrete questions: objective / next step / human judgment gates / evidence changes / whether to continue. Each maps to a piece of code, a CLI command, and a verifiable contract.
What it doesn't do is also a design choice. LoopX explicitly states: it's not an autonomous production controller, it doesn't grant credentials, it doesn't approve destructive operations, it won't mark an unverified run as successful. At a time when agent capability boundaries are still unclear, this kind of explicit self-limitation is engineering honesty.
If you have multi-day AI agent work — machine learning experiments, large code refactors, sustained open-source contributions — LoopX offers the most complete open-source control-plane solution currently available.
Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.
Visit my personal site for more insights and interesting products.
Top comments (0)