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.
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:
| Layer | Role |
|---|---|
| Codex / Claude Code / Cursor | Execute a bounded agent loop: read, write, run commands, respond |
| Goal mode / automation / CLI / TUI | Trigger or schedule the next loop |
| LoopX | Preserve goals, gates, todos, run history, quota, evidence, handoff state |
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.
A TODO.md
plus a long system prompt gets you surprisingly far. It falls over once any of these become true:
LoopX makes those things explicit and machine-readable, which is what lets a loop run longer without becoming less accountable.
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.
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.
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
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.
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.
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.
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.
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.
loopx check --scan-path README.md --scan-path docs/ --scan-path examples/
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.
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.
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.