LoopX Control Plane
Keep long-running, multi-agent work recoverable, reviewable, and ready for verified handoff.
Least privilege is supported by local-first operation, default-off experiments, read-only inspection, boundary tests, scoped workflow permissions, and checkout without persisted credentials. It is not full-score because the quick install pipes a remote script into a shell and optional projections and runtimes can reach external systems. User confirmation is thorough: concrete human gates, owner review, human retention of dangerous permissions and publishing, and an explicit prohibition on automatic release promotion are all evidenced. Data flow describes the Agent-Capability-Provider-Kernel path and the relationship between local state and external projections, but the supplied files do not document field-level flows for every adapter. Sensitive-data handling includes no telemetry, warnings against submitting credentials or internal content, compact projections that remove private fields, and a read-only scoped workflow secret; comprehensive encryption, retention, and deletion policies are not shown. Dependency security is strong: no core runtime dependencies, a pinned build dependency, bounded test dependencies, pinned or versioned Actions, and dependency review. External effects are gated by quotas, human decisions, claims, and validated writeback, but complete authorization behavior for every optional provider and projection is not present. Recovery is supported by restartable state, preservation of existing state, leases, history, and documented collision recovery, though no general transaction rollback or reversal of external writes is evidenced. Attribution earns full credit because creator demonstrations, independent-user reports, public contributions, and reproducible demos are distinctly labeled with their evidentiary limits.
The README, package metadata, security policy, and tests agree on local-first operation, Python requirements, the dependency model, owner review, and read/write boundaries. Architecture tests actively enforce dependency direction among kernel, extension, CLI, and presentation layers, supporting full self-consistency credit. Core dependency availability is favorable because it uses the standard library, but installation still relies on GitHub Pages, curl, tar, supported hosts, and optional ecosystems, with no demonstrated offline installation path. Failure messaging is thorough: tests show structured errors, nonzero exits, redaction of private paths, explicit insufficient-evidence decisions, and fail-closed regression handling.
The repository explicitly covers engineering, research, experiments, operations, content workflows, single agents, peer teams, and non-engineering operators, so audience and scenario coverage is thorough. Boundaries clearly separate runtime execution, provider observations, capability transitions, and kernel control, while repeatedly disclaiming autonomous production control. Triggering is precise through quota should-run decisions, scheduler hints, claims, leases, concrete human gates, audited fallbacks, and stop conditions; skips, preflight failures, and previews do not consume quota. Environment support spans Codex, Claude Code, Cursor, OpenCode, Pi, SSH, shell, and custom runners, but the quick path only establishes macOS/Linux and Python 3.11+ support, with no equivalent evidence for Windows or every host environment.
The README provides layered navigation across learning, installation, capabilities, architecture, operations, recovery, and advanced references, backed by a broader documentation index. Installation notes are detailed, including prerequisites, clone-free setup, connection, diagnosis, host-specific entry points, contributor installation, and success criteria. Naming stability is supported by versioned schemas and protocols, audited compatibility facades, and architecture tests. Examples are extensive, including a minimal custom runtime, reproducible KNN demo, cross-runtime workflow, showcases, and a user-manual/FAQ path. Limitations are unusually explicit: the product is not an autonomous production controller, optional features are default-off, humans retain final authority, and showcase evidence boundaries are stated. The MIT license is complete and consistent with package metadata. Versioning has a package version, release badge, latest-release security policy, and release-readiness reference, but no actual changelog content was supplied, so it is not full-score. Maintenance has a private vulnerability channel, a five-business-day acknowledgement target, and a latest-release support policy; however, authorship is only stated as LoopX contributors, publisher identity is unverified, and named maintainers or governance are absent.
Output usability is strong because status, history, review packets, structured JSON, concrete next actions, owner gates, and compact evidence directly support operation and handoff. Marginal value is supported by durable state, quota, leases, evidence, cross-runtime handoff, and a reproducible demo, but the strongest real-world outcome claims still include creator-operated, redacted, or user-reported cases without independent controlled validation. Cost-benefit is addressed through quota accounting, quiet skips, token and user-attention cost models, and baseline comparison structures, but no independently verifiable aggregate savings are provided.
Claim traceability is thorough: major examples point to concrete repository documents, public contributions, commands, demos, and stated authoritative sources. Cross-source corroboration exists across the README, metadata, security policy, workflows, and tests for architecture and safety claims, but real-world effectiveness remains largely repository-authored, creator-operated, or user-reported. Fact-inference separation is exemplary: verified public results, reports, demos, redacted evidence, elapsed wall-clock duration, continuous execution, and prohibited benchmark claims are explicitly distinguished.
- The quick install uses curl piped to a shell; pin and inspect the installer revision before adoption, especially in enterprise or privileged environments.
- The supplied evidence does not fully expose permissions, transmitted fields, or reversal behavior for external providers, Lark projections, schedulers, and host bridges; audit each before enabling it.
- Do not interpret the 200+ hour cases or independent-user reports as continuous unattended compute, production safety, or independently validated uplift.
- Only the latest published version is maintained, so deployments need an explicit upgrade and rollback policy.
- Publisher identity is unknown. This is not evidence of wrongdoing, but adopters should separately verify maintainers, release signing, and supply-chain provenance.
What does this agent do, and when should you use it?
LoopX is a lightweight state kernel and local-first control plane for long-running AI-agent workflows; it does not replace the runtime that performs the work. It persists objectives, decision gates, todos, scope, evidence, quotas, claims, and leases so work can resume and transfer across bounded turns. Codex, Claude Code, Cursor, shell agents, or custom runners execute each slice, while LoopX decides whether another turn should run, wait for human judgment, or stop. Its main interface is the `loopx` CLI, supplemented by integrations for Codex, Claude Code, generic workers, custom runners, a status dashboard, and Lark projections. Outputs include updated goal state, todos, evidence, run history, handoff information, and scheduler hints, with local state remaining authoritative. It fits engineering, research, and operational workflows that need durable oversight, but it does not approve production changes, grant dangerous permissions, or publish without authorization.
LoopX reads durable project state describing the active objective, scope, user gates, agent todos, claims, leases, evidence, and quota. A runner first calls loopx quota should-run to determine whether a registered agent may act and then uses loopx todo claim to take ownership of one work slice; Codex, Claude Code, Cursor, a shell agent, or a custom runtime performs the actual analysis and tool use. After validation, the runner records changes and evidence with loopx todo update, generates the next turn's state through loopx refresh-state, and accounts for the validated slice with loopx quota spend-slot. Operators inspect current state, history, failures, and review material through loopx status, loopx history, loopx diagnose, and loopx review-packet. Schedulers follow quota should-run.scheduler_hint; when a user gate blocks one lane, only a separately audited safe fallback may continue. Optional surfaces include loopx issue-fix, loopx content-ops, loopx value-connectors, loopx ml-experiment, loopx benchmark, Explore, Auto Research, the read-first dashboard, and Lark projections.
- A maintainer handling a multi-day issue or pull request can preserve scope, review status, fix evidence, and the next todo between agent sessions.
- A research or ML team running repeated experiments can track hypotheses, quota, evidence gates, replicates, stop conditions, and promotion decisions.
- A team using both Codex and Claude Code can make implementation, review, ownership, leases, and handoffs explicit in one shared control state.
- An operator running recurring heartbeat or monitoring work can use
quota should-runand scheduler hints to avoid spending turns when no useful transition remains. - A custom-agent developer can add durable goals and validated writeback to an existing runner using the minimal CLI-turn example and worker bridge contract.
- A team that needs non-engineering oversight can expose progress through the read-first dashboard or a Lark Kanban projection while keeping local LoopX state authoritative.
What are this agent's strengths and limitations?
- The control state is separated from execution, allowing Codex, Claude Code, Cursor, shell agents, and custom runners to share the same governance layer without tying the core to one model provider.
- Objectives, concrete human gates, todo claims, leases, evidence, quota, and handoff data live in one durable state model designed for multi-turn and peer-agent work.
- Quota prechecks, post-validation spending, stop conditions, and scheduler hints provide explicit controls for recurring automation.
- Local state remains the source of truth; dashboards and Lark boards are projections rather than competing state authorities.
- The repository documents copyable installation and CLI flows, a minimal custom-runtime example, and dedicated Codex and Claude Code integration paths.
- The documented installation requires Python 3.11+,
curl,tar, and a macOS or Linux shell; no native Windows installation path is provided. - LoopX is not an agent runtime or complete agent platform, so adopters must still supply Codex, Claude Code, Cursor, a shell agent, or their own executor.
- Claude Code needs an opt-in adapter, while several host integrations and advanced features remain optional, default-off, or experimental.
- It does not grant credentials, approve destructive or production actions, or assume publication authority, so human governance remains necessary.
- The public evidence mixes reproducible demos, redacted showcases, and user reports; some long-running outcomes cannot be independently reproduced and do not establish continuous compute or production autonomy.
How do you install or deploy this agent?
Requirements are Python 3.11+, curl, tar, and a macOS or Linux shell. Install over the network with:
curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctorThe Python package has no runtime dependencies outside the standard library. No API key or cloud credential is required by the documented core installation. Git is needed only for the contributor clone/canary workflow:
git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctorHow do you use this agent?
Connect an existing project from its root:
cd /path/to/your-project
loopx connect
loopx statusIf connect reports that state is missing, initialize a guided goal:
loopx start-goal --guided --project . --goal-text "Your long-running objective"A successful connection has a passing loopx doctor, .loopx/registry.json, projected active-goal state, and a loopx status view showing the objective, current user gate, and next agent todo. Keep .loopx/, .codex/goals/, and .local/ ignored rather than committed. A governed work slice follows this sequence:
loopx quota should-run
loopx todo claim
loopx todo update
loopx refresh-state
loopx quota spend-slotAutomated turns must check quota first and spend only after validated writeback. In Codex App or Codex CLI, use $loopx <complex task> after connection. Claude Code requires the opt-in adapter, followed by /loopx <task> and /loop. Custom-runner developers can begin with python3 examples/custom-runtime-minimal-cli-turn-smoke.py.
FAQ
Does LoopX perform coding, research, or external-system actions itself?
Does the core setup require a cloud account, API key, or paid service?
What happens when a task requires human judgment?
How does scheduled operation avoid wasting quota?
loopx quota should-run, and scheduling follows its scheduler_hint. Quiet skips, preflight failures, and dry runs do not spend quota; loopx quota spend-slot is used only after validated writeback.