LoopX: The Open Source Control Plane for Long-Running AI Agent Teams (2026 Guide)

An AI agent can finish a task in one session. Long-running work is harder. Objectives change, owner decisions appear, evidence goes stale, agents hand work to peers, and a scheduler can keep spending after no useful transition remains. Chat memory and a timer are not enough to govern that. If you have ever left an AI agent running overnight and come back to find it spent $50 in API costs going in circles, you know the problem.

LoopX, developed by huangruiteng, is a free, open source state kernel and local-first control plane for long-running AI agent teams. It keeps objectives, gates, todos, evidence, quota, and handoffs stable while Codex, Claude Code, Cursor, or your own runtime executes bounded turns. It is agent-loop agnostic, provider-neutral, and does not replace the runtime that performs the work. 4,700+ stars on GitHub, MIT license.

In this guide, you'll learn what LoopX is, how it works, and how to connect it to your AI agent.

What is LoopX?

LoopX is a lightweight loop engineering state kernel for long-running AI agent teams. It is agent-loop agnostic across Codex, Claude Code, Cursor, and other coding agents, with durable goals, quota-aware auto-wake, executable todos, evidence logs, and verifiable handoffs.

The core idea is that agent runtimes execute the work, but LoopX governs the state that lets engineering, research, discovery, and operations loops continue across runs. It is not another agent framework or a provider-specific orchestration runtime. It is a control plane that sits between you and your agents, keeping the durable state that makes long-running work reviewable, restartable, and easier to hand off.

A useful mental model is an agent-native Kanban for long-running work. Cards carry identity, authority, evidence, and continuation. Moves are validated operators such as claim, gate, monitor, and writeback. The board is a projection; LoopX state remains the source of truth.

LoopX folds its control-plane mechanics into five questions:

What is the objective? (active goal, explicit scope, current authority)
What happens next? (ordered user and agent todos, ownership, claims, leases)
What needs human judgment? (concrete user gates instead of a vague "waiting for owner")
What evidence changed? (compact run history, validation, blockers, accepted writeback)
May the loop continue? (quota, capabilities, safe fallback, scheduler hints, stop conditions)

Who is it for?

Researchers running multi-day experiments: AI researchers who need an agent to run 200+ hour experiment arcs with hypotheses, matched evidence, invalid lineages, running replicates, and promote/stop gates visible in one graph.
Engineering teams with long-running agent tasks: Teams that run agents on multi-day engineering objectives, issue and PR loops, or recurring heartbeat work that must preserve scope, evidence, and review state.
Multi-agent teams: Teams where multiple agents (proposer, executor, evaluator) work in parallel and need ownership, leases, and handoff to be explicit and verifiable.
Operators who need legible progress: Creators, researchers, or operations teams whose progress must remain legible to a non-engineering operator who needs to understand what the agents are doing.

What makes LoopX different from just leaving an agent running?

Durable goals across turns and sessions: The objective, scope, and authority persist across turns, terminal sessions, and agent restarts. The agent does not lose sight of what it is supposed to be doing.
Quota-aware scheduling: loopx quota should-run decides whether a turn should deliver, ask, wait, self-repair, or stay quiet. The scheduler can keep spending after no useful transition remains, and LoopX prevents that. Quota decides the next tick.
Concrete user gates: Instead of a vague "waiting for owner," LoopX creates concrete user gates. The agent asks a specific question and waits. You answer it and the loop continues.
Evidence-backed handoff: When an agent hands work to a peer, the handoff includes evidence, validation status, and blockers. The receiving agent knows exactly what was done, what was verified, and what is still open.
Peer agent ownership: Registered agents are peers. Claims, leases, task boundaries, capabilities, and typed continuation decide who acts next. No durable leader identity is required.
Agent-loop agnostic: Works with Codex App, Codex CLI, Claude Code, Cursor, OpenCode, Pi, and custom runners. LoopX does not replace your agent runtime. It governs the state around it.
Real-world evidence: LoopX has been used in real projects spanning 200+ hours of elapsed loop lifetime, including a 4-day unattended run, a 13-hour C++ accuracy run, and 7 merged PRs in a public engine refactor.
Free and open source: MIT license. 4,700+ stars, 40 contributors, 36 releases. Python with no runtime dependencies outside the standard library.

What you need before you start

Python 3.11+: LoopX is a Python package with no runtime dependencies outside the standard library.
curl and tar: For the installation script.
macOS or Linux shell: The install script supports both platforms.
An AI agent: Codex App, Codex CLI, Claude Code, Cursor, OpenCode, Pi, or a custom runner.
Git (optional): Only needed for contributor clone and canary workflows.

Step-by-step installation

Step 1: Install LoopX

curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

Step 2: Connect your project

Navigate to your project root and connect it to LoopX:

cd /path/to/your-project
loopx connect
loopx status

If the project has not been initialized and connect tells you state is missing, use the guided path:

loopx start-goal --guided --project . --goal-text "Your long-running objective"

Step 3: Start from your agent

Connect your AI agent to LoopX. The exact setup depends on your agent:

Claude Code:

# Install the opt-in adapter, then run:
/loopx <task>
/loop

Codex App:

# Ask the agent to connect this project to LoopX, run loopx doctor,
# preserve existing state, and report the current gate and next todo.
# Then use $loopx <complex task> or choose loopx from /skills.

Codex CLI:

# Start codex in the project, ask it to connect and diagnose LoopX,
# then use $loopx <complex task> or /skills.

Cursor, shell, or custom runner:

# Use the installer and loopx doctor
# Connect manually or call LoopX from your runner

Step 4: Monitor and review

loopx status                    # Current objective, gate, and next todo
loopx history --goal-id <id>    # Run history
loopx quota should-run --goal-id <id>  # Should the agent act now?
loopx review-packet             # Compact owner-facing view of decisions

Step 5: Use presets for common workflows

loopx preset list
loopx preset show daily-triage

Safe presets cover daily triage, changelog drafts, and PR watching.

Common errors and how to fix them

Error	What it means	How to fix it
"State is missing" on connect	The project has not been initialized with LoopX state.	Run `loopx start-goal --guided --project . --goal-text "Your objective"` to initialize.
"loopx: command not found"	LoopX is not in your PATH.	Run `export PATH="$HOME/.local/bin:$PATH"` or add it to your shell profile.
Agent cannot connect to LoopX	The agent adapter is not installed or the agent is not in the project directory.	Follow the agent-specific setup in the Getting Started guide. Ensure you are in the project root when starting the agent.
"Quota exhausted"	The agent has used all its allocated turns, tokens, or time for this goal.	Review the quota allocation with `loopx quota should-run`. Adjust the quota if the work is not complete, or pause the goal with `loopx goal pause`.

LoopX vs leaving an agent running vs chat memory

Feature	LoopX (control plane)	Leaving agent running	Chat memory
Durable goals	Yes (persist across turns and sessions)	No (lost on restart)	No
Quota control	Yes (prevents wasteful spending)	No (agent keeps going)	No
User gates	Yes (concrete questions, not vague waiting)	No	No
Evidence and handoff	Yes (structured, verifiable)	No	Partial
Peer agent ownership	Yes (claims, leases, typed continuation)	No	No
Agent-agnostic	Yes (Codex, Claude Code, Cursor, custom)	N/A	N/A
Real-world tested	Yes (200+ hour loops, 4-day unattended runs)	Risky	No
Best for	Long-running multi-agent work that needs governance	Quick one-off tasks	Recalling past conversations

Bottom line: LoopX solves the fundamental problem of governing long-running AI agent work. Instead of leaving an agent running and hoping it does not go in circles, LoopX provides a durable control plane with goals, gates, quotas, evidence, and handoffs. The real-world evidence (200+ hour loops, 4-day unattended runs, 7 merged PRs) shows this is not a toy. If you are running AI agents on tasks that take hours or days, LoopX is the control plane that keeps the work reviewable, restartable, and bounded. It does not replace your agent runtime. It governs the state around it. For teams doing serious long-running agent work, this is the best free open source control plane available.

3 alternatives worth checking out

Prime Agent (github.com/PrimeIntellect-ai/prime-agent): A self-improving RLM agent with persistent IPython and built-in subagents. While LoopX is a control plane that works with any agent, Prime Agent is a complete agent with its own long-running features (daemon-backed sessions, persistent goals, heartbeats). Use LoopX if you want to keep your existing agent (Claude Code, Codex) and add governance. Use Prime Agent if you want a complete agent built for long-running work from the ground up.
DeepSeek-Reasonix (github.com/esengine/DeepSeek-Reasonix: A coding agent engineered around prefix-cache stability with per-turn checkpoints. Reasonix solves the "agent breaks over long sessions" problem with cache stability and checkpoints. LoopX solves the "agent goes in circles over long sessions" problem with goals, quotas, and gates. They address different failure modes of long-running work.
TencentDB Agent Memory (github.com/TencentCloud/TencentDB-Agent-Memory: A team-level memory hub for AI agents. While LoopX governs the loop (goals, quotas, gates, handoffs), TencentDB Agent Memory governs the knowledge (chat memory, skills, wiki, code graph). They are complementary: use LoopX for loop control and TencentDB Agent Memory for shared knowledge across agents.

Found this guide useful? Check out more AI tools and open source projects on Sudo Scout.