LoopX: A Control Plane for AI Agents That Have to Keep Working for Days

If you have ever pointed a coding agent at a multi-day goal, you know the failure mode. It is not that the model writes a bad function. It is that on turn 40, the agent no longer remembers what the objective was, which decision you already made, what is out of scope, or what the last run actually proved. The context window rolled over, and the plot went with it.

LoopX is an attempt to fix that specific problem. It calls itself "loop engineering for long-running AI agents," and it is a local control plane that sits above your agent runtime rather than replacing it.

The one-sentence version

Your agent (Codex, Claude Code, Cursor, whatever) executes bounded loops. Something (a heartbeat, a cron job, you hitting enter) triggers the next loop. LoopX holds the state that has to survive between those loops.

The project draws the separation like this:

That third row is the whole product. LoopX is not an executor and not an autonomous production controller. It is a state kernel with a CLI.

Why "just use a todo file" isn't enough

A TODO.md plus a long system prompt gets you surprisingly far. It falls over once any of these become true:

• The goal changed halfway through, and nothing recorded why.


• A decision genuinely needs a human, and that request evaporated into a chat message nobody read.


• Two agents are touching the same repo and neither knows who owns what.


• The last run claimed success, and there is no artifact proving it.


• Some work is safe and read-only, some crosses into writes, production, or private data, and the distinction lives only in your head.

LoopX makes those things explicit and machine-readable, which is what lets a loop run longer without becoming less accountable.

The concepts, in plain English

Lifetime goals. A durable project intention that outlives one chat thread. Importantly, a lifetime goal does not hand the agent open-ended autonomy: only the next bounded transition is executable.

User gates. A concrete decision that belongs to you, recorded as a first-class object instead of a sentence in a transcript. The loop can see that it is blocked on a human.

Safe fallback. When one lane is gated, audited side paths can keep moving without bypassing the gate. This is the part I find most interesting: the alternative designs are usually "block everything" or "let the agent decide," and both are bad.

Todo ownership. Todos are tagged user or agent, with a claimed_by field so multiple agents can coordinate instead of colliding.

Quota. A guard that answers whether an automatic turn should run right now, wait, ask the user, self-repair, or stay quiet. Practically, this is your defense against a heartbeat loop burning tokens on turns that cannot produce a verified transition.

Run history and evidence. Compact append-only events for progress, validation, blockers, rewards, and quota spend.

Public/private boundary checks. A local scan that tries to keep credentials, raw logs, local paths, and private state out of anything you publish.

Setup

Requirements are refreshingly light: Python 3.11+, curl, tar, and a macOS or Linux shell. The Python package has no runtime dependencies outside the standard library. Git is only needed if you want to contribute.

1. Install (no clone)

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash

export PATH="$HOME/.local/bin:$PATH"

loopx doctor

The installer drops a release snapshot under ~/.local/share/loopx/releases/, a CLI wrapper in ~/.local/bin, a man page, and reusable agent skills under ~/.codex/skills. As always, read a piped install script before running it if that matters to you.

Updates go through an explicit interface rather than re-running the installer blind:

loopx update --check     # read-only

loopx update --dry-run   # read-only

loopx update --execute

2. Kick the tires without touching a real repo

loopx demo

cd /tmp/loopx-demo

loopx status

loopx quota should-run --goal-id demo-goal

loopx history --goal-id demo-goal

This creates a disposable goal with one user todo and one agent todo. You should see ok: True and a should_run=True / state=eligible quota response. Do this first. It takes thirty seconds and tells you whether the mental model clicks for you.

3. Connect a real project

cd /path/to/your-project

loopx bootstrap \

  --goal-id your-project-goal \

  --objective "Improve this project through bounded, verified goal segments." \

  --goal-doc GOAL.md

loopx connect is an alias for bootstrap. This creates:

your-project/

  .loopx/registry.json

  .codex/goals/your-project-goal/ACTIVE_GOAL_STATE.md



~/.codex/loopx/

  goals/<goal-id>/runs/

Add these to .gitignore before you commit anything:

.loopx/

.codex/goals/

.opencode/goals/

goals/**/ACTIVE_GOAL_STATE.md

That state is live local runtime data. Committing a controller's active goal state is how private paths and internal notes end up in a public repo.

A healthy connection means loopx doctor passes, both files above exist, loopx status shows who acts next, and none of it is staged for commit.

4. The agent-first path

The docs actually push you toward not running these commands yourself. Paste something like this into Codex, Claude Code, or Cursor from your project root:

Connect the current project to LoopX. Do not clone the LoopX repository.

If `loopx` is not on PATH, install it with the official no-clone installer.



Then run `loopx doctor`. Working only from the current project root:

1. If LoopX state already exists, reuse it. Do not overwrite the goal or objective.

2. If the project is not connected, prefer `loopx connect`; use `loopx bootstrap`

   only when state clearly needs initialization.

3. Ensure `.loopx/`, `.codex/goals/`, and `.local/` are ignored.

4. Set up the thin LoopX heartbeat for this surface.

5. Stop after setup and report the active state id, current user gate, top agent

   todo, and next safe action.



Do not start longer delivery work in this setup turn.

One caveat worth knowing before you try this with a non-Codex agent: LoopX can only drive an agent that exposes at least one control hook, such as shell execution, a goal/task command, an automation hook, or its own scheduler. Without one, LoopX still tracks state, but you run the commands by hand.

5. The daily loop

loopx status

loopx history --goal-id your-project-goal

loopx quota should-run --goal-id your-project-goal

Adding work:

loopx todo add --goal-id your-project-goal --role agent \

  --text "Run the next bounded validation slice."

Diagnosing is also meant to be delegated. loopx diagnose deliberately emits an agent-facing evidence packet rather than a verdict, so you ask your agent to run it and reason from it: can this project self-drive, what blocks it, what exact question needs your answer, what happens next.

6. Heartbeats and quota (the token-spend part)

An automatic turn is supposed to check quota before working and record spend exactly once after validated writeback:

loopx quota should-run --goal-id your-project-goal

loopx heartbeat-prompt --thin --goal-id your-project-goal

loopx quota spend-slot --goal-id your-project-goal --slots 1 --source heartbeat --execute

Spend is not appended for quiet skips, preflight failures, or dry runs. should-run returns a fairly rich contract: whether delivery may run, what it is waiting on (user, controller, external evidence, health, quota), the work lane, todo summaries, and the spend policy.

7. Before you publish anything

loopx check --scan-path README.md --scan-path docs/ --scan-path examples/

8. Optional local dashboard

There is a read-first React dashboard for inspecting projects, todos, gates, and evidence across a global registry. It is explicitly experimental: the CLI stays the source of truth and browser writes require local opt-in. Check the repo docs for the current path, since it moved between the README and the getting-started guide.

What it deliberately does not do

The maintainer is unusually direct about this, which is a good sign. LoopX is not a full agent platform, not an autonomous production controller, and not a replacement for your runtime. Project ownership and dangerous permissions stay with the human. It is a local coordination substrate.

Is it worth a look?

Yes, if: you are running agents on goals that span days, you have heartbeat or monitor-style turns firing on a schedule, you coordinate a controller agent with scoped side agents, or you have already been bitten by an agent confidently redoing work it finished last Tuesday. The demo costs you a minute, and the ideas are portable even if you never adopt the tool.

Probably not yet, if: you use agents for single-session tasks, you are on Windows without WSL, you need something battle-tested with a release history and a large user base, or you do not use Codex-family or shell-capable agents. The value shows up proportionally to how long your loops run. Short loops do not drift, and the ceremony will feel like overhead.

Repo: https://github.com/huangruiteng/loopx