LoopX: AI Agent Orchestration Control Plane
/loopx
LoopX is a local control plane that keeps a long-running AI agent job's objective, gates, todos, evidence, and quota intact across sessions and tools. Reach for it if you're already running multi-day loops with Codex, Claude Code, or Cursor and losing track of decisions or blockers. Skip it if one agent session finishes your task — LoopX sits on top of a runtime, not in place of one, and the project calls itself still early.
What is LoopX?
LoopX is a Python-based state kernel that acts as a local control plane for long-running AI agent work. It tracks the durable parts of a job — objective, gates, todos, evidence, and quota — in one layer on your machine, so Codex, Claude Code, Cursor, or a custom runner all read and write the same state. The README calls this an agent-native Kanban board where LoopX's own state stays the source of truth.
The Challenge of Long-Running AI Agent Work
A single agent turn can finish a task in one sitting; the trouble starts when the work spans days. Objectives shift mid-stream, evidence goes stale, an agent hands a task to a peer, and a scheduler can keep firing turns long after there's no useful next step — chat history and a cron timer don't track any of that. LoopX's answer is narrow: it isn't trying to make agents smarter, it's keeping the objective, the gate blocking progress, the todo list, the evidence, and the remaining quota in one place so a new session, or a different tool, can pick up exactly where the last one stopped.
Core Capabilities for Agent Orchestration
- ✓Durable state lives in `.loopx/` and `.codex/goals/` on your machine, not in chat context, so it survives a session ending or a runtime switch.
- ✓`loopx quota should-run` determines if a turn's action ought to be delivering, asking, waiting, self-repairing, or remaining quiet, all prior to any expenditure, while `loopx quota spend-slot` is solely responsible for recording a slice that has been completed and validated, subsequently.
- ✓Concrete user gates replace vague waiting states — `loopx status` reports the current objective, the exact gate blocking progress, and the next agent todo.
- ✓`loopx todo claim` and `loopx todo update` let peer agents own a slice of work and hand it off with evidence attached, instead of relying on an implicit leader.
- ✓Runtime bridges cover Codex App, Codex App over SSH, Codex CLI, Claude Code (via an opt-in adapter with `/loopx` and `/loop`), and OpenCode (via a command facade).
- ✓Domain capabilities are packaged as commands for repeatable lanes — `loopx issue-fix`, `loopx content-ops`, `loopx value-connectors`, `loopx ml-experiment`, `loopx benchmark`.
- ✓`loopx review-packet` renders a compact, owner-facing summary of decisions, evidence, and unresolved gates for someone who isn't reading the agent's raw output.
- ✓Optional projections like a Lark Kanban adapter and a local dashboard display state without becoming the source of truth themselves.
When to Use LoopX
- •Multi-day engineering, research, benchmark, or experiment work that runs across many separate agent sessions.
- •Issue and PR loops where scope, evidence, and review state need to survive between turns and between tools.
- •Recurring heartbeat or monitor jobs that should stop spending compute once there's no useful next step.
- •Projects with owner-approval, safety, publication, or private-data gates that need an explicit stop-and-ask point.
- •Peer-agent setups where task claims, leases, and handoff between agents matter more than a single long chat.
Getting Started with LoopX
Installation is clearly documented. LoopX needs Python 3.11+, `curl`, `tar`, and a macOS or Linux shell — Git is only required for the contributor clone path, and the Python package itself has no runtime dependencies outside the standard library. The documented path skips cloning entirely: pipe the install script from the repo, add the resulting binary to your `PATH`, then run a doctor check. ```bash curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash export PATH="$HOME/.local/bin:$PATH" loopx doctor ``` From your project root, `loopx connect` followed by `loopx status` attaches LoopX to that project. If it reports missing state, the guided path (`loopx start-goal --guided --project . --goal-text "Your long-running objective"`) sets one up. LoopX is meant to reuse existing state rather than overwrite it, and the README says to keep `.loopx/`, `.codex/goals/`, and `.local/` out of version control. Contributors who want the live canary build instead clone the repo and run `scripts/install-local.sh`.
Integrating LoopX with Your AI Agents
Once connected, the actual integration depends on which agent runtime you're driving. For Claude Code specifically, the README points to an opt-in adapter — install it, then run `/loopx <task>` followed by `/loop`, and the loop driver becomes Claude Code's native `/loop` command gated by LoopX. Codex App, Codex CLI, and OpenCode each get their own recommended start command and loop driver in the README's host table, and Cursor or a custom runner can call LoopX directly through the installer and `loopx doctor`. Underneath any of those, the core tick LoopX expects a runtime to drive is five commands: `loopx quota should-run`, `loopx todo claim`, `loopx todo update`, `loopx refresh-state`, `loopx quota spend-slot`. A working connection looks like `loopx doctor` passing, a populated `.loopx/registry.json`, and `loopx status` showing a real objective, gate, and next todo — if any of those pieces are missing, the setup isn't finished yet.
Strengths
- ✓It layers on top of your existing agent runtime instead of replacing it — Codex, Claude Code, Cursor, or a custom runner still does the actual work.
- ✓Quota is checked before a turn spends anything and only debited after a validated writeback, a concrete guard against a scheduler burning compute on nothing.
- ✓The core tick is five small, named commands, which makes it easy to trace exactly what happened when a loop misbehaves.
- ✓Host integration is spelled out per runtime instead of one generic API doc — Codex App, Codex CLI, Claude Code, and OpenCode each get a specific start command.
- ✓No runtime dependencies outside the Python standard library keeps the install itself small and easy to audit.
What LoopX Does Not Do
- △The project describes itself as still early and is actively asking users where the control plane felt heavy — treat it as a young tool, not a mature one.
- △LoopX avoids being an autonomous production controller. Dangerous permissions, publishing, and production writes are designed to stay with a human, as is final ownership. This ensures your approval steps are not eliminated.
- △It adds another layer of local state (`.loopx/`, `.codex/goals/`) that has to travel with the project and stay out of git, on top of whatever state your runtime already keeps.
- △The documented requirements only cover macOS and Linux shells; Windows isn't mentioned as a supported environment.
- △Reward Memory, one of the newer capabilities, is explicitly experimental and default-off, so it's not something to depend on yet.
- △The 200+ hour usage evidence in the README comes from the project's own creator working on OpenViking and internal experiments, not from independent third-party case studies.
Frequently Asked Questions
LoopX is released under the MIT license, according to the repository's license file, so you can use, modify, and redistribute it with minimal restriction.
LoopX documents integration paths for Codex App, Codex App over SSH, Codex CLI, Claude Code, and OpenCode, plus a generic path for Cursor, shell, or a custom runner.
LoopX keeps the objective, gates, todos, evidence, and quota for a long-running agent job in one durable state layer, so context doesn't get lost when a chat session or single agent turn ends.
For LoopX to run, Python 3.11+ is needed, alongside curl, tar, and a shell environment on macOS or Linux. Git becomes necessary exclusively for a contributor clone install, while the Python package itself has no runtime dependencies apart from the standard library.
The README documents two 200+ hour elapsed-time trajectories, an OpenViking issue-fix contribution arc and an Auto ML experiment arc, as public-safe evidence, though both come from the project's own creator rather than independent third parties.
LoopX does not replace your agent runtime; it manages durable state and gates around Codex, Claude Code, Cursor, or another runtime while that runtime executes the actual work.
Alternatives
Who should try it — and who should skip
Try LoopX if you're already running Codex, Claude Code, or Cursor on work that spans days instead of minutes — issue fixes, research loops, recurring monitors — and you're tired of re-explaining state every time a session resets. Skip it if your agent tasks wrap up in a single sitting, or if you need a polished hosted product rather than a local, MIT-licensed, still-early tool you run and read yourself.
Related repositories
Still deciding about loopx?
One click hands the question to an AI along with this page — see what it says about loopx.