LoopX
The local control plane for long-running AI agent work.
Keep objectives, gates, todos, evidence, quota, and handoffs stable while Codex, Claude Code, Cursor, or your own runtime executes bounded turns.
Public website · Docs · Try LoopX · See real loops · How it works · User manual · 简体中文
把会干活的 Agent，接成可管理、可复盘、可持续改进的数字员工。
A lightweight state kernel and agent-agnostic local control plane for loop engineering, LoopX keeps long-running work reviewable, restartable, and easier to hand off across turns, tools, and agents. It does not replace your agent runtime.
Loop engineering for long-running AI agents and peer agent teams.
Keep the loop moving. Keep the judgment human.
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:
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
These are not one-turn demos. The OpenViking Issue-Fix and Auto ML trajectories each span 200+ hours of elapsed loop lifetime across many bounded turns, decisions, and evidence updates. Elapsed lifetime is wall-clock project time, not 200 hours of continuous model execution or a claim of unattended production autonomy. Open each visual to inspect the public-safe graph, evidence branches, and decisions preserved across turns.
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
200+ hour owner-run experiment arc: hypotheses, matched evidence, invalid lineages, running replicates, and promote/stop gates remain visible in one graph.
The redacted public-safe graph preserves decision lineage across that 200+ hour elapsed window. It is trajectory evidence, not a claim of continuous compute, independent reproduction, or a production result.
Auto Research
Proposer, executor, and evaluator/promoter agents iterate in parallel while todo, quota, evidence, and targeted wake remain visible.
More inspectable surfaces:
the public homepage for the product narrative, quick start, and long-running evidence;
the showcase catalog , including blocked-P0 safe rotation , LoopX self-iteration , and dynamic workflow orchestration ;
the cross-runtime implementation review demo ;
the public user manual .
Try LoopX
Requirements: Python 3.11+, curl , tar , and a macOS or Linux shell. Git is only needed for contributor clone/canary workflows. The Python package has no runtime dependencies outside the standard library.
Install without cloning:
Then connect from your project root:
If the project has not been initialized and connect tells you state is missing, use the guided path:
LoopX should reuse existing state rather than overwrite it. Keep .loopx/ , .codex/goals/ , and .local/ ignored.
Start From Your Agent
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 , or the Claude Code adapter .
For custom runners, read Embed LoopX in Your Agent Runner and the worker bridge install contract . The core tick is deliberately small:
A successful connection has:
loopx doctor passing;
.loopx/registry.json and a projected active goal state;
loopx status showing the current objective, concrete user gate, and next agent todo;
a visible loop driver or an exact activation instruction;
local runtime state ignored rather than committed.
Clone-based install is only for contributors who want the live canary wrapper:
Capabilities
LoopX folds its control-plane mechanics into five questions:
Control-Plane Surface
The shipped primitives include lifetime goals, concrete user gates, audited safe fallbacks, peer todo ownership, quota and steering, compact run history, evidence-backed handoff, a read-first management surface, project-level value signals, and public/private boundary checks.
Runtime Responsibilities
The execution path is Agent -> Capability -> Provider ; the control path returns Provider readback -> Capability transition -> Kernel . An extension is how an optional provider is packaged and managed, not another control-plane owner. See Architecture and Extensions and Capabilities .
Advanced Paths
The first useful loop does not require every optional surface. Add these only when the work needs them.
Inspect the current goal's read-only capability catalog before enabling an advanced path:
Without --execute , this reports current/default state, fit, boundaries, and copyable commands without changing project state.
Presets and Auto Research
Safe presets cover daily triage, changelog drafts, and PR watching. The one-command research path coordinates proposer, executor, and evaluator/promoter roles while keeping quota and evidence visible. See the beginner preset guide and Auto Research command path .
Preset inspection is read-only. For a connected recurring goal, loopx ready-score --goal-id <goal-id> --agent-id <agent-id> reports whether the loop is ready to run repeatedly.
Governed Turns
LoopX can generate one pure, bounded turn decision from a validated receipt, fresh quota state, and a provider-neutral budget. The current Codex CLI quickstart and activation contract are documented in LoopX Turn for Codex CLI .
Explore Graph and Harness
Explore is supported, optional, and default-off. It works best when a task has a measurable offline evaluation, baseline, treatment, and guardrails; it is not a substitute for production approval. Start with the Explore capability and its Lark presentation mapping .
Review Agent Work
Use loopx review-packet for a compact owner-facing view of decisions, evidence, validation, and unresolved gates. The intelligent management surface describes the operator model; the project-level reward model describes conservative value signals across output quantity, quality, token cost, and user attention cost.
For one concrete peer workflow, see the cross-runtime implementation review demo : Claude implements and Codex reviews while LoopX keeps ownership, evidence, quota, and handoff explicit.
App and Projection Paths
Local read-first UI: dashboard guide
Public product overview: public homepage
Documentation portal: hosted docs
Feishu/Lark projection: Lark Kanban adapter
Generic host integration: integration guide
Custom multi-agent runner: custom runner integration
Optional projections make state easier to inspect; they do not become the source of truth.
Operating and Recovery
Start daily inspection with:
Automatic turns must check quota first and append spend only after validated writeback. Quiet skips, preflight failures, and dry-run previews do not spend. When a user gate blocks one lane, a separately audited safe fallback may continue, but it must not bypass the gate.
Peer agents use loopx todo claim before delivery and loopx todo update after validation so ownership and evidence remain visible.
Scheduler cadence follows quota should-run.scheduler_hint ; installed Codex App automations acknowledge the current hint through the returned ack_hint.cli_args . Collision recovery, monitor semantics, self-repair, and the exact operator commands are maintained in Getting Started , Quota Allocation , and Long-Task Cadence Policy .
Before publishing public docs or examples:
Advanced Documentation
Start with the path that matches your role. Use the hosted documentation portal for the published docs site; the documentation index remains the complete source map.
Use and Operate
Getting Started : install, connect, diagnose, daily workflow, heartbeats, dashboard, development, and commands.
User Manual : public onboarding, concepts, FAQ, and selected cases.
Showcase Catalog : public-safe cases and evidence labels.
Update Notes : public-safe progress notes.
Release Readiness : install/update paths, compatibility gates, release notes, and safe-to-depend-on surfaces.
Dashboard and Status Data Contract .
Understand the Control Plane
Architecture : lifetime-goal invariant and kernel.
State Interaction Model : actors, stores, interaction contract, and writeback.
Interaction Pattern Catalog : reusable routing, gate, evidence, projection, and planning patterns.
Loop Engineering Principles and Pitfalls and the Chinese version .
Control-Plane Developer Course : nine Chinese, code-led lectures.
Product Vision : the broader Loop Agent direction.
Integrate and Extend
Integration Guide
Custom Agent Runner Integration
Worker Bridge Install Contract
Extensions and Capabilities
Codex App Host Command Registry
Heartbeat Automation Prompt
Lark Kanban Adapter
Reward Memory Architecture
Validate and Govern
Quota Allocation
Public/Private Boundary
Benchmark Developer Workflow
Project-Level Reward Model
Project Governance
Authors and Contributors
Project History
Name and Marks
Community and Feedback
LoopX is still early. The most useful feedback comes from real long-running agent projects: where the control plane helped, where it felt heavy, and which gates or handoffs disappeared from view.
Use GitHub Issues for reproducible bugs, install problems, and feature requests.
Open PRs for docs fixes, showcase writeups, and small public-safe examples.
Chinese-speaking users and contributors can join the Lark developer group. To join the WeChat group, add huangrt00 and include LoopX in the friend request.
Lark developer group
WeChat: huangrt00 Mention LoopX for a group invitation
LoopX project mark
Contributing
External contributors should start with Contributor Tasks for public, claimable work and Contributing for setup, validation, and boundary rules. Project roles and public history are recorded in Governance , Authors and Contributors , and Project History .
LoopX keeps local active state separate from the public repository. Do not commit .loopx/ , .codex/goals/ , live ACTIVE_GOAL_STATE.md , raw benchmark traces, credentials, private logs, or operator artifacts.
Current Status
The v0.4.x line is an early but usable local control plane for long-running agent work. It is not a full agent platform, an agent runtime, or an autonomous production controller.
Today LoopX ships a durable state kernel for goals, typed todos and decision scopes, peer claims and leases, evidence and writeback, quota-aware scheduling, and cross-turn continuation. Guided start, recurring heartbeat, isolated Codex CLI turns, evidence-backed Issue-Fix admission, optional Explore and auto research paths, public validation canaries, and a read-first multi-project dashboard build on that shared control state.
Support levels remain explicit. The state and CLI contracts are the stable center; several host integrations and advanced paths are optional, default-off, or experimental. LoopX does not grant credentials, approve destructive or production actions, publish on a user's behalf without authorization, or turn an unverified run into evidence of success.
The next milestones are simpler installation and host packaging, broader typed runtime adapters, stronger terminal acceptance across repeated public loops, independent adoption and outcome evidence, and a more polished management surface.
License
MIT. See LICENSE .