diff --git a/README.md b/README.md
index fea612a6ad..6aab04842a 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,12 @@
-**Turn long-horizon goals into verifiable results.**
+**Start with one goal. Keep long-running agent work verifiable.**
-A local-first [semantic control plane](https://loopx-project.github.io/loopx/blog/from-one-shot-agents-to-long-horizon-control/#control-plane) and [research workbench](#research-workbench) for long-running agent teams, across sessions and runtimes.
-Keep goals, decisions, ownership and evidence durable. Work with Codex, Claude Code, DeepSeek Harness and other runtimes you already use.
+Tell the Agent you already use what you want done. LoopX keeps the goal,
+work, approvals and evidence durable behind the scenes, so the next session can
+continue without making you learn LoopX internals first.
+Work with Codex, Claude Code, DeepSeek Harness and other runtimes. Advanced docs still expose the local-first semantic kernel, ownership model and research workbench.
[](https://github.com/loopx-project/loopx/releases/latest) [](LICENSE) [](docs/architecture/rfcs/typescript-control-plane-migration-v0.md) [](pyproject.toml)
@@ -21,9 +23,9 @@ A local-first [semantic control plane](https://loopx-project.github.io/loopx/blo
-## Start in two steps
+## Start with one goal
-**1. Install LoopX and its Agent skills.** Requires Python 3.11+ and
+**1. Install LoopX once.** Requires Python 3.11+ and
Node.js 22.22.3+ (24 LTS recommended).
```bash
@@ -32,15 +34,16 @@ python3 -m pip install --upgrade loopx && loopx workflow-skills --install
[Install options and upgrades](docs/guides/installing-loopx.md)
-**2. Give your Agent a concrete task.** Restart your Agent host, open your
-project, then send this in Codex:
+**2. Tell your Agent the outcome.** Restart your Agent host, open your project,
+then send one natural-language goal:
```text
$loopx speed up this project's slowest workflow; compare approaches and verify the gains
```
-Claude Code uses `/loopx `; see [host setup](#start-from-your-agent)
-for other runtimes. Prefer a guided first run? [Choose a task below](#try-loopx).
+LoopX turns that into visible tasks, gates and evidence as needed. Claude Code
+uses `/loopx `; see [host setup](#start-from-your-agent) for other
+runtimes. Prefer a guided first run? [Choose a task below](#try-loopx).
## 📰 News
@@ -64,6 +67,11 @@ for other runtimes. Prefer a guided first run? [Choose a task below](#try-loopx)
## Why LoopX
+You should not have to learn LoopX internals before the first useful action.
+The default path is goal-first: describe the outcome, let the Agent prepare the
+plan, and inspect the machinery only when a decision or debugging need calls
+for it.
+
An agent can finish a task in one session. Long-running work is harder:
objectives change, owner decisions appear, evidence goes stale, and agents
hand work to peers. A timer can keep a loop running without making it useful.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 802830b92f..7216beec0d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -4,10 +4,11 @@
-**让 Agent 把长程目标做成可验证的成果。**
+**从一个目标开始，让长程 Agent 工作可验证。**
-面向长程 Agent 团队的本地优先[语义控制面](https://loopx-project.github.io/loopx/blog/zh/from-one-shot-agents-to-long-horizon-control/#control-plane)与[研究工作台](#research-workbench)，跨会话、跨运行时延续工作。
-持久保留目标、决策、分工与证据，连接你已经在用的 Codex、Claude Code、DeepSeek Harness 等运行时。
+告诉你已经在用的 Agent 想完成什么。LoopX 在幕后持久保留目标、
+工作、审批与证据，让下一轮会话可以继续，而不要求你先学会 LoopX 内部机制。
+连接 Codex、Claude Code、DeepSeek Harness 等运行时。高级文档仍会展开本地优先语义内核、ownership 模型与研究工作台。
[](https://github.com/loopx-project/loopx/releases/latest) [](LICENSE) [](docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md) [](pyproject.toml)
@@ -21,9 +22,9 @@
-## 两步开始
+## 从一个目标开始
-**1. 安装 LoopX 和 Agent 技能。** 需要 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS）。
+**1. 安装一次 LoopX。** 需要 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS）。
```bash
python3 -m pip install --upgrade loopx && loopx workflow-skills --install
@@ -31,13 +32,14 @@ python3 -m pip install --upgrade loopx && loopx workflow-skills --install
[其他安装方式与升级说明](docs/guides/installing-loopx.md)
-**2. 给 Agent 一个具体任务。** 重启 Agent 宿主，打开项目，再在 Codex 对话中输入：
+**2. 告诉 Agent 你想要的结果。** 重启 Agent 宿主，打开项目，再发送一个自然语言目标：
```text
$loopx 优化这个项目最慢的流程，对比方案并验证性能提升
```
-Claude Code 使用 `/loopx <复杂任务>`；其他运行时见[宿主接入](#从你已经在用的-agent-启动)。
+LoopX 会按需把它变成可见的任务、决策门和证据。Claude Code 使用
+`/loopx <复杂任务>`；其他运行时见[宿主接入](#从你已经在用的-agent-启动)。
想跟着教程试一次？[选择一个入门任务](#试用-loopx)。
## 📰 最新动态
@@ -60,6 +62,9 @@ Claude Code 使用 `/loopx <复杂任务>`；其他运行时见[宿主接入](#
## 为什么需要 LoopX
+第一次有用动作之前，你不需要先学会 LoopX 内部机制。默认路径是目标优先：
+描述结果，让 Agent 准备计划；只有决策或调试需要时，再查看背后的机制。
+
一个 Agent 可以在单次会话里完成任务。长程工作更难：目标会变化，用户决策会出现，
证据会过期，多个 Agent 会交接。定时器能让任务继续运行，却不能保证仍在做有用的工作。
diff --git a/apps/presentation/site/src/App.tsx b/apps/presentation/site/src/App.tsx
index 9a7d2b58a4..74f2c15204 100644
--- a/apps/presentation/site/src/App.tsx
+++ b/apps/presentation/site/src/App.tsx
@@ -32,26 +32,27 @@ import mlEvidenceUrl from "../../../../docs/assets/long-running-loop-ml-experime
type Language = "en" | "zh";
const setupPrompts: Record = {
- en: `Connect the current project to LoopX: https://github.com/loopx-project/loopx
+ en: `Help me start LoopX in the current project: https://github.com/loopx-project/loopx
Do not clone LoopX. Follow the README Quick Start to use the no-clone installer and \`loopx doctor\`, then reuse or \`loopx connect/bootstrap\` the current project state.
-After setup, first report the project connection status, current user gate, top agent todo, next safe action, and available commands.
+After setup, first report whether the project is connected, then ask me for one natural-language goal unless I already included it.
-Then I will use \`/loopx \` to begin real work.
-When you receive \`/loopx \`, first provide a concise ordered plan, then write it as P0/P1/P2 todos so I can see what needs to be done, what is blocked by a gate, and what the next safe action is.`,
- zh: `把当前项目接入 LoopX: https://github.com/loopx-project/loopx
+When you receive \`/loopx \`, first provide a concise ordered plan, then write it as P0/P1/P2 todos so I can see what needs to be done, what is blocked by a gate, and what the next safe action is.
+
+Keep LoopX internal terms behind advanced or debugging explanations unless a decision requires them.`,
+ zh: `帮我在当前项目启动 LoopX: https://github.com/loopx-project/loopx
不要 clone LoopX；按 README Quick Start 使用 no-clone installer、
\`loopx doctor\`，复用或 \`loopx connect/bootstrap\` 当前项目状态。
-接入后先汇报：项目连接状态、当前 user gate、top agent todo、
-next safe action，以及可用命令。
+接入后先汇报项目是否已连接；如果我还没有给目标，就先问我要一个自然语言目标。
-然后我会直接用 \`/loopx <复杂任务>\` 开始真实工作。
收到 \`/loopx \` 后，先给出简洁有序计划，再把它写成
P0/P1/P2 todos，让我能看到当前要做什么、什么被 gate 卡住、
-下一步安全动作是什么。`,
+下一步安全动作是什么。
+
+LoopX 内部机制术语默认放在高级或调试说明里，只有决策需要时再展开。`,
};
const shellSetupCommand = `curl -fsSL https://loopx-project.github.io/loopx/install.sh | bash
@@ -69,13 +70,13 @@ const macAppGuideUrl = "https://github.com/loopx-project/loopx/blob/main/apps/de
const content = {
en: {
nav: ["Product", "Workflow", "Learn"],
- eyebrow: "The control plane for long-running AI agents",
+ eyebrow: "Start long-running agent work with one goal",
title: {
- first: "Long-running agents.",
- secondPrefix: "Lasting ",
- secondAccent: "progress",
+ first: "Tell your agent the outcome.",
+ secondPrefix: "Keep ",
+ secondAccent: "progress visible",
},
- body: "Turn complex work into durable goals, coordinated tasks, and reviewable results. LoopX keeps your agents moving across sessions. You keep the judgment.",
+ body: "Use the agent you already trust. LoopX turns one natural-language goal into durable work, gates, and evidence behind the scenes, so the next session can continue without making you learn LoopX internals first.",
copy: "Get started",
mac: {
download: "Download for Mac",
@@ -84,13 +85,13 @@ const content = {
guide: "Install and first launch",
},
setup: {
- eyebrow: "Set up LoopX",
- title: "Choose how you want to start.",
- body: "Use your current agent for the guided path, or copy the shell commands for a manual setup.",
- agentTitle: "Agent setup",
- agentBody: "Give the complete setup prompt to Codex, Claude Code, OpenCode, TraeX, Pi, or another shell-capable agent.",
- shellTitle: "Shell setup",
- shellBody: "Install LoopX, check the CLI, and connect the current project yourself.",
+ eyebrow: "Goal-first setup",
+ title: "Start from the outcome.",
+ body: "Give your current agent one setup prompt, then send the goal. Shell remains available when you want the manual path.",
+ agentTitle: "Guided agent start",
+ agentBody: "Ask Codex, Claude Code, OpenCode, TraeX, Pi, or another shell-capable agent to connect this project and keep the machinery behind the scenes.",
+ shellTitle: "Manual shell setup",
+ shellBody: "Install LoopX, check the CLI, and connect the current project when an agent cannot run the setup for you.",
copy: "Copy",
copied: "Copied",
close: "Close setup",
@@ -112,29 +113,29 @@ const content = {
nextBody: "Keep independent tasks moving while review waits",
},
proof: [
- ["Explicit authority", "Agents move fast without silently taking control."],
- ["Durable state", "The next session resumes from governed state, not memory."],
+ ["No vocabulary tax", "Start from the outcome; open LoopX details only when they matter."],
+ ["Durable work", "The next session resumes from governed state, not memory."],
["Reviewable evidence", "Every transition leaves a result another person can verify."],
],
- sectionEyebrow: "One governed lifecycle",
- sectionTitle: "Long-running work stays legible.",
- sectionBody: "The runtime executes. LoopX preserves the control state that lets the work continue safely across sessions, hosts, and providers.",
+ sectionEyebrow: "One goal-first lifecycle",
+ sectionTitle: "Useful work can start before the machinery is familiar.",
+ sectionBody: "Your runtime executes. LoopX preserves the durable state that lets the work continue safely across sessions, hosts, and providers.",
steps: [
- ["01", "Lifetime goal", "One durable direction"],
- ["02", "Authority gate", "A concrete decision"],
- ["03", "Agent lanes", "Scoped continuation"],
- ["04", "Evidence", "A validated outcome"],
- ["05", "Next run", "Recoverable progress"],
+ ["01", "One goal", "A natural-language outcome"],
+ ["02", "Plan", "Visible work to do"],
+ ["03", "Gate", "A concrete decision"],
+ ["04", "Evidence", "A validated result"],
+ ["05", "Resume", "Recoverable progress"],
],
capabilities: {
- eyebrow: "Across providers, runtimes, and hosts",
- title: "One governed loop across agent runtimes.",
- body: "Codex, Claude Code, OpenCode, TraeX, Pi, and custom runners can share one stateful goal lifecycle while each agent stays inside an explicit scope.",
+ eyebrow: "Default simple, kernel intact",
+ title: "A natural entry backed by durable state.",
+ body: "Codex, Claude Code, OpenCode, TraeX, Pi, and custom runners can share one durable lifecycle. First contact starts with one goal; advanced surfaces expose ownership, scheduling, recovery, and protocols when needed.",
items: [
- ["01", "Durable state", "Goals, decisions, todos, claims, quota, run history, and handoffs survive session boundaries."],
- ["02", "Cross-runtime", "Change the executor or host without reconstructing the objective from chat history."],
- ["03", "Gate aware", "A blocked P0 stays visible while independent P1 and P2 lanes continue safely."],
- ["04", "Outcome driven", "Every run writes validation, ownership, review, and handoff evidence into the next loop."],
+ ["01", "Goal-first entry", "Start from a natural-language outcome; LoopX records the durable Goal and Todo structure as work becomes concrete."],
+ ["02", "Cross-runtime continuity", "Change the executor or host without reconstructing the objective from chat history."],
+ ["03", "Gate-aware progress", "A blocked P0 stays visible while independent P1 and P2 lanes continue safely."],
+ ["04", "Reviewable outcomes", "Every run writes validation, ownership, review, and handoff evidence into the next loop."],
],
},
explore: {
@@ -153,11 +154,11 @@ const content = {
},
learn: {
eyebrow: "Developer book",
- title: "Choose your path into LoopX.",
+ title: "Go deeper when you are ready.",
body: "A bilingual, protocol-first guide for developers who want to understand the control plane, connect a real project, or contribute along the right ownership boundary.",
open: "Open the Developer Book",
cards: [
- ["01", "Understand the control plane", "Build the model from sessions and Goals through durable state, authority, governed turns, and recovery.", "Start with foundations"],
+ ["01", "Understand the kernel", "Build the model from sessions and Goals through durable state, authority, governed turns, and recovery.", "Start with foundations"],
["02", "Connect an existing project", "Let your agent establish the Goal, identity, Host, and Git boundary, then verify the result.", "Follow project onboarding"],
["03", "Contribute to LoopX", "Trace protocols to source ownership, choose the right contribution surface, validate it, and prepare a focused PR.", "Open the contribution map"],
],
@@ -178,23 +179,23 @@ const content = {
},
quickstart: {
eyebrow: "Manual fallback",
- title: "Prefer the shell? Install LoopX manually.",
- body: "Use this path when your current agent cannot run shell commands. The same official installer registers lightweight command entries for supported hosts.",
+ title: "Need the terminal path? Install LoopX manually.",
+ body: "Use this when your current agent cannot run shell commands or you want to inspect each step. The default product path still starts from one goal.",
guide: "Read the Quick Start",
inspect: "Inspect installer",
setup: "Setup options",
},
- footer: "Keep the loop moving. Keep the judgment human.",
+ footer: "Start with the goal. Keep the judgment human.",
},
zh: {
nav: ["产品", "工作方式", "学习"],
- eyebrow: "长程 AI Agent 的有状态控制面",
+ eyebrow: "从一个目标开始长程 Agent 工作",
title: {
- first: "让 Agent 持续推进。",
- secondPrefix: "让目标成为",
- secondAccent: "结果",
+ first: "告诉 Agent 你想完成什么。",
+ secondPrefix: "让进展",
+ secondAccent: "持续可见",
},
- body: "把复杂工作变成持久的目标、协同的任务和可审查的成果。跨越会话，Agent 接着做；关键判断，始终由你掌握。",
+ body: "继续使用你已经信任的 Agent。LoopX 在背后把一个自然语言目标变成持久工作、决策门和证据，让下一轮会话可以接着推进，而不要求你先学会 LoopX 内部机制。",
copy: "开始使用",
mac: {
download: "下载 Mac App",
@@ -203,13 +204,13 @@ const content = {
guide: "安装与首次启动",
},
setup: {
- eyebrow: "设置 LoopX",
- title: "选择你的开始方式。",
- body: "让当前 Agent 完成引导式接入，或复制 Shell 命令手动安装。",
- agentTitle: "Agent 接入",
- agentBody: "把完整设置指令交给 Codex、Claude Code、OpenCode、TraeX、Pi 或其他具备 Shell 能力的 Agent。",
- shellTitle: "Shell 接入",
- shellBody: "手动安装 LoopX、检查 CLI，并连接当前项目。",
+ eyebrow: "目标优先的设置",
+ title: "从结果开始。",
+ body: "把设置提示交给当前 Agent，然后直接发送目标；需要手动路径时，再使用 Shell。",
+ agentTitle: "Agent 引导启动",
+ agentBody: "让 Codex、Claude Code、OpenCode、TraeX、Pi 或其他具备 Shell 能力的 Agent 连接当前项目，并把机制细节默认放在幕后。",
+ shellTitle: "手动 Shell 设置",
+ shellBody: "当 Agent 不能替你执行 Shell 时，手动安装 LoopX、检查 CLI，并连接当前项目。",
copy: "复制",
copied: "已复制",
close: "关闭设置",
@@ -231,29 +232,29 @@ const content = {
nextBody: "审批等待中，继续推进不依赖审批的任务",
},
proof: [
- ["显式权限", "Agent 快速推进，但不会静默接管用户权力。"],
- ["持久状态", "下一轮从受治理状态恢复，而不是依赖聊天记忆。"],
+ ["无术语门槛", "先描述结果；LoopX 细节只在需要决策或调试时展开。"],
+ ["持久工作", "下一轮从受治理状态恢复，而不是依赖聊天记忆。"],
["可审查证据", "每次状态变化都留下可供他人验证的结果。"],
],
- sectionEyebrow: "一个受治理的生命周期",
- sectionTitle: "让长程工作始终清晰可读。",
- sectionBody: "Runtime 负责执行；LoopX 保存跨会话、Host 与 Provider 安全推进所需的控制状态。",
+ sectionEyebrow: "一个目标优先的生命周期",
+ sectionTitle: "先开始有用工作，再按需理解内核。",
+ sectionBody: "Runtime 负责执行；LoopX 保存跨会话、Host 与 Provider 安全推进所需的持久状态。",
steps: [
- ["01", "长期目标", "一个持久方向"],
- ["02", "权限 Gate", "一个具体判断"],
- ["03", "Agent 线路", "有边界地继续"],
+ ["01", "一个目标", "自然语言结果"],
+ ["02", "计划", "可见的待办"],
+ ["03", "Gate", "一个具体判断"],
["04", "Evidence", "一个验证结果"],
- ["05", "下一轮运行", "可恢复地推进"],
+ ["05", "恢复", "可继续的进展"],
],
capabilities: {
- eyebrow: "跨 Provider、Runtime 与 Host",
- title: "一套受治理的闭环，连接不同 Agent Runtime。",
- body: "Codex、Claude Code、OpenCode、TraeX、Pi 与自定义 Runner 可以共享同一套有状态目标生命周期，同时让每个 Agent 保持明确边界。",
+ eyebrow: "默认简单，内核完整",
+ title: "自然入口背后，是持久状态。",
+ body: "Codex、Claude Code、OpenCode、TraeX、Pi 与自定义 Runner 可以共享同一套持久生命周期。第一次接触从一个目标开始；需要时，高级界面再展开 ownership、调度、恢复与协议。",
items: [
- ["01", "持久状态", "目标、用户决策、Todo、Claim、Quota、运行历史与交接不会随会话结束而丢失。"],
- ["02", "跨运行时", "更换执行器或 Host 时，无需从聊天记录重建长期目标。"],
- ["03", "Gate-aware", "P0 等待决策时保持可见，独立的 P1、P2 线路可以安全继续。"],
- ["04", "结果驱动", "每轮运行都把验证、归属、审查和交接证据写入下一轮闭环。"],
+ ["01", "目标优先入口", "从自然语言结果开始；随着工作具体化，LoopX 写入持久 Goal 与 Todo 结构。"],
+ ["02", "跨运行时连续性", "更换执行器或 Host 时，无需从聊天记录重建长期目标。"],
+ ["03", "Gate-aware 进展", "P0 等待决策时保持可见，独立的 P1、P2 线路可以安全继续。"],
+ ["04", "可审查结果", "每轮运行都把验证、归属、审查和交接证据写入下一轮闭环。"],
],
},
explore: {
@@ -272,11 +273,11 @@ const content = {
},
learn: {
eyebrow: "开发者手册",
- title: "选择你的 LoopX 学习路径。",
+ title: "准备深入时，再打开内核。",
body: "为想要理解控制面、接入真实项目或在正确 ownership 边界上贡献的开发者准备的系统性双语协议指南。",
open: "打开开发者手册",
cards: [
- ["01", "理解控制面", "从会话与目标出发，逐步建立对持久状态、权限、治理回合与恢复的完整认知。", "从基础开始"],
+ ["01", "理解内核", "从会话与目标出发，逐步建立对持久状态、权限、治理回合与恢复的完整认知。", "从基础开始"],
["02", "接入已有项目", "让 Agent 建立 Goal、身份、Host 与 Git 边界，然后验证结果。", "跟随项目接入指南"],
["03", "贡献 LoopX", "从协议追踪到源码归属，选择正确的贡献面，验证后提交聚焦的 PR。", "打开贡献地图"],
],
@@ -297,13 +298,13 @@ const content = {
},
quickstart: {
eyebrow: "手动备用方案",
- title: "更习惯终端？可以手动安装 LoopX。",
- body: "当你使用的 Agent 无法执行 Shell 命令时使用这条路径。同一官方安装器会为受支持的 Host 注册轻量命令入口。",
+ title: "需要终端路径？可以手动安装 LoopX。",
+ body: "当你的 Agent 无法执行 Shell 命令，或你想逐步检查安装时使用这条路径。默认产品路径仍然从一个目标开始。",
guide: "阅读快速开始",
inspect: "查看安装脚本",
setup: "设置方式",
},
- footer: "让闭环持续运转，让判断始终属于人。",
+ footer: "从目标开始，让判断始终属于人。",
},
} as const;
diff --git a/apps/presentation/site/src/page-metadata.ts b/apps/presentation/site/src/page-metadata.ts
index 6ca994bf8c..24b109ba44 100644
--- a/apps/presentation/site/src/page-metadata.ts
+++ b/apps/presentation/site/src/page-metadata.ts
@@ -26,12 +26,12 @@ export const pageMetadata = {
home: {
path: "",
en: {
- title: "LoopX — Stateful control plane for long-running AI agents",
- description: "Keep long-running AI agents on track across sessions with durable goals, tasks, human approval gates and recovery. Works with Codex, Claude Code and other agent runtimes.",
+ title: "LoopX — Start long-running agent work with one goal",
+ description: "Tell Codex, Claude Code or another agent one natural-language goal. LoopX keeps the work, gates, evidence and recovery durable across sessions.",
},
zh: {
- title: "LoopX — 长程 AI Agent 的有状态控制面",
- description: "让 Codex、Claude Code 等 Agent 跨会话持续推进任务，用持久目标、任务看板、人工审批与恢复机制管理长程工作。",
+ title: "LoopX — 从一个目标开始长程 Agent 工作",
+ description: "给 Codex、Claude Code 等 Agent 一个自然语言目标。LoopX 跨会话保留工作、决策门、证据与恢复状态。",
},
},
sweMarathon: {