AI 编程工作流层 hellowind777/helloagents

HelloAGENTS

给 AI 编程命令行加一层工作流：技能、项目知识、交付检查、更安全的配置写入，以及可恢复的执行。

[!IMPORTANT]
还在找 v2.x？旧的 Python 分支现在放在 helloagents-archive。v3 分支是完全重写的版本，基于 Node.js、Markdown 规则、技能和少量运行时脚本。

🏅 本项目由 LINUX DO 社区关联并认可。

目录

- HelloAGENTS 做什么
- 核心功能
- 快速开始
- 命令行管理
- 对话中的命令
- 项目知识库
- 工作流与交付
- 配置
- 各命令行如何接入
- 验证
- 常见问题
- 故障排查
- 许可协议

HelloAGENTS 做什么

AI 编程命令行跑得很快，但也可能只给建议就停下、跳过检查、丢掉项目上下文、任务一难就甩锅，或者活儿还没干完就报告完成。

HelloAGENTS 在 Claude Code、Gemini CLI、Grok Build、Cursor 和 Codex CLI 之上加了一层工作流。它把智能体锚定为有能力的执行者，拦住甩锅的套路，帮智能体选对路径、用上针对具体任务的技能、维护项目知识库，并在交付前验证成果。

没有 HelloAGENTS

有 HelloAGENTS

| 问题 | 没有 HelloAGENTS | 有 HelloAGENTS |
| 过早停止 | 给出建议就结束 | 继续进入构建、验证和收尾 |
| 推卸责任 | 拒绝困难任务，建议换其他工具 | 穷尽替代路径，坚持完成任务 |
| 质量不稳定 | 取决于每条提示词 | 14 项质量技能按任务类型自动激活 |
| 上下文分散 | 计划散落在聊天记录里 | 项目知识和计划文件留在磁盘上 |
| 完成定义模糊 | 自然语言说「做完了」 | 交付检查依据状态、证据和验证 |
| 配置写入有风险 | 命令行文件可能漂移 | 安装、更新、清理和 doctor 流程会检查受管文件 |

核心特性

1）14 项内置工作流技能

HelloAGENTS 内置 14 项技能。只在当前阶段需要时才加载，所以简单任务保持轻量，复杂工作则接受更严格的检查。

| 技能 | 关注点 |
| hello-ui | UI 规划、设计契约、实现映射、视觉验证 |
| hello-api | API 设计、校验、错误格式、兼容性 |
| hello-security | 认证、密钥、权限、注入风险 |
| hello-test | TDD、覆盖率、边界情况、测试结构 |
| qa-review | 统一质量审查、验证命令、阻塞性修复、交付证据、收尾 |
| helloagents | 命令路由、工作流阶段规则、项目知识、状态协调 |
| hello-errors | 错误处理、日志、重试与恢复行为 |
| hello-perf | 性能、缓存、查询与渲染风险 |
| hello-data | 数据库、迁移、事务、索引 |
| hello-arch | 架构、边界、代码规模、可维护性 |
| hello-debug | Bug 诊断，卡住时升级处理 |
| hello-subagent | 子代理委派与结果整合 |
| hello-write | 文档、报告、书面交付物 |
| hello-reflect | 可复用的经验教训与知识更新 |

所有 UI 工作首先遵循共享的 UI 质量基线。
在宿主全局模式、已初始化项目或显式 UI 工作流中，hello-ui 会在这条基线之上追加更深入的设计契约执行、设计系统映射和视觉验证。
需要视觉证据时，HelloAGENTS 会把它记录到当前会话的 artifacts/visual.json。

2）适配不同工作方式的命令

命令在 AI 命令行聊天中以 ~ 前缀运行。命令技能直接读取；工作流不需要时，不会加载无关技能。

| 命令 | 用途 |
| ~ask | 交互式澄清：通过问答锁定目标、方向、范围和约束；不写文件 |
| ~auto | 选择主路径并持续推进，直到交付或遇到真正的阻塞 |
| ~plan | 需求、方案设计、任务拆解、计划包 |
| ~build | 根据当前请求或已有计划进行实现 |
| ~prd | 通过逐维度引导，生成现代产品需求文档 |
| ~loop | 长时间运行的入口；在 Codex 中优先走 /goal -> ~auto -> ~qa |
| ~init | 初始化项目工作流，并同步项目知识 |
| ~test | 为目标模块或最近的改动编写测试 |
| ~qa | 运行统一质量循环：审查、验证命令、修复、收尾 |
| ~commit | 生成 conventional commit 信息并同步知识 |
| ~clean | 归档已完成的计划，清理临时运行时文件 |
| ~help | 显示命令和当前设置 |

兼容别名：

- ~do → ~build
- ~design → ~plan
- ~review → ~qa
- ~idea → ~ask（已废弃）

用 ~ask 澄清需求、比较方案、权衡价值、划定范围——纯对话，不创建文件。

3) 项目知识库

HelloAGENTS 可以在 .helloagents/ 下创建并维护项目知识库。

知识库帮后续轮次理解仓库，不必反复重新发现同样的事实。它可以存放：

| 文件或目录 | 用途 |
| context.md | 项目概览、技术栈、架构、模块索引 |
| guidelines.md | 从仓库推断出的非显而易见的编码约定 |
| verify.yaml | 验证命令，如 lint、test、build |
| CHANGELOG.md | 项目级变更历史 |
| DESIGN.md | 项目有 UI 工作时稳定的 UI 设计契约 |
| modules/.md | 模块专属笔记与经验教训 |
| plans/<feature>/ | 进行中的计划包 |
| archive/ | 已归档的计划包 |

~init 初始化项目工作流：写入项目级完整载体标记，准备项目状态，创建或更新知识库。

4) 结构化计划包

复杂工作可以存成计划包，而不是聊天里的一段话。

对于 ~plan，HelloAGENTS 使用：

- requirements.md
- plan.md
- tasks.md
- contract.json

对于 ~prd，HelloAGENTS 还会创建 PRD 文件，例如：

- prd/00-overview.md
- prd/01-user-stories.md
- prd/02-functional.md
- prd/03-ui-design.md
- prd/04-technical.md
- prd/05-nonfunctional.md
- prd/06-i18n-l10n.md
- prd/07-accessibility.md
- prd/08-content.md
- prd/09-testing.md
- prd/10-deployment.md
- prd/11-legal-privacy.md
- prd/12-timeline.md

工作流用 contract.json 决定 qaMode、qaFocus、可选的 advisor 检查，以及可选的可视化验证。

tasks.md 还包含一个 Codex /goal 入口。Codex 的长时间运行工作，用这个准备好的入口，不要给 /goal 一份原始产品文档。默认链路是 /goal -> ~auto -> ~qa：Codex 负责长时间运行的续接，~auto 执行 AFK 工作，~qa 在收尾前仍是最后的质量关卡。

5) 状态与恢复

长任务需要一份小的恢复快照，但一个共享状态文件对并发工作来说不够安全。
HelloAGENTS 现在从 state_path 解析当前状态文件：

- 有稳定或可复用的会话 id 时：.helloagents/sessions/<workspace>/<session>/STATE.md
- 可复用的会话 id 还没就绪时：.helloagents/sessions/<workspace>/default/STATE.md

<workspace> 是当前 Git 分支；处于 detached HEAD 时是 detached-<sha>；非 Git 项目则是 workspace。<session> 是当前项目本地的会话 token。.helloagents/sessions/active.json 只保留最新的活跃 workspace/session 映射和别名桥接，这样同一个命令行会话始终待在一个目录里，/resume 也能复用它。

对于项目本地的会话，HelloAGENTS 优先使用稳定的宿主标识，比如 sessionId、conversationId、threadId 或 HELLOAGENTS_NOTIFY_SESSION_ID。如果宿主只暴露窗口或终端 id，比如 WT_SESSION、TERM_SESSION_ID 或 WINDOWID，HelloAGENTS 只把它当作轻量别名桥接，优先复用已映射的会话，而不是散出一堆重复目录。如果会话在稳定宿主标识就绪之前就启动了，HelloAGENTS 可以先从 default 开始，等同一个命令行会话之后暴露稳定标识时，继续复用同一个活跃目录，而不是分裂出第二个会话目录。

STATE.md 记录当前工作流停在哪里。它不是所有对话的通用记忆文件。Codex /goal 不替代 state_path、turn-state 或本地证据文件；它只负责 Codex 这一侧的长时续跑。

6) 验证与交付证据

HelloAGENTS 不把「测试通过」和「任务完成」当成一回事。交付还可能要求计划覆盖、任务清单状态、评审证据、顾问证据和视觉证据。

运行时状态现在刻意保持精简：

- .helloagents/sessions/<workspace>/<session>/STATE.md
- .helloagents/sessions/<workspace>/<session>/runtime.json
- .helloagents/sessions/active.json
- .helloagents/sessions/<workspace>/<session>/artifacts/qa-review.json
- .helloagents/sessions/<workspace>/<session>/artifacts/advisor.json
- .helloagents/sessions/<workspace>/<session>/artifacts/visual.json
- .helloagents/sessions/<workspace>/<session>/artifacts/closeout.json
- 可选的 .helloagents/sessions/<workspace>/<session>/events.jsonl
- ~/.codex/.helloagents/notify-state.json，仅用于 Codex 原生收尾去重

STATE.md 只保留人类可读的恢复快照。runtime.json 只给机器用，保留最小运行时状态。artifacts/.json 只限于结构化回执。events.jsonl 仍是可选的追踪输出，默认关闭。
项目本地的 STATE.md 现在更懒地物化。

标准运行时证据和临时运行时状态现在 72 小时后过期。长时运行的 Codex goal 流程在工作流明确需要时，仍保留 720 小时的上限。
交付门禁、守卫和 QA 门禁消息改用面向行动的措辞，比如处理路径、收尾动作、视觉验证动作，这样被阻塞的流程能直接显示下一步该做什么，而不会把可执行步骤变成可选建议。最终收尾还会强制只保留一个 HelloAGENTS 包装器，因此一次回复不会输出重复的收尾标题。
该包装器现在只保留给直接面向最终用户的交付。中间报告、委派任务结果和子代理回复保持自然，子代理停止钩子会拒绝带包装的收尾回复。

7) 更安全的安装、更新、清理和诊断

命令行显式管理宿主文件：

- install 只写入选定的目标，除非用了 --all
- update 刷新选定的目标或全部目标
- cleanup 移除受管理的注入和链接
- uninstall 在移除包之前执行限定范围的清理
- doctor 报告载体、链接、钩子、配置项、插件根目录、缓存副本、版本，以及真实的 Claude/Gemini 全局安装产物中的漂移；对 Codex，还会在可用时显示原生 codex doctor 的输出
- Codex 受管理的 notify = ["helloagents-js", "codex-notify"] 保持可移植，doctor、cleanup 和 uninstall 也能识别 Codex App / Computer Use 使用的带包装 --previous-notify 链
- 每个宿主的模式跟踪只在宿主设置成功后写入，原生全局清理失败时会让宿主保持跟踪为 global，而不是悄悄在其上叠加 standby
- 直接执行 switch-branch 会在内部 npm install/sync 步骤之前清除残留的 HELLOAGENTS 生命周期环境变量，包的 preuninstall 在没有显式宿主参数时会回退到 --all，因此残留的 shell 环境变量不会缩小分支切换或卸载清理的范围
- Windows 的 .cmd / .bat 生命周期调用现在通过显式命令包装器运行，因此宿主安装、分支切换和 doctor 流程不会发出 Node DEP0190 shell 弃用警告
- Claude Code、Gemini CLI、Grok Build、Cursor 和 Codex CLI 的配置写入、更新、清理、卸载、模式切换和分支切换被当作一条经过测试的生命周期链覆盖，而不是各自尽力而为的独立路径

快速开始

1) 安装包

npm install -g --allow-scripts=helloagents helloagents

如果 PATH 中已经存在另一个名为 helloagents 的可执行文件，请使用稳定的受管理入口别名：

helloagents-js

默认情况下，postinstall 会安装包命令、初始化 ~/.helloagents/helloagents.json，并把运行时文件同步到 ~/.helloagents/helloagents。除非你设置 HELLOAGENTS=target[:mode]，比如 HELLOAGENTS=codex:global，否则不会部署任何宿主命令行。

对于 npm 11 及更高版本，在直接安装或升级包的命令中保留 --allow-scripts=helloagents，这样 npm 就能运行受管理的 postinstall，而不会出现批准警告。如果你还在用 npm 10 或更早版本，可以省略该参数。

2) 部署到某个命令行

选中的项目用 standby 模式，显式激活：

helloagents install codex --standby
helloagents install --all --standby

想让规则在所有地方都生效，就用 global 模式：

helloagents --global
helloagents install --all --global

重新安装、刷新或切换模式之后，重启目标 AI 命令行，或者开一个新会话；已经在跑的会话不会自动重新加载注入的规则。

3) 在 AI 命令行里验证

输入：

~help

你应该能看到可用的聊天命令和当前设置。

4) 创建项目知识

初始化项目工作流：

~init

命令行管理

Shell 命令

helloagents --standby
helloagents --global
helloagents install codex --standby
helloagents install --all --global
helloagents update codex
helloagents cleanup claude --global
helloagents uninstall gemini
helloagents switch-branch beta
helloagents switch-branch beta claude --global
helloagents doctor
helloagents doctor codex --json
helloagents codex goals status
helloagents codex goals enable

支持的目标：

- claude
- gemini
- grok
- cursor
- codex
- --all

如果你不写 --standby 或 --global，HelloAGENTS 会先复用该命令行已跟踪或检测到的模式，再回退到 standby。

npm 与一次性脚本入口

如果你不想在更新包时依赖 helloagents 可执行文件，就用这些入口。在 HELLOAGENTS=target[:mode] 里，target 可以是 all、claude、gemini、grok、cursor 或 codex；mode 可以是 standby 或 global。安装时省略 mode 按 standby 处理。更新、清理、卸载和切换分支时，省略的 mode 会原样透传，这样 HelloAGENTS 能先复用该命令行已跟踪或检测到的模式。如果你不提供 HELLOAGENTS，一次性安装脚本现在的行为就跟普通包安装一样：只安装或更新包，不自动部署任何宿主命令行。要指定自定义 tarball 或包规格，请设置 HELLOAGENTS_PACKAGE，而不是 HELLOAGENTS_BRANCH。想确保已安装的包被刷新，优先在包命令之后执行 npm explore -g helloagents -- npm run sync-hosts -- ...。一次性 shell 和 PowerShell 包装脚本会自动检测 npm 11+，只在支持该参数的地方追加 --allow-scripts=helloagents。
宿主配置使用稳定的 helloagents-js 入口点和运行时根目录 ~/.helloagents/helloagents，这样 Node 全局包路径变化时，不会破坏受管理的钩子或 Codex notify。Codex 钩子改用独立的 ~/.codex/hooks.json，不再往 config.toml 里塞大段钩子配置；Codex 全局插件根目录和插件缓存现在都链接回同一个稳定运行时根目录。Claude Code 全局安装使用专属的本地市场投影，位于 ~/.helloagents/host-projections/claude-marketplace；Gemini 全局扩展打包使用 ~/.helloagents/host-projections/gemini；Grok Build 全局安装使用物化后的市场投影 ~/.helloagents/host-projections/helloagents-grok-marketplace；Cursor 全局安装使用精选的本地插件投影 ~/.helloagents/host-projections/cursor-local-plugin/helloagents，外加一个真实复制的安装目录 ~/.cursor/plugins/local/helloagents。这样，各宿主专属的打包内容就与共享运行时根目录隔离开，不再依赖纯符号链接的插件加载方式。

npm 命令

macOS / Linux：

Install to Codex in standby mode
HELLOAGENTS=codex npm install -g --allow-scripts=helloagents helloagents

Install to Codex in global mode
HELLOAGENTS=codex:global npm install -g --allow-scripts=helloagents helloagents

Update the package, then refresh Claude in standby mode
npm install -g --allow-scripts=helloagents helloagents@latest
npm explore -g helloagents -- npm run sync-hosts -- claude --standby

Switch to the beta branch, then refresh all CLIs in standby mode
npm install -g --allow-scripts=helloagents https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
npm explore -g helloagents -- npm run sync-hosts -- --all --standby

Clean Gemini integration before package uninstall
npm explore -g helloagents -- npm run uninstall -- gemini --standby
npm uninstall -g helloagents

Windows PowerShell：

Install to Codex in standby mode
$env:HELLOAGENTS="codex"; npm install -g --allow-scripts=helloagents helloagents

Install to Codex in global mode
$env:HELLOAGENTS="codex:global"; npm install -g --allow-scripts=helloagents helloagents

Update the package, then refresh Claude in standby mode
npm install -g --allow-scripts=helloagents helloagents@latest
npm explore -g helloagents -- npm run sync-hosts -- claude --standby

Switch to the beta branch, then refresh all CLIs in standby mode
npm install -g --allow-scripts=helloagents https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
npm explore -g helloagents -- npm run sync-hosts -- --all --standby

Clean Gemini integration before package uninstall
npm explore -g helloagents -- npm run uninstall -- gemini --standby
npm uninstall -g helloagents

安装完包之后，你也可以直接调用它的 npm 脚本：

npm explore -g helloagents -- npm run deploy:global
npm explore -g helloagents -- npm run sync-hosts -- --all --standby
npm explore -g helloagents -- npm run cleanup-hosts -- codex --standby
npm explore -g helloagents -- npm run uninstall -- --all

全新安装仍然可以直接用 HELLOAGENTS=target[:mode]。如果是更新、切换分支，或者对已安装的包强制重新同步宿主，上面那条显式的 npm run sync-hosts 步骤才是确定性的做法。

一次性脚本

macOS / Linux： bash

Install

HELLOAGENTS=codex curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Update

HELLOAGENTS=claude:standby HELLOAGENTS_ACTION=update curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Switch branch

HELLOAGENTS=all:global HELLOAGENTS_ACTION=switch-branch HELLOAGENTS_BRANCH=beta curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Cleanup host integration without uninstalling the package

HELLOAGENTS=codex:standby HELLOAGENTS_ACTION=cleanup curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Uninstall

HELLOAGENTS=gemini HELLOAGENTS_ACTION=uninstall curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Windows PowerShell： powershell

Install

$env:HELLOAGENTS="codex"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Update

$env:HELLOAGENTS="claude:standby"; $env:HELLOAGENTS_ACTION="update"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Switch branch

$env:HELLOAGENTS="all:global"; $env:HELLOAGENTS_ACTION="switch-branch"; $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Cleanup host integration without uninstalling the package

$env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Uninstall

$env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

shell 和 PowerShell 包装脚本现在只解析一次 HELLOAGENTS，没指定 target 时保持普通的包安装 / 更新行为，在更新、切换分支、卸载之前先清掉生命周期环境变量，然后只走一条显式的同步或清理路径。

切换分支

switch-branch 先安装指定的 npm/GitHub ref，再通过 npm 脚本同步宿主命令行，所以更新过程中不依赖 helloagents 可执行文件： bash helloagents switch-branch beta helloagents switch-branch beta claude --global helloagents branch beta --all --standby

直接执行 helloagents switch-branch ... 命令时，也会在内部 npm install 和宿主同步步骤之前清掉残留的 HELLOAGENTS 生命周期环境变量。
只想换包、不立刻同步宿主命令行时，用普通 npm 命令： bash
npm install -g --allow-scripts=helloagents https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
npm install -g --allow-scripts=helloagents helloagents@latest
npm explore -g helloagents -- npm run uninstall -- --all
npm uninstall -g helloagents

待机模式文件

| 命令行 | 写入或更新的文件 | 清理行为 |
| Claude Code | ~/.claude/CLAUDE.md、~/.claude/settings.json、~/.claude/helloagents -> ~/.helloagents/helloagents | 移除受管理的标记块、HelloAGENTS 钩子/权限，以及符号链接 |
| Cursor | ~/.cursor/hooks.json、~/.cursor/helloagents -> ~/.helloagents/helloagents | 移除受管理的 Cursor 钩子和运行时符号链接 |
| Gemini CLI | ~/.gemini/GEMINI.md、~/.gemini/settings.json、~/.gemini/helloagents -> ~/.helloagents/helloagents | 移除受管理的标记块、HelloAGENTS 钩子，以及符号链接 |
| Grok Build | ~/.grok/AGENTS.md、~/.grok/hooks/helloagents.json、~/.grok/helloagents -> ~/.helloagents/helloagents | 移除受管理的标记块、受管理的 Grok 钩子文件，以及符号链接 |
| Codex CLI | ~/.codex/AGENTS.md、~/.codex/config.toml、~/.codex/hooks.json、~/.codex/helloagents -> ~/.helloagents/helloagents、受管理的备份 | 移除受管理的标记块、受管理的配置键、受管理的钩子、符号链接，以及最新的受管理备份 |

全局模式文件

| 命令行 | 安装方式 | 涉及的文件 |
| Claude Code | 原生插件安装 | ~/.helloagents/host-projections/claude-marketplace、由宿主管理的 Claude Code 插件元数据/缓存 |
| Cursor | 原生本地插件安装 | ~/.helloagents/host-projections/cursor-local-plugin/helloagents，落地到 ~/.cursor/plugins/local/helloagents |
| Gemini CLI | 原生扩展安装 | ~/.helloagents/host-projections/gemini、~/.gemini/extensions/helloagents |
| Grok Build | 原生市场 + 插件安装 | ~/.helloagents/host-projections/helloagents-grok-marketplace、~/.grok/config.toml、~/.grok/installed-plugins/registry.json、由宿主管理的 Grok 插件缓存 |
| Codex CLI | 原生本地插件链 | ~/.agents/plugins/marketplace.json、~/plugins/helloagents/ -> ~/.helloagents/helloagents、~/.codex/plugins/cache/local-plugins/helloagents/local/ -> ~/.helloagents/helloagents、~/.codex/config.toml、~/.codex/hooks.json、~/.codex/helloagents -> ~/.helloagents/helloagents |
全局模式下，HelloAGENTS 现在会自动尝试宿主原生的安装命令。Claude Code 使用本地 marketplace 投影，Gemini 使用本地扩展投影，Grok Build 使用物化后的本地 marketplace 投影，Cursor 会刷新 ~/.cursor/plugins/local/helloagents 下的真实本地插件副本，Codex 则始终链接回同一个稳定的运行时根目录。因此安装、更新、切分支、切模式、清理、卸载都会针对同一份一致的运行时副本刷新。如果宿主命令不可用，手动执行同样的命令： text /plugin marketplace add "~/.helloagents/host-projections/claude-marketplace" /plugin install helloagents@helloagents gemini extensions link "~/.helloagents/host-projections/gemini" grok plugin marketplace add "~/.helloagents/host-projections/helloagents-grok-marketplace" grok plugin install "~/.helloagents/host-projections/helloagents-grok-marketplace/plugins/helloagents" --trust

Cursor 这边，把 ~/.helloagents/host-projections/cursor-local-plugin/helloagents 的内容复制到 ~/.cursor/plugins/local/helloagents。Windows 上不要依赖指向 ~/.cursor 之外的符号链接或 junction。

Claude Code 这边，命令行还会尝试等价的 claude plugin marketplace add ... 和 claude plugin install ... 命令。marketplace 名为 helloagents，插件也叫 helloagents，所以安装目标是 helloagents@helloagents。全局安装后重启宿主命令行。

把 Claude 或 Gemini 切回 standby 时，HelloAGENTS 会先移除原生插件或扩展。如果清理失败，宿主会继续按 global 跟踪，而不是悄悄把 standby 叠加上去。

Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。

聊天中的命令

典型流程

| 目标 | 使用 |
| 澄清需求、比较方案、确定范围与价值 | ~ask "should this become a full platform or just a thin wedge?" |
| 让 HelloAGENTS 选路径并继续 | ~auto "add JWT login" |
| 实现前先审阅计划 | ~plan "refactor payment module" |
| 根据明确请求或当前计划实现 | ~build "finish task 2 in the plan" |
| 产出完整的产品需求文档 | ~prd "modern dashboard for operations team" |
| 通过 /goal -> ~auto -> ~qa 跑长 Codex 任务 | ~loop "finish the auth refactor" |
| 初始化或刷新项目工作流 | ~init |
| 校验当前工作 | ~qa |
| 生成提交信息并同步知识 | ~commit |

项目初始化与宿主全局部署

standby 模式下，未初始化的项目使用更轻的规则，并显式提供 ~command 入口。~init 写入项目级 标记后，项目就算初始化完成。

全局模式下，HelloAGENTS 默认在宿主层面应用完整规则。

项目知识库本地模式

默认情况下，项目知识存放在项目里： text .helloagents/

这个目录是本地知识、计划、状态和运行时目录。

仓库共享模式

当 project_store_mode = "repo-shared" 时：

- 本地 .helloagents/ 保留项目本地状态和运行时文件
- 稳定的知识文件和计划文件移到 ~/.helloagents/projects/<repo-key>/
- 同一个 git 仓库的多个工作树可以共享同一份稳定知识

运行时状态和证据仍然留在当前工作项目里：

- state_path
- .helloagents/sessions/active.json
- .helloagents/sessions/<workspace>/<session>/runtime.json
- .helloagents/sessions/<workspace>/<session>/artifacts/*.json

项目本地存储之外的临时会话

做只读工作、不产生本地输出时，如果当前目录及其父目录都没有项目本地的 .helloagents/ 目录，HelloAGENTS 会把短时运行时状态放在用户级目录下： text ~/.helloagents/runtime/<scope-key>/

这里只存短时的 STATE.md、runtime.json 和 artifacts/。可选的 events.jsonl 追踪文件只在开启追踪模式时才写入。它不是项目知识。过期的临时会话由 TTL 清理删除。

Once the task creates or modifies local files, or otherwise leaves local output in the current project, HelloAGENTS creates the project-local .helloagents/sessions/<workspace>/<session>/STATE.md automatically instead of keeping that task only in the user-level transient runtime.

Knowledge creation rules

| Command or setting | Behavior |
| ~init | initializes the project workflow and syncs the knowledge base |
| kb_create_mode = 0 | disables automatic knowledge updates |
| kb_create_mode = 1 | syncs knowledge automatically only when the KB already exists |
| kb_create_mode = 2 | for coding tasks, auto-creates or syncs the KB when it already exists or the project is initialized |

Workflow and Delivery

Workflow stages

HelloAGENTS uses this stage model for structured work:
text
Routing and tiering → Goal clarification → Planning → Implementation → Quality loop → Closeout and archive

| Stage | Purpose |
| Routing and tiering | decide whether the task should go through ~ask, ~plan, ~build, ~qa, ~prd, or automatic flow |
| Goal clarification | clarify goal, constraints, and success criteria |
| Planning | prepare plan files and choose needed skills |
| Implementation | implement and run local checks |
| Quality loop | review, run commands, and check contract and evidence |
| Closeout and archive | update state, knowledge, and closeout evidence |

HelloAGENTS also keeps an always-on core-rule layer in bootstrap.md / bootstrap-lite.md.
That layer anchors the agent as a capable executor in a trusted environment, blocks responsibility-shifting to users or other tools, enforces exhausting alternative paths before declaring blockage, corrects proposal bias, distinguishes real external constraints from internal inertia, and keeps user-visible wording in one language unless code identifiers, commands, paths, config keys, or necessary proper names must stay unchanged.

Delivery tiers

| Tier | Typical use |
| T0 | read-only analysis, idea exploration, comparison |
| T1 | low-risk focused fixes or explicit verification |
| T2 | multi-file features, new projects, structured plans |
| T3 | high-risk or irreversible work such as auth, payment, database, release, production operations |

UI workflow

UI work follows this priority:

1. current plan.md or PRD UI decisions
2. .helloagents/DESIGN.md
3. any loaded hello-ui implementation and validation rules; all UI work must still satisfy the shared UI quality baseline

For heavier UI work, contract.json can require:

- ui.styleAdvisor.required
- ui.visualValidation.required

Those requirements are closed with the current session artifacts/advisor.json and artifacts/visual.json.

Verification sources

Verification commands are detected in this order:

1. logical .helloagents/verify.yaml
2. package manager scripts such as package.json
3. automatic detection

When project_store_mode = "repo-shared", logical .helloagents/verify.yaml resolves from the shared project store.

Configuration

Config file:
text
~/.helloagents/helloagents.json

Default shape:
json
{
"output_language": "",
"output_format": true,
"notify_level": 0,
"ralph_loop_enabled": true,
"guard_enabled": true,
"kb_create_mode": 1,
"project_store_mode": "local",
"auto_commit_enabled": true,
"commit_attribution": "",
"install_mode": "standby",
"host_install_modes": {}
}

| Key | Default | Meaning |
| output_language | "" | follow the user language unless set |
| output_format | true | direct final-user closeout from the main agent uses the HelloAGENTS layout; intermediate, delegated, and sub-agent output stays natural |
| notify_level | 0 | 0 off, 1 desktop, 2 sound, 3 both |
| ralph_loop_enabled | true | run the QA stop gate for explicit ~qa / ~loop or required closeout gates |
| guard_enabled | true | block dangerous commands |
| kb_create_mode | 1 | 0 off, 1 sync existing KB automatically, 2 auto-create or sync the KB for coding tasks |
| project_store_mode | "local" | local or repo-shared |
| auto_commit_enabled | true | auto-create a local commit at closeout when verification passed and the working tree changed; false skips only the automatic commit |
| commit_attribution | "" | optional text appended to commit messages |
| install_mode | "standby" | current default install mode |
| host_install_modes | {} | managed per-CLI mode map, such as { "codex": "standby" }; recorded only after successful host setup and used before falling back to install_mode |

auto_commit_enabled is initialized to true only when the config file is first created. Later installs and updates only fill missing keys and do not overwrite your existing value.

How Each CLI Is Integrated

Claude Code

- standby writes ~/.claude/CLAUDE.md
- standby updates ~/.claude/settings.json with managed hooks and permissions
- standby creates ~/.claude/helloagents -> ~/.helloagents/helloagents
- global mode uses Claude Code's plugin system
- switching from global back to standby removes the native plugin first; if that cleanup fails, HelloAGENTS keeps Claude tracked as global

Gemini CLI

- standby writes ~/.gemini/GEMINI.md
- standby updates ~/.gemini/settings.json with managed hooks
- standby creates ~/.gemini/helloagents -> ~/.helloagents/helloagents
- global mode uses Gemini's extension system
- switching from global back to standby removes the native extension first; if that cleanup fails, HelloAGENTS keeps Gemini tracked as global

Grok Build

- standby writes ~/.grok/AGENTS.md
- standby writes a managed global hooks file at ~/.grok/hooks/helloagents.json
- standby creates ~/.grok/helloagents -> ~/.helloagents/helloagents
- global mode uses Grok Build's native marketplace plus plugin install path
- global packaging is materialized under ~/.helloagents/host-projections/helloagents-grok-marketplace
- switching from global back to standby removes the native plugin and marketplace source first; if that cleanup fails, HelloAGENTS keeps Grok tracked as global

Cursor

- standby updates ~/.cursor/hooks.json
- standby creates ~/.cursor/helloagents -> ~/.helloagents/helloagents
- global mode uses Cursor's native local-plugin path
- global packaging is materialized under ~/.helloagents/host-projections/cursor-local-plugin/helloagents
- the installed local plugin is copied into ~/.cursor/plugins/local/helloagents, so Cursor does not depend on an external symlink target
- switching from global back to standby removes the local plugin copy first; if that cleanup fails, HelloAGENTS skips standby injection

Codex CLI

Codex is rules-file driven by default.

- standby writes ~/.codex/AGENTS.md
- standby writes a portable managed model_instructions_file = "~/.codex/AGENTS.md"
- standby writes a managed and portable notify = ["helloagents-js", "codex-notify"] command for closeout notification, so reinstalling, updating, or moving to another machine does not require rewriting an absolute path
- standby writes silent Codex hooks to ~/.codex/hooks.json
- Codex SessionStart stays silent and reads the current ~/.helloagents/helloagents.json at runtime instead of baking a config snapshot into config.toml, so first-turn and post-compaction settings stay current
- install and update also sync HelloAGENTS-managed Codex hook trust state in ~/.codex/config.toml, so Codex 0.129.0+ does not re-prompt for the managed hooks
- that hook trust state is machine-local generated metadata derived from the current absolute ~/.codex/hooks.json path; unlike model_instructions_file = "~/.codex/AGENTS.md", it is not portable config and should be regenerated on each machine
- standby creates ~/.codex/helloagents -> ~/.helloagents/helloagents
- global mode installs the native local-plugin chain, but keeps ~/.helloagents/helloagents as the single managed runtime source by linking plugin roots, plugin cache, and ~/.codex/helloagents back to it
- doctor, cleanup, and uninstall also recognize wrapped notify chains such as --previous-notify ["helloagents-js", "codex-notify"], so Codex App / Computer Use wrappers do not cause false drift reports or break notify restoration
- for Codex app/plugin discovery, global is the native path; standby remains the lighter default for explicit project work
- cleanup removes only the HelloAGENTS-managed hook trust entries, while keeping user-owned hook state untouched
- Codex hooks only synchronize runtime state and enforce Stop gates; they do not inject HelloAGENTS rules or route text through hook output
- Codex closeout de-duplicates Stop hooks and native codex-notify, so one turn does not notify twice, and clientless delegated child-completion events stay silent when the managed Stop hook is active
- /goal remains Codex-native. Enable it explicitly with helloagents codex goals enable when long-running plan execution is needed
- Current OpenAI docs still mark /goal as experimental, and Codex app support is still preview. HelloAGENTS therefore treats /goal as an opt-in Codex-native accelerator, not as a required runtime dependency
- Goal-aware commands resume from tasks.md, contract.json, and state_path; they do not create goals automatically or mark them complete before HelloAGENTS verification and closeout

Verification

Run all tests:
bash
npm test

The current suite covers:

- install, update, cleanup, uninstall, branch switching, and mode switching
- stale lifecycle-env protection for direct switch-branch and package preuninstall
- Windows .cmd / .bat lifecycle dispatch without Node DEP0190 warnings
- one-shot shell and PowerShell lifecycle dispatch, plus wrapper env cleanup and mode-routing rules for install, update, cleanup, uninstall, and branch switching
- Claude, Gemini, Grok, Cursor, and Codex host integration behavior, including global-to-standby cleanup and failed native cleanup tracking
- Codex managed model_instructions_file, notify, hooks.json, hook trust state, local plugin, marketplace, and cache behavior
- Codex cleanup and canonical managed notify restoration rules, including wrapped --previous-notify chains
- Codex /goal feature toggles, long-running route context, and goal-aware command contracts
- helloagents doctor
- project storage and repo-shared behavior
- workspace-session scoped state_path, runtime signals, and evidence
- runtime injection, routing, guard, verification, visual evidence, delivery gates, closeout de-duplication, sub-agent wrapper and notification suppression, and successful-mode tracking after native install failures
- end-to-end host config write, update, cleanup, uninstall, mode-switch, and branch-switch flows across Claude Code, Gemini CLI, Grok Build, Cursor, and Codex CLI
- README and skill contract alignment

FAQ

What is the role of docs/?

docs/ is reference material for users and AI agents. It may lag behind implementation; runtime behavior is defined by source code, rule templates, skills, templates, and tests.

Is this a CLI tool or a prompt framework?

Both.

- cli.mjs handles install, update, cleanup, diagnostics, and host config
- rule templates define the loaded workflow rules
- skills/ defines task-specific behavior
- scripts/ provides runtime helpers for routing, guard, notify, verification, state, and evidence

Should I use ~init or --global?

Use ~init inside a repo when you want to initialize that project workflow and sync project knowledge.

Use helloagents --global when you want host-wide deployment across supported CLIs.

What is the difference between standby and global?

standby is lighter and explicit. It deploys rules to selected CLIs while leaving each repo uninitialized until you run ~init.

global applies full rules broadly at the host level. Claude, Gemini, and Grok use native plugin, extension, or marketplace installs. Cursor and Codex use native local-plugin paths; Cursor specifically materializes a real plugin copy under ~/.cursor/plugins/local/helloagents.
If you mainly want Codex app/plugin discoverability, use global. If you mainly want a lighter, explicit project workflow, keep standby.

Do Codex hooks show injected content?

No HelloAGENTS rule or route text is injected through hooks. HelloAGENTS Codex hooks only write runtime state and enforce Stop gates; successful hooks stay quiet, while blocked or failed hooks show the necessary reason.

Can I turn off notifications or guard checks?

Yes.

- set notify_level to 0 to disable notifications
- set guard_enabled to false to disable command guards

Does npm uninstall -g helloagents remove project knowledge?

No. Run npm explore -g helloagents -- npm run uninstall -- --all before package removal so HelloAGENTS can reuse the tracked or detected mode for each CLI and clean host integrations plus the stable runtime copy. Project .helloagents/ files and ~/.helloagents/helloagents.json are intentionally preserved unless you remove them yourself.

Troubleshooting

~help is not recognized

Check:
bash
npm list -g helloagents
helloagents doctor

Then restart the target CLI.

A CLI appears installed but behavior is stale

Run:
bash
helloagents doctor
helloagents update codex
helloagents --standby
helloagents --global

Use the command that matches your installed mode and target CLI.

Codex still uses old files after a local branch switch

Refresh Codex:
bash
helloagents update codex

For global mode, you can also run:
bash
helloagents --global

Notifications do not work

Check notify_level first.

- Windows: PowerShell must be able to show desktop notifications or play sound
- macOS: afplay should be available
- Linux: install aplay, paplay, or notify-send

Guard blocks a command you intended to run

Review the command. Guard blocks known destructive operations and warns about risky writes. If you still want to disable it:
json
{ "guard_enabled": false }

License

Code is licensed under Apache-2.0. Documentation is licensed under CC BY 4.0.

Contributing

- Bug reports: open an issue
- Feature requests: open an issue
- Pull requests are welcome

If this project helps you, a star is the best support.

Thanks to codexzh.com / ccodezh.com for supporting this project.