LoopX: A Control Plane for Agent Loops

LoopX is a local state kernel that sits beside your coding agent and holds onto the things a chat session forgets: what the objective was, which decisions still need a human, what evidence has already been gathered, who owns the next slice of work, and whether the loop has any budget left to keep going. It doesn't run the agent. Codex, Claude Code, Cursor or your own runner still executes the turn; the kernel only decides whether a turn should happen and what the next one inherits.

huangruiteng/loopx started on May 31, 2026 and reached 2,247 stars by August 6. It's MIT-licensed, Python 3.11 or newer, and the package has no runtime dependencies outside the standard library. Three releases landed in six days: v0.3.0 on July 30, v0.4.0 on August 1, v0.4.1 on August 4.

Key Takeaways:

• It stores control state, not conversation. Objective, gates, todos, scope, evidence and quota live in .loopx/ on your machine.
• The whole tick is five commands: quota should-run, todo claim, todo update, refresh-state, quota spend-slot.
• Claude Code support is an opt-in adapter gating Claude's native /loop. Codex App gets a heartbeat driver. Cursor and custom runners connect manually.
• The repo's headline evidence, two trajectories spanning 200+ hours, means elapsed wall-clock project time. The project says so itself and disclaims continuous model execution or unattended autonomy.
• It refuses to be an autonomous production controller. Dangerous permissions, publishing and production writes stay with you by design.

What LoopX actually is

Four roles carry the whole architecture, and they're worth memorising because everything else in the docs assumes them.

The agent plans and performs one bounded action through a host runtime. A provider calls external systems and returns observations and results. A capability defines the caller's intended outcome, normalises whatever the provider spat back, validates it, and proposes a typed transition. The kernel owns durable todos, gates, monitors, accepted writeback, quota, recovery and scheduling.

Execution flows Agent -> Capability -> Provider. Control flows back the other way: provider readback becomes a capability transition, which the kernel either accepts or doesn't. So the agent never writes directly into the state that governs it, which is the entire point.

The mental model the docs offer is an agent-native Kanban board for long-running work. Cards carry identity, authority, evidence and continuation; moves are validated operators like claim, gate, monitor and writeback. The board is a projection. The kernel's state stays the source of truth, and that distinction gets enforced rather than just described: loopx lark-kanban will project todos and gates into Lark through a documented adapter, but the projection never becomes authoritative.

Registered agents are peers. There's no durable leader identity; claims, leases, task boundaries and typed continuation decide who acts next.

Loop engineering, and why it suddenly needed tooling

The term went from nowhere to everywhere over a few months in 2026. LangChain, IBM and Addy Osmani have all published explainers, Gergely Orosz wrote a "what is this" piece, and there's an r/AI_Agents thread asking someone to explain it like the reader is five. When a phrase collects that many definitional posts in a quarter, it usually means the practice arrived before the vocabulary did.

The practice, minus the branding: a single agent turn is bounded, because context runs out, the tool budget runs out, and the session ends. Work that takes days doesn't fit in one turn, so you get a loop, and the loop needs somewhere to keep whatever survives between turns. Prompt engineering shapes one turn, context engineering shapes what a turn can see, and loop engineering handles what persists across turns and what decides whether the next one runs at all. The harness sits underneath all three, running the turn once something has decided it should happen.

The README puts the failure mode plainly: 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 cron timer don't govern any of that. The last item is the expensive one, because a loop that keeps firing with nothing left to do burns tokens in a way nobody notices until the bill arrives.

Five questions, and the state that answers them

The project folds its mechanics into five questions it can always answer about a running objective.

What is the objective? The active goal, its explicit scope, current authority. What happens next? Ordered user and agent todos with ownership, claims and leases. What needs human judgment? Concrete user gates, phrased as an actual question, instead of a status that says "waiting for owner" and tells you nothing. What evidence changed? Compact run history, validation results, blockers, accepted writeback. May the loop continue? Quota, capabilities, safe fallback, scheduler hints, stop conditions.

The gates question is the one that separates this from a task tracker. A gate isn't a flag; it's a specific question the loop asks and then stops for, and loopx status shows you the current one alongside the next agent todo.

The tick itself is small enough to read in one breath:

loopx quota should-run      # should this registered agent act now?
loopx todo claim            # who owns this slice?
loopx todo update           # what changed?
loopx refresh-state         # what should the next turn see?
loopx quota spend-slot      # account for a completed, validated slice

Five commands. Everything else in the surface, the presets, the capability packs, the dashboard, sits on top of those.

Above the tick there's a layer of packaged work lanes: issue fixing, content operations, value connector planning, ML experiment advice, benchmark evidence. Each one bundles the todos, gates and evidence shape that kind of work usually needs, so you're not designing a loop from first principles for a job someone has already mapped. Safe presets cover the smaller recurring cases, daily triage, changelog drafts and PR watching among them, and loopx preset list will show you what's available without changing anything. Inspection is read-only throughout; loopx configure-goal --goal-id <id> reports current state, fit, boundaries and copyable commands, and does nothing to your project unless you pass --execute. That read-first default is a small design decision that turns out to matter a lot when the thing you're inspecting governs whether a scheduler spends money.

Installing it and connecting a project

You need Python 3.11+, curl, tar, and a macOS or Linux shell. Git only matters if you want the contributor canary wrapper.

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

Then from the project root, loopx connect followed by loopx status. If the project has no state yet, the guided path is loopx start-goal --guided --project . --goal-text "your long-running objective".

A connection counts as working when loopx doctor passes, .loopx/registry.json exists with a projected active goal, loopx status shows the objective plus a concrete user gate plus the next agent todo, and there's a visible loop driver. Keep .loopx/, .codex/goals/ and .local/ out of git; the docs are firm that it should reuse existing state rather than overwrite it, so committing runtime state is how you get two machines fighting.

Which agents it drives, and how differently

The host support is uneven in a way the README is honest about, and picking a host changes your experience considerably.

Codex App is the best-served path, which tracks with how much of the current tooling is being built around Codex agent workflows. You ask the agent to connect the project, then use $loopx <complex task> or pick loopx from /skills, and the loop driver is Codex App's heartbeat automation refreshed from quota should-run.scheduler_hint. Over SSH there's a dedicated onboarding command, loopx agent-onboard --agent-type codex-app-ssh.

Claude Code works through an opt-in adapter. You install it, run /loopx <task>, then /loop, and Claude Code's native loop runs gated by LoopX. That's a neat arrangement: Claude Code already has the loop primitive; the kernel just decides when it's allowed to fire.

Codex CLI uses a visible /goal <task_body> with no hidden headless execution by default. OpenCode gets a static command facade and an opt-in --with-goal-bridge for recurring goals. Cursor, plain shells and custom runners get the installer and loopx doctor, and you wire the rest yourself against the custom runner integration guide.

What it deliberately won't do

Two refusals, stated in the README rather than buried in a design doc.

It does not replace your agent runtime, and has no model, no tool loop and no execution of its own. Comparing it to LangGraph or CrewAI is a category error: those give you the graph and the runtime, this gives you the durable state and the permission to run. You can use both, and the four-role architecture assumes you will.

It is also not an autonomous production controller. Dangerous permissions, publishing, production writes and final ownership stay with the human. The repo's own status badge reads "loop agents early". For a project moving three releases a week, that's the right label.

The evidence section deserves the same reading discipline. Two showcase trajectories, an OpenViking issue-fix arc and an Auto ML experiment, each span 200+ hours of loop lifetime. The project immediately clarifies that this is wall-clock project time, not 200 hours of continuous model execution and not a claim of unattended production autonomy. Anyone quoting "200 hours of autonomous agent work" from this repo has dropped the sentence that follows the number.

Local control plane versus a hosted agent

A local control plane solves governability. You get to see the objective, interrupt at a gate, audit the evidence, and stop the loop spending. What it doesn't solve is the machine: something on your laptop still has to be awake for the next tick to happen, and quota should-run returning yes is useless if the host is asleep.

Which is the part LoopX cannot fix, because it is not a LoopX problem. The kernel can hold an objective perfectly for three days and still deliver nothing, since quota should-run returning yes at 2am is worth exactly as much as the machine that is supposed to act on it. Local-first buys you governability and hands you an availability problem in exchange. Worth it if the loop runs while you are at the desk anyway. If the point was work that continues without you, the laptop was the wrong place to put it, and an always-on hosted agent removes the question rather than governing it better.

FAQ

Is LoopX a replacement for LangGraph or CrewAI?

No, and the README says so directly: it does not replace your agent runtime. LangGraph and CrewAI give you an execution graph and a way to run agents. This gives you durable objectives, gates, todos, evidence and quota that survive between whatever runs, with the kernel sitting underneath the agent rather than around it.

Does LoopX run locally?

Yes, local-first by design: installs to $HOME/.local/bin, keeps state in .loopx/ in your project, and needs Python 3.11+ on macOS or Linux. The Python package has no runtime dependencies beyond the standard library, so there's no server and no database to stand up.

Does LoopX work with Claude Code?

Through an opt-in adapter. You install it, then /loopx <task> followed by /loop, and Claude Code's native loop runs under the kernel's gate. Status detection and driver quality differ by host, with Codex App currently getting the most complete integration.

What does loop engineering mean in practice?

Deciding what survives between agent turns and what governs whether the next turn runs. Prompt engineering shapes a single turn, context engineering shapes what that turn can see, and loop engineering handles the state, gates and budget that carry across many of them. This is one implementation of that idea; the concept doesn't require any particular tool.