🔥 huangruiteng/loopx：面向长时运行 AI Agent 团队的轻量级循环工程状态内核

---

LoopX 是一个面向循环工程的轻量级状态内核和与 Agent 无关的本地控制平面，可让长时间运行的工作在跨越不同轮次、工具和 Agent 时保持可审查、可重启，并更易于交接。它不会替代你的 Agent 运行时。

面向长时间运行 AI Agent 与对等 Agent 团队的循环工程。

让循环持续推进。让判断留给人类。

Agent 可以在单次会话中完成一项任务。长时间运行的工作则更复杂：目标会变化，所有者决策会出现，证据会过期，Agent 会将工作交接给同伴，而且在已无有效状态转换可执行后，调度器仍可能持续消耗资源。聊天记忆和计时器不足以治理这类工作。

LoopX 将持久化控制状态保存在一个紧凑层中：

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 原生看板。卡片携带身份、权限、证据和延续信息。状态迁移由 claim、gate、monitor 和 writeback 等经过验证的操作符执行。看板只是投影；LoopX 状态仍是唯一事实来源。

已注册的 Agent 彼此对等。声明、租约、任务边界、能力和类型化延续共同决定下一个由谁行动；无需持久化的领导者身份。

在运行以下工作时，LoopX 很有用：

• 持续多天的工程、研究、基准测试或实验目标；
• 必须保留范围、证据和评审状态的 Issue 与 PR 循环；
• 周期性 heartbeat 或监控工作；
• 包含所有者、安全、发布或私有数据审批门的项目；
• 所有权、租约和交接至关重要的对等 Agent 团队；
• 需要让非工程背景运营者也能清晰理解进展的创作者、研究或运营工作流。

LoopX 并不是自主化生产控制器。危险权限、发布、生产写入和最终所有权仍由人类掌握。

这些不是单轮演示。OpenViking Issue-Fix 和 Auto ML 轨迹都跨越了 超过 200 小时的已流逝循环生命周期，其中包括多次有界轮次、决策和证据更新。流逝生命周期指项目的实际墙钟时间，而不是 200 小时的连续模型执行，也不意味着无人值守的生产自治。打开每个可视化内容，可查看在多轮之间保留的公共安全图谱、证据分支和决策。

超过 200 小时的公共贡献轨迹：PR 交付与可复用的修复知识共同演进。

LoopX 的创建者以 OpenViking 贡献者 身份使用这一路径。所展示的公共贡献序列，从首次创建 PR 到最新展示的评审或更新，跨越超过 200 小时的流逝时间。Issue-Fix 能力 将滚动更新的仓库上下文、带修订标记的修复知识和面向审阅者的偏好彼此分离；关联 PR、当前检出源码和测试仍是权威来源。

超过 200 小时的所有者运行实验轨迹：假设、匹配证据、无效谱系、运行中的复现实验以及推进/停止审批门，都在同一图谱中保持可见。

经脱敏处理的公共安全图谱保留了该超过 200 小时流逝窗口内的决策谱系。它是轨迹证据，而非关于持续计算、独立复现或生产结果的声明。

提议者、执行者和评估者/推进者 Agent 并行迭代，同时待办、配额、证据和定向唤醒保持可见。

更多可检查界面：

要求：Python 3.11+、curl、tar，以及 macOS 或 Linux Shell。只有贡献者克隆/canary 工作流需要 Git。该 Python 包在运行时除标准库外没有其他依赖。

无需克隆即可安装：

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

然后从项目根目录连接：

cd /path/to/your-project
loopx connect
loopx status

如果项目尚未初始化，且 connect 提示状态缺失，请使用引导路径：

loopx start-goal --guided --project . --goal-text "你的长期运行目标"

LoopX 应复用现有状态，而不是覆盖它。请将 .loopx/、.codex/goals/ 和 .local/ 保持在忽略列表中。

Host	推荐启动方式	循环驱动器
Codex App	请求 Agent 将该项目连接到 LoopX，运行 loopx doctor，保留现有状态，并报告当前审批门和下一项待办。随后使用 $loopx <complex task> 或从 /skills 中选择 loopx。	Codex App heartbeat 自动化，根据 quota should-run.scheduler_hint 刷新
通过 SSH 使用 Codex App	loopx agent-onboard --agent-type codex-app-ssh --project .	返回的可见 /goal <task_body>
Codex CLI	在项目中启动 codex，要求它连接并诊断 LoopX，随后使用 $loopx <complex task> 或 /skills。	可见的 /goal <task_body>；默认不进行隐藏式无头执行
Claude Code	安装选择加入的适配器，然后运行 /loopx <task>，再运行 /loop。	由 LoopX 控制的原生 Claude Code /loop
OpenCode	安装静态命令门面；如需周期性目标，请选择加入 --with-goal-bridge。	OpenCode 命令门面和显式目标桥接
Cursor、Shell 或自定义 Runner	使用安装器和 loopx doctor；手动连接，或从你的 Runner 调用 LoopX。	你的 Shell、调度器或 Runner

精确、可直接复制的配置消息和 Host 恢复路径位于 Getting Started。Host 集成可查阅 Codex App Host 命令注册表契约、Codex CLI 打包安装路径，或 Claude Code 适配器。

对于自定义 Runner，请阅读在 Agent Runner 中嵌入 LoopX和 worker bridge 安装契约。核心 tick 被刻意设计得很小：

loopx quota should-run      # 这个已注册 Agent 现在应当行动吗？
loopx todo claim            # 谁拥有这个工作切片？
loopx todo update           # 发生了什么变化？
loopx refresh-state         # 下一轮应看到什么？
loopx quota spend-slot      # 记录一个已完成、已验证的工作切片

一次成功的连接应具备：

• loopx doctor 通过；
• .loopx/registry.json 和投影出的活跃目标状态；
• loopx status 显示当前目标、具体的用户审批门和下一项 Agent 待办；
• 可见的循环驱动器或精确的激活说明；
• 本地运行时状态被忽略而非提交。

基于克隆的安装仅适用于希望使用实时 canary 包装器的贡献者：

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctor

LoopX 将其控制平面机制归纳为五个问题：

问题	LoopX 保持可见的内容
目标是什么？	活跃目标、明确范围和当前权限。
下一步会发生什么？	有序的用户和 Agent 待办、所有权、声明和租约。
什么需要人类判断？	具体的用户审批门，而不是模糊的“等待所有者”。
哪些证据发生了变化？	紧凑的运行历史、验证、阻塞因素和已接受的 writeback。
循环可以继续吗？	配额、能力、安全回退方案、调度器提示和停止条件。

界面	功能	起步命令
目标状态与状态页	跟踪活跃状态、待办、声明、审批门、证据、运行历史和首屏关注事项。	loopx status、loopx diagnose、loopx review-packet
配额与交互契约	决定一轮应交付、提问、等待、自我修复还是保持安静。	loopx quota should-run、配额分配
Agent 运行时桥接	让 Codex App、Codex CLI、Claude Code 和通用 Worker 与同一套防护机制保持一致。	loopx heartbeat-prompt、loopx codex-cli-bootstrap-message、loopx worker-bridge
运营者界面	渲染紧凑状态，同时不让浏览器成为状态权威来源。	loopx serve-status、dashboard、frontstage
外部投影	将待办和审批门投影到协作界面，同时由 LoopX 保持权威。	loopx lark-kanban、Lark Kanban 适配器
领域能力	封装可重复使用的工作通道，例如 Issue 修复、内容运营、价值连接器规划、ML 实验建议、基准证据和 Explore。	loopx issue-fix、loopx content-ops、loopx value-connectors、loopx ml-experiment、loopx benchmark、Explore
实验性上下文学习	让具名的已注册 Agent 通过被忽略、默认关闭的项目配置，试用与提供商无关的 Reward Memory。OpenViking 是可选提供商之一，而非全局依赖。	loopx reward-memory experiment-status、Reward Memory 架构
治理模式	捕获可复用的路由、审批门、证据、投影和规划模式。	交互模式、状态模型

已交付的原语包括生命周期目标、具体用户审批门、经审计的安全回退方案、对等待办所有权、配额与引导、紧凑运行历史、由证据支持的交接、优先读取的管理界面、项目级价值信号，以及公共/私有边界检查。

角色	职责
Agent	通过 Host/运行时进行规划、分析、使用工具并执行一次有界操作。
Provider	调用外部系统并返回观测结果、效果结果和回读数据。
Capability	定义调用方结果，对 Provider 输出进行标准化和验证，并提出类型化状态转换。
Kernel	负责持久化待办、审批门、监控器、已接受的 writeback、配额、恢复和调度。

执行路径为 Agent -> Capability -> Provider；控制路径则返回 Provider readback -> Capability transition -> Kernel。扩展是对可选 Provider 的封装和管理方式，而不是另一个控制平面所有者。参见架构和扩展与能力。

第一个有用的循环不需要启用所有可选界面。仅在工作需要时再添加它们。

在启用高级路径前，请检查当前目标的只读能力目录：

loopx configure-goal --goal-id <goal-id>

不带 --execute 时，该命令会报告当前/默认状态、适配性、边界和可复制命令，而不会改变项目状态。

预设与 Auto Research

安全预设涵盖日常分诊、更新日志草稿和 PR 监控。一键研究路径可协调提议者、执行者和评估者/推进者角色，同时让配额和证据保持可见。参见入门预设指南和 Auto Research 命令路径。

loopx preset list
loopx preset show daily-triage

预设检查为只读操作。对于已连接的周期性目标，loopx ready-score --goal-id <goal-id> --agent-id <agent-id> 会报告该循环是否已准备好重复运行。

LoopX 可基于经过验证的回执、最新配额状态和与 Provider 无关的预算，生成一次纯粹且有界的轮次决策。当前 Codex CLI 快速入门和激活契约记录于 LoopX Turn for Codex CLI。

Explore 图谱与 H

---

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.

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

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.

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.

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.

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.

Proposer, executor, and evaluator/promoter agents iterate in parallel while todo, quota, evidence, and targeted wake remain visible.

More inspectable surfaces:

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:

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

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.

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
OpenCode	Install the static command facade; opt in to --with-goal-bridge for recurring goals.	OpenCode command facade and explicit goal bridge
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, 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:

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 completed, validated slice

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:

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctor

LoopX folds its control-plane mechanics into five questions:

Question	What LoopX keeps visible
What is the objective?	The active goal, explicit scope, and current authority.
What happens next?	Ordered user and agent todos, ownership, claims, and leases.
What needs human judgment?	Concrete user gates instead of a vague "waiting for owner."
What evidence changed?	Compact run history, validation, blockers, and accepted writeback.
May the loop continue?	Quota, capabilities, safe fallback, scheduler hints, and stop conditions.
Surface	What it does
---	---
Goal state and status	Tracks active state, todos, claims, gates, evidence, run history, and first-screen attention.
Quota and interaction contract	Decides whether a turn should deliver, ask, wait, self-repair, or stay quiet.
Agent runtime bridges	Keeps Codex App, Codex CLI, Claude Code, and generic workers aligned with the same guard.
Operator surfaces	Renders compact status without making the browser the state authority.
External projections	Projects todos and gates into collaboration surfaces while LoopX remains authoritative.
Domain capabilities	Packages repeatable work lanes such as issue fixing, content operations, value connector planning, ML experiment advice, benchmark evidence, and Explore.
Experimental context learning	Lets named registered agents trial provider-neutral Reward Memory through ignored, default-off project configuration. OpenViking is one provider option, not a global dependency.
Governance patterns	Captures reusable routing, gate, evidence, projection, and planning shapes.

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.

Role	Responsibility
Agent	Plans, analyzes, uses tools, and performs one bounded action through a host/runtime.
Provider	Calls external systems and returns observations, effect results, and readback.
Capability	Defines the caller outcome, normalizes provider output, validates it, and proposes a typed transition.
Kernel	Owns durable todos, gates, monitors, accepted writeback, quota, recovery, and scheduling.

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.

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:

loopx configure-goal --goal-id <goal-id>

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.

loopx preset list
loopx preset show daily-triage

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.

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.

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.

Optional projections make state easier to inspect; they do not become the source of truth.

Start daily inspection with:

loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal

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:

loopx check \
  --scan-path README.md \
  --scan-path docs/ \
  --scan-path examples/

Start with the path that matches your role. The documentation index remains the complete map.

• 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

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

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.

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.

MIT. See LICENSE.