loopx-agent · Oct 30, 2026 · Oct 30, 2026
@@ -23,27 +23,24 @@ A local-first [semantic control plane](https://loopx-project.github.io/loopx/blo
 
 ## Start in two steps
 
-With Python 3.11+ and Node.js 22.22.3+ (24 LTS recommended), install once:
+**1. Install LoopX and its Agent skills.** Requires Python 3.11+ and
+Node.js 22.22.3+ (24 LTS recommended).
 
 ```bash
 python3 -m pip install --upgrade loopx && loopx workflow-skills --install
 ```
 
-Restart your Agent host, open your project, then give Codex a concrete task:
+[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:
 
 ```text
 $loopx speed up this project's slowest workflow; compare approaches and verify the gains
 ```
 
-Claude Code uses `/loopx <complex task>`. [Other hosts, install options and upgrades ↓](#try-loopx)
-
-**New to LoopX?** Start with the [first bug-fixing loop](docs/guides/first-bugfix-loop.md):
-reproduce a bug in a small Python project, let the Agent fix it, then check the patch.
-
-- **Use your own project:** follow the [coding agent guide](docs/guides/long-running-coding-agents.md)
-  to set up your host and resume work across sessions.
-- **Use the App:** follow the [illustrated Workspace guide (中文)](docs/guides/personal-workspace-user-guide.md)
-  to manage projects, conversations and results.
+Claude Code uses `/loopx <complex task>`; see [host setup](#start-from-your-agent)
+for other runtimes. Prefer a guided first run? [Choose a task below](#try-loopx).
 
 ## 📰 News
 
@@ -88,7 +85,7 @@ protected actions.
 
 | What you want to do | Start here |
 | --- | --- |
-| Keep a coding or research agent working across sessions | [Install and start](#try-loopx) |
+| Keep a coding or research agent working across sessions | [Install and start](#quick-start) |
 | Manage personal projects, schedules and decisions in one place | [Personal Agent Workspace](#meet-the-personal-agent-workspace) |
 | Let agents collaborate and deliver verifiable results | [Agent collaboration guide](docs/product/use-cases/cross-runtime/README.md) |
 
@@ -212,35 +209,34 @@ from this reproducible workspace. [Scenarios and replay instructions](demo/works
 
 ## Try LoopX
 
-Install once:
+Choose a walkthrough with a result you can inspect:
 
-```bash
-python3 -m pip install --upgrade loopx && loopx workflow-skills --install
-```
+| Start with | What you'll do |
+| --- | --- |
+| [Your first bug-fixing loop](docs/guides/first-bugfix-loop.md) | Reproduce two bugs in a small Python project, let the Agent fix them, then check the tests and patch. |
+| [Long-running coding work](docs/guides/long-running-coding-agents.md) | Fix an issue or keep improving your own repository, with review, evidence and recovery across sessions. |
+| [Personal Agent Workspace (中文)](docs/guides/personal-workspace-user-guide.md) | Follow the illustrated guide to manage projects, conversations, tasks and delivered results in the App. |
 
 ### Start From Your Agent
 
-Restart your Agent host, then start from a session opened on your project:
+After the [two-step setup](#quick-start), use the entry for your host in a
+session opened on your project:
 
-| Host | Type |
+| Host | Start and confirm continuation |
 | --- | --- |
-| Codex App, Codex CLI | `$loopx <complex task>` |
-| Claude Code | `/loopx <complex task>` |
+| Codex App | `$loopx <complex task>`; confirm the [heartbeat automation is saved](docs/guides/first-bugfix-loop.md#confirm-that-it-actually-started). |
+| Codex CLI | `$loopx <complex task>`; activate the generated [native `/goal`](docs/product/runtimes/codex-cli/codex-cli-packaged-install.md#current-user-path) in the same session. |
+| Claude Code | `/loopx <complex task>`; follow the [loop driver setup](docs/guides/newcomer-command-path.md#choose-the-loop-driver) for recurring work. |
 | DeepSeek Harness | Install the [native DSH plugin](packages/dsh-loopx-plugin/README.md), select the `loopx` skill, then describe the task |
 
-For example, give your Agent a concrete outcome:
-
-```text
-$loopx speed up this project's slowest workflow; compare approaches and verify the gains
-```
-
 LoopX reuses existing project state or connects the project, plans the work as
-Todos and sets up the host's loop. `loopx status` shows the goal, any decision
-waiting for you and the next Todo; `loopx doctor` diagnoses the install.
+Todos and guides host activation. Ask your Agent to confirm the active Goal,
+next Todo and continuation mechanism; a setup packet alone is not an active loop.
+Keep the host available for continued work. `loopx status` shows the Goal,
+decisions waiting for you and the next Todo; `loopx doctor` diagnoses the install.
 
-Requires Python 3.11+ and Node.js 22.22.3+ (24 LTS recommended).
-[Installing LoopX](docs/guides/installing-loopx.md) covers native Windows,
-`pipx`, upgrades, rollback and uninstall.
+[Installing LoopX](docs/guides/installing-loopx.md) covers native Windows, `pipx`,
+upgrades, rollback and uninstall.
 
 **Upgrading from 1.x?** Read the [2.0 migration and recovery guide](docs/product/releases/v2.0.0.md) before continuing existing Goals.
 

@@ -23,27 +23,22 @@
 
 ## 两步开始
 
-准备好 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS），安装一次：
+**1. 安装 LoopX 和 Agent 技能。** 需要 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS）。
 
 ```bash
 python3 -m pip install --upgrade loopx && loopx workflow-skills --install
 ```
 
-重启 Agent 宿主，打开项目，再给 Codex 一个具体任务：
+[其他安装方式与升级说明](docs/guides/installing-loopx.md)
+
+**2. 给 Agent 一个具体任务。** 重启 Agent 宿主，打开项目，再在 Codex 对话中输入：
 
 ```text
 $loopx 优化这个项目最慢的流程，对比方案并验证性能提升
 ```
 
-Claude Code 使用 `/loopx <复杂任务>`。[其他宿主、安装方式与升级说明 ↓](#试用-loopx)
-
-**第一次用 LoopX？** 先跟着[查 bug 入门教程](docs/guides/first-bugfix-loop.zh-CN.md)，
-用一个小型 Python 项目走完「复现 bug → Agent 修复 → 检查补丁」的流程。
-
-- **接入自己的项目：** 阅读[长程编程任务指南（English）](docs/guides/long-running-coding-agents.md)，
-  了解宿主接入与跨会话恢复。
-- **使用 App：** 跟着[图文工作区手册](docs/guides/personal-workspace-user-guide.md)，
-  管理项目、对话与交付结果。
+Claude Code 使用 `/loopx <复杂任务>`；其他运行时见[宿主接入](#从你已经在用的-agent-启动)。
+想跟着教程试一次？[选择一个入门任务](#试用-loopx)。
 
 ## 📰 最新动态
 
@@ -80,7 +75,7 @@ Claude Code 使用 `/loopx <复杂任务>`。[其他宿主、安装方式与升
 
 | 你想做什么 | 从这里开始 |
 | --- | --- |
-| 让编程或研究 Agent 跨会话持续干活 | [安装并开始](#试用-loopx) |
+| 让编程或研究 Agent 跨会话持续干活 | [安装并开始](#快速开始) |
 | 在一个入口管理个人项目、定时任务与待决事项 | [个人 Agent 工作区](#认识个人-agent-工作区) |
 | 让多个 Agent 分工协作，交付可验收的结果 | [Agent 协作指南](docs/product/use-cases/cross-runtime/README.md#中文指南) |
 
@@ -186,33 +181,31 @@ App 为 ad-hoc 签名，尚未 notarize。Windows 预览版目前手动更新，
 
 ## 试用 LoopX
 
-先安装一次：
+选一个能检查实际成果的教程：
 
-```bash
-python3 -m pip install --upgrade loopx && loopx workflow-skills --install
-```
+| 从哪里开始 | 你会完成什么 |
+| --- | --- |
+| [查 bug 入门教程](docs/guides/first-bugfix-loop.zh-CN.md) | 在小型 Python 项目中复现两个 bug，让 Agent 修复，再检查测试和补丁。 |
+| [长程编程任务指南（English）](docs/guides/long-running-coding-agents.md) | 修复 issue 或持续改进自己的仓库，保留评审、证据和跨会话恢复。 |
+| [图文工作区手册](docs/guides/personal-workspace-user-guide.md) | 跟着截图在 App 中管理项目、对话、任务和交付结果。 |
 
 ### 从你已经在用的 Agent 启动
 
-重启 Agent 宿主，在打开了你项目的会话里开始：
+完成上面的[两步启动](#快速开始)后，在打开了你项目的会话里使用对应入口：
 
-| 宿主 | 输入 |
+| 宿主 | 启动并确认续跑 |
 | --- | --- |
-| Codex App、Codex CLI | `$loopx <复杂任务>` |
-| Claude Code | `/loopx <复杂任务>` |
+| Codex App | `$loopx <复杂任务>`；确认 [heartbeat 自动化已保存](docs/guides/first-bugfix-loop.zh-CN.md#确认它真的开始执行)。 |
+| Codex CLI | `$loopx <复杂任务>`；在同一会话中激活生成的[原生 `/goal`](docs/product/runtimes/codex-cli/codex-cli-packaged-install.md#current-user-path)。 |
+| Claude Code | `/loopx <复杂任务>`；按 [loop driver 接入说明](docs/guides/newcomer-command-path.md#choose-the-loop-driver)设置周期性续跑。 |
 | DeepSeek Harness | 安装 [DSH 原生 Plugin](packages/dsh-loopx-plugin/README.md)，在技能选择器中选 `loopx`，然后直接描述任务 |
 
-例如，给 Agent 一个具体成果要求：
-
-```text
-$loopx 优化这个项目最慢的流程，对比方案并验证性能提升
-```
-
-LoopX 会复用项目已有状态或连接项目，把工作规划成 Todo，并设置宿主的循环。
-`loopx status` 显示目标、等你处理的决策和下一条 Todo；`loopx doctor` 诊断安装。
+LoopX 会复用项目已有状态或连接项目，把工作规划成 Todo，并引导宿主激活。
+让 Agent 回报当前 Goal、下一条 Todo 和实际续跑机制；生成 setup packet 不等于循环已经启动。
+持续工作需要宿主保持可用。`loopx status` 显示目标、等你处理的决策和下一条 Todo；
+`loopx doctor` 诊断安装。
 
-需要 Python 3.11+ 与 Node.js 22.22.3+（推荐 24 LTS）。原生 Windows、`pipx`、
-升级、回滚与卸载见 [Installing LoopX](docs/guides/installing-loopx.md)。
+原生 Windows、`pipx`、升级、回滚与卸载见[安装指南](docs/guides/installing-loopx.md)。
 
 **从 1.x 升级？** 继续既有 Goal 前，先读 [2.0 迁移与恢复指南](docs/product/releases/v2.0.0.md#中文指南)。