LoopX
The open, provider-neutral, stateful control plane for long-horizon agents.
Runs on top of Codex, Claude Code, Cursor, and other agent harnesses. LoopX preserves objectives, gates, todos, evidence, quota, and handoffs across turns; the harness executes bounded work.
Public website · Blog · Docs · Developer Book · Try LoopX · See real loops · How it works · 简体中文
Open and provider-neutral, LoopX is a lightweight state kernel and local-first
control plane for loop engineering. It runs on top of different agent harnesses
rather than replacing them, providing the long-horizon state, semantic
decisions about what happens next, governance, recovery, and human-agent
collaboration that keep long-running work reviewable, restartable, and easier
to hand off across turns, tools, and agents.
Loop engineering for long-horizon AI agents and peer agent teams.
Keep the loop moving. Keep the judgment human.
Learn LoopX
- Developer Book - the curated bilingual path from control-plane foundations to project onboarding and developer contributions. 中文版 · English
- Getting started - install, connect a project, and run your first governed loop. Guide
- Docs - the full reference and operations site. LoopX Docs
Meet the Personal Agent Workspace
Keep long-horizon goals in one local-first workspace. Goals, attention,
conversations, tasks, files, schedules, and recovery stay durable across days,
restarts, and harnesses. Reopen a project, inspect the previous turn’s state
and evidence, and continue the next permitted action.
LoopX 1.0 brings these long-horizon control states into the Personal Workspace. It gives you one place to:
- see what needs you, what is running, what is being watched, and what is
scheduled or stopped;
- configure Goal capabilities, distinguish machine defaults from Goal overrides,
and preview changes before applying them;
- steer a live turn, queue a message, or use the async inbox from a connected
Lark conversation with explicit Goal/Agent/session routing;
- inspect deliverable files, periodic reports, and their supporting evidence;
- continue across Codex, Claude Code, direct-model, and other registered Agent
sessions without losing Goal state or evidence;
- review protected changes through typed preview, explicit confirmation, and
receipts while LoopX state—not the browser—remains authoritative.
loopx dashboard
loopx dashboard is the supported browser/PWA launch path. You can also download
native desktop previews from the 1.0 release;
they reuse the same loopback services and Goal state. Apple Silicon macOS supports
signed App updates that pair the shell with its bundled runtime, plus repair and
recovery. Python 3.11+ is required; the App is ad-hoc signed, not notarized.
Windows preview installers currently use manual updates and a separately installed CLI.
Desktop installation, updates, and source development.
From a source checkout, run python -m demo.workspace serve to explore a community
event, a home-energy comparison, and a neighborhood website release. Each has four
work roles, 18 tasks, two decisions, and two watches. The screenshot above comes
from this reproducible workspace. Scenarios and replay instructions.
Watch the full 32-second walkthrough
· Read the workspace guide
· Try the five-minute tour
Why LoopX
An 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.
LoopX keeps the durable control state in one compact layer:
objective / issue / project
│
▼
LoopX state: objective + gates + todos + scope + evidence + quota
│
├─ human judgment needed? ── yes ─▶ ask a concrete question and wait
│
├─ safe fallback available? ──────▶ run one bounded agent slice
│
▼
Codex / Claude Code / Cursor / shell agent executes one turn
│
▼
write evidence + handoff + next todo ─▶ quota decides the next tick
Agent runtimes execute the work. 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.
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.
Registered agents are peers. Claims, leases, task boundaries, capabilities, and
typed continuation decide who acts next; no durable leader identity is
required.
LoopX is useful when you run:
- multi-day engineering, research, benchmark, or experiment objectives;
- issue and PR loops that must preserve scope, evidence, and review state;
- recurring heartbeat or monitor work;
- projects with owner, safety, publication, or private-data gates;
- peer-agent teams where ownership, leases, and handoff matter;
- creator, research, or operations workflows whose progress must remain
legible to a non-engineering operator.
LoopX is not an autonomous production controller. Dangerous permissions,
publishing, production writes, and final ownership stay with the human.
Evidence
The public OpenViking contribution sequence and the redacted, owner-run
Auto ML showcase each span 200+ hours of elapsed loop lifetime, preserving
bounded turns, decisions, and evidence updates. This measures wall-clock project
time, not continuous model execution or unattended production autonomy. Open
each visual to inspect the public-safe task graph, evidence branches, and
cross-turn decisions; each case states its source and reproducibility boundary.
Open-Source Issue Fix
200+ hour public contribution arc: PR delivery and reusable fix knowledge
evolve together.
LoopX's creator uses this path as an
OpenViking contributor.
The represented public contribution sequence spans more than 200 elapsed hours
from its first PR creation to the latest represented review or update. The
Issue-Fix capability keeps rolling
repository context, revision-stamped fix knowledge, and reviewer-facing
preferences separate; linked PRs plus current checkout source and tests remain
authoritative.
Auto ML Experiment
Redacted owner-run showcase: a 200+ hour experiment arc keeps hypotheses,
matched evidence, invalid lineages, running replicates, and promote/stop gates
visible in one graph.
The redacted public-safe graph preserves decision lineage across that 200+ hour
elapsed window. It is an owner-run showcase, not a claim of continuous compute,
independent reproduction, a production result, or company or employer
endorsement. The redacted image is not sufficient to reproduce the underlying
experiment independently.
Auto Research
Reproducible public KNN demo: proposer, executor, and evaluator/promoter agents
iterate in parallel while todo, quota, evidence, and targeted wake remain
visible.
This screenshot comes from LoopX's built-in exact-KNN demo. The public task,
editable and protected files, deterministic CPU evaluator, and dev/held-out
commands all live in this repository. Follow the
showcase walkthrough
or the demo command path to reproduce the
workflow; it is a demo result, not a production research claim.
Used In Real Projects
- Independent user ·
>13h C++ accuracy run. The user reported that a
multi-stage task stayed aligned, triggered public research, adopted a
public code-memory tool,
and improved final precision. Read the evidence boundary.
- Independent user ·
4d unattended run. The user reported four days
without human intervention, useful ongoing work, and a periodic report
surface. Read the redacted case.
- Independent user ·
7 merged PRs. A LoopX-attributed Engine refactor is
visible in a public issue and
seven merged PRs; attribution and the reported 1B+ token scale remain user
reports. Inspect the case.
These are the three strongest current cases, not the full inventory. Browse the
complete Showcase catalog for contributor cases,
creator dogfooding, reproducible demos, and explicit evidence-strength labels.
Exploratory Benchmark Studies
- SWE-Marathon:
Five execution modes on 15 matched tasks compare self-verification, scores,
and cost. More self-verification did not consistently yield higher scores.
- DeepSWE behavior analysis (Chinese):
Selected cases examine how domain hints relate to requirement retention and
verification choices, offering mechanism hypotheses for further testing.
SWE-Marathon has one trial per task and mode; DeepSWE uses selected cases and
post-hoc analysis. Neither establishes a general performance gain.
More inspectable surfaces:
Try LoopX
Requirements: Python 3.11+ and Node.js 22.6+; Node.js 24 LTS is recommended.
Use an active Python environment whose console scripts are on PATH; macOS and
Linux use a POSIX shell, while native Windows uses PowerShell 7. Node.js runs
the managed, idle-exiting TypeScript Effect core; LoopX starts it automatically.
Git is only needed for contributor clone/canary workflows.
Install from PyPI without cloning:
python3 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor
Existing installs can use loopx update plan and loopx update apply; LoopX
keeps the detected pip, pipx, or archive owner instead of switching channels.
On native Windows PowerShell 7, use the same PyPI release without a POSIX
compatibility layer:
py -3.11 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor
Restart your agent host after first install so it reloads the workflow skills.
See Installing LoopX for pipx, host
command surfaces, native Windows checkout installation, upgrade, rollback,
uninstall, and the archive fallback.
Then connect from your project root:
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"
LoopX should reuse existing state rather than overwrite it. Keep .loopx/,
.codex/goals/, and .local/ ignored.
Start From Your Agent
| Host |
Recommended start |
Loop driver |
| 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 App heartbeat automation, refreshed from quota should-run.scheduler_hint |
| Codex App over SSH |
loopx agent-onboard --agent-type codex-app-ssh --project . |
The returned visible /goal <task_body> |
| Codex CLI |
Start codex in the project, ask it to connect and diagnose LoopX, then use $loopx <complex task> or /skills. |
Visible /goal <task_body>; no hidden headless execution by default |
| Claude Code |
Install the opt-in adapter, then run /loopx <task> followed by /loop. |
Native Claude Code /loop gated by LoopX |
| KunlunCode |
Run loopx-kunluncode connect --project . --goal-id <goal-id> --agent-id <registered-agent-id>, add a bounded todo, then run loopx-kunluncode run --project .. |
Native Goal Pro through app-server; LoopX writes completion and quota only after strict verification |
| OpenCode |
Install the static command facade; opt in to --with-goal-bridge for recurring goals. |
OpenCode command facade and explicit goal bridge |
| Pi |
Install the opt-in goal extension with loopx slash-commands --install --surface pi, then use /loopx <task> from a trusted Pi session. |
Visible Pi goal extension gated by LoopX quota (loopx_goal_activate + agent_settled continuation) |
| ZCode |
Install the skill facade with loopx slash-commands --install --surface zcode, then invoke the $loopx skill (or /loopx <complex task>) from a ZCode session in the project. |
The ZCode session's own turn loop; every continuation enters through quota should-run |
| Antigravity CLI (agy) |
Install the skill facade with loopx slash-commands --install --surface agy, then invoke the loopx skill (or /loopx <complex task>) from an agy session in the project. |
The session's native /goal loop (audited until <!-- GOAL_COMPLETE -->) with schedule self-wakes while the session lives; the facade instructs every turn/wake to re-enter through quota should-run — advisory pacing, not a host-enforced gate |
| Kiro CLI |
Install the skill facade with loopx slash-commands --install --surface kiro-cli, then run /loopx <complex task> from a kiro-cli session in the project. |
The session's native /goal --max <N> <task_body> Done when: <criteria> loop, with the acceptance criteria stated inside the goal statement because the host derives them from it, bounded by the host's own iteration budget (default 5) and settled through the built-in goal completion contract; the facade instructs every turn and iteration to re-enter through quota should-run — advisory pacing, not a host-enforced gate |
| DeepSeek Harness (dsh) |
Install the native DSH plugin, select the loopx skill, and describe the task. The dsh goal-mode adapter remains available for headless turns. |
Native same-session continuation and GoalBar, or headless dsh segments; both remain gated by LoopX authority |
| Cursor, shell, or custom runner |
Use the installer and loopx doctor; connect manually or call LoopX from your runner. |
Your shell, scheduler, or runner |
The exact, copy-ready setup messages and host recovery paths live in
Getting Started. Host integrations can inspect
the Codex App host command registry contract,
the Codex CLI packaged install path,
the Claude Code adapter, the
KunlunCode native Goal adapter, the
Kiro CLI goal-mode adapter, or the
DeepSeek Harness turn adapter.
See the 60-second DSH × LoopX Replan recording and reproducible
fixture for the native path:
install the plugin, select one skill, change a material constraint, and inspect
the preserved decision trail.
For custom runners, start with the
minimal custom runtime example
(python3 examples/custom-runtime-minimal-cli-turn-smoke.py), then the full
Embed LoopX in Your Agent Runner
guide and the worker bridge install contract.
The core tick is deliberately small:
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 co
LoopX 是一个开放的、与模型提供方无关的控制平面，架设在 Codex、Claude Code、Cursor 等智能体运行环境之上。在长时间运行的 AI 智能体工作中，它能在多轮对话和多个会话之间持久保存目标、门禁、待办事项、证据、配额和交接信息。