huangruiteng / loopx

LoopX is 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. LoopX 是用于长期运行 AI Agent 任务的本地控制平面。它能在 Codex、Claude Code、Cursor 或你自己的运行时执行有限轮次任务时，保持目标、门控、待办事项、证据、配额和交接工作的稳定性。

把会干活的 Agent，接成可管理、可复盘、可持续改进的数字员工。 (This is the original Chinese tagline provided in the source.)

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. 作为一种轻量级状态内核和与 Agent 无关的本地控制平面，LoopX 专为循环工程设计，使长期运行的任务变得可审查、可重启，并更易于在不同轮次、工具和 Agent 之间进行交接。它不会取代你的 Agent 运行时。它是面向长期运行的 AI Agent 和协作 Agent 团队的循环工程工具。保持循环运转，并将判断权留给人类。

Why LoopX

为什么选择 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. Agent 可以在单次会话中完成任务，但长期运行的任务则更具挑战：目标会发生变化，所有者会做出决策，证据会过时，Agent 需要将工作移交给同伴，且调度程序可能会在没有有效进展的情况下持续消耗资源。仅靠聊天记录和计时器不足以管理这些过程。

LoopX keeps the durable control state in one compact layer: 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

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. 一个有用的思维模型是为长期任务设计的“Agent 原生看板”。卡片承载了身份、权限、证据和延续性。移动操作是经过验证的算子，如声明（claim）、门控（gate）、监控（monitor）和回写（writeback）。看板只是一个投影，LoopX 的状态始终是事实的唯一来源。注册的 Agent 互为同伴。声明、租约、任务边界、能力和类型化的延续性决定了下一个执行者；无需持久的领导者身份。

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 适用于以下场景：多天的工程、研究、基准测试或实验目标；必须保留范围、证据和审查状态的 Issue 和 PR 循环；周期性的心跳或监控工作；带有所有者、安全性、发布或私有数据门控的项目；需要管理所有权、租约和交接的协作 Agent 团队；以及需要让非工程操作员也能看懂进展的创作、研究或运营工作流。

LoopX is not an autonomous production controller. Dangerous permissions, publishing, production writes, and final ownership stay with the human. LoopX 不是一个自主的生产控制器。危险权限、发布、生产环境写入以及最终所有权仍由人类掌控。

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. 这些不是单轮演示。OpenViking 的 Issue-Fix 和 Auto ML 轨迹各自跨越了 200 多个小时的循环生命周期，涵盖了许多有限轮次、决策和证据更新。生命周期是指项目的挂钟时间，而非 200 小时的连续模型执行，也不是对无人值守生产自主性的声明。打开每个可视化图表，即可查看跨轮次保留的公共安全图谱、证据分支和决策。

Open-Source Issue Fix: 200+ hour public contribution arc: PR delivery and reusable fix knowledge evolve together. 开源 Issue 修复：200 多小时的公共贡献弧线：PR 交付与可复用的修复知识共同演进。
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. Auto ML 实验：200 多小时的所有者运行实验弧线：假设、匹配的证据、无效的谱系、运行中的副本以及提升/停止门控都在一个图表中可见。

Try LoopX

尝试 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. 要求：Python 3.11+、curl、tar 以及 macOS 或 Linux shell。仅在贡献者克隆/灰度工作流中需要 Git。该 Python 包除了标准库外没有其他运行时依赖。

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: 如果项目尚未初始化且 connect 提示缺少状态，请使用引导路径：

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. LoopX 应该复用现有状态而不是覆盖它。请确保 .loopx/、.codex/goals/ 和 .local/ 被忽略。