Codex Harness CLI

Thin CLI for initializing and driving a Codex Harness project from npm. The published package embeds its own package-source/ and only falls back to GitHub Release assets when the embedded package source is unavailable.

Install

Use with npx

适合一次性初始化或临时验证：

npx @pzy560117/codex-harness init

Global install

适合长期在本机重复使用：

npm install -g @pzy560117/codex-harness

安装后命令名是：

harness

执行 harness init 时如果发现 %USERPROFILE%\\.codex\\packages\\codex-harness\\ 的用户级 package cache 缺失或版本落后，会先自动刷新这层共享缓存，再继续项目初始化。

Quick Start

1. 初始化当前项目

在目标项目根目录执行：

harness init

如果当前目录还不是 Git 仓库，CLI 会调用安装器并按默认策略初始化项目所需的 Harness runtime。 如果用户级 package cache 版本落后，CLI 会先自动补齐 install-user.ps1 对应的共享缓存。

2. 运行 doctor

harness doctor

这会检查：

• runtime 文件是否齐备
• task.json 是否可读
• install manifest / lock / config 是否一致
• PowerShell / prompts / rules / trace schema 是否健康

3. 运行 verify

harness verify

这是包级 sanity check，至少会做 git diff --check，并校验 hooks、PowerShell 语法和 package freshness。

4. 跑 driver

harness run --run-until-done

这会转调项目里的：

• tools/harness/codex-loop.ps1

主执行链仍然是：

task.json
  -> codex-loop.ps1
  -> review / test / trace / commit

Commands

harness init [--version <version>] [--project-root <path>] [--vendor] [--force] [--init-git] [--plan]
harness doctor [--project-root <path>]
harness verify [--project-root <path>]
harness run [--project-root <path>] [--task-file <path>] [--run-until-done]

Common Usage

初始化到指定目录

harness init --project-root E:\repo\my-project

只看安装计划，不改文件

harness init --plan

钉住指定版本初始化

npx @pzy560117/codex-harness init --version 0.1.14

如果要强制使用某个已发布 CLI 版本，推荐直接写成：

npx --yes @pzy560117/[email protected] init

适合 release smoke、回滚或验证特定版本的安装语义。

对已初始化项目跑检查

harness doctor --project-root E:\repo\my-project
harness verify --project-root E:\repo\my-project

指定任务文件运行

harness run --task-file custom-task.json --run-until-done

What init installs

默认 init 会安装 project scope 的运行面，包括：

• AGENTS.md
• .codex/
• tools/harness/
• docs/ai/
• docs/harness/
• docs/spec/
• docs/testing/
• docs/knowledge/
• docs/requirement-prep-kit/
• .agents/skills
• .agents/workflows
• .codex-harness/state|locks|manifests

安装完成后，建议优先做三件事：

1. 裁剪 docs/ai/repo-map.md
2. 裁剪 docs/ai/architecture-brief.md
3. 运行 harness doctor 和 harness verify

/goal usage

如果目标项目准备在 Codex app 中使用 /goal 长时间推进，安装完成后优先阅读：

• docs/codex-harness-engineering/goal-harness-integration-guide.md
• docs/codex-harness-engineering/examples/goal-templates.md

/goal 只作为外层长期目标控制面，不替代 task.json + codex-loop.ps1 + stop hook 主链。

Windows notes

• CLI 会优先尝试 pwsh，回退到 powershell。
• 所有真正的安装/验证/运行动作最后都回到 PowerShell 脚本。
• 如果企业环境限制脚本执行，请优先检查 PowerShell Execution Policy 和企业代理。

Release Assets

GitHub Release assets are built from the repository package source with:

powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1