一个面向 Codex CLI 的轻量级多 agent harness,用来补齐 Codex 生态里偏少的编排能力。

这个项目的目标很直接:

• oh-my-codex 很强,但对很多场景来说偏重
• Codex 生态里现成的多 agent 编排组件不多
• 因此这里提供一套更轻、更本地化、更容易直接落到 ~/.codex 的 harness

它不是另一个完整平台,而是一套可安装的工作环境约定:配置、agent 模板、编排提示词、skills 模板和辅助包装器。

如果你现在使用 Codex CLI,通常会遇到几个问题:

• 默认单 agent 模式在复杂任务上容易上下文过载
• 缺少一套开箱即用的多 agent 分工模板
• 缺少把调研、方案、编码、评审、验证串起来的轻量工作流
• 想接入额外能力时,经常要手工维护配置、MCP 和辅助脚本

codex-harness 的做法是直接把这些基础设施安装到 ~/.codex,让你可以在 Codex CLI 里用统一方式调用。 它并没有直接修改默认的codex profile,默认方式使用时,除非显式说明,否则默认不会自动触发多agent编排。

sandbox_mode = "danger-full-access"
approval_policy = "never"

开启了以上配置,不要在生产环境中使用。

基于当前仓库内容,项目已经具备这些能力。

安装后会写入一个 multi profile,使用方式是:

codex -p multi

这个 profile 会启用 templates/agents-prompts/MULTI_BASE.md 里的共享基础约束。 当任务需要总调度时,需要显式触发 multi-orchestrator-playbook skill,主代理才会读取 templates/agents-prompts/ORCHESTRATOR.md 这份编排手册来组织多 agent 执行。

它的当前特征包括:

• 面向多阶段任务的编排式执行
• 强调规范驱动和阶段化推进
• 优先把任务分给专门角色,而不是让一个 agent 混做所有事

仓库在 templates/agents 中提供了一组现成 agent 模板,安装后会复制到 ~/.codex/agents。

当前包含:

• architect
• code-mapper
• code-simplifier
• coder
• doc_editor
• evaluator
• explorer
• quick
• reviewer
• scrum_master
• security-auditor
• verifier

这些角色覆盖了从调研、架构、任务拆分,到编码、审查、验证、文档整理的一整条链路。 即使没有通过codex -p multi进入,也可以通过自然语言使用上述预置角色。

当前多 agent 提示词并不是"无脑并发",而是偏流程化编排:

• 调研阶段使用 explorer / code-mapper
• 方案阶段使用 architect / evaluator
• 拆解阶段使用 scrum_master
• 实施阶段使用 coder
• 验证阶段使用 security-auditor / verifier / reviewer
• 收尾阶段使用 doc_editor

这让它更适合中等复杂度以上的开发任务,而不是只做简单 shell 包装。

仓库在 templates/skills 中提供了技能模板:

• multi-model-research:支持 Gemini / Claude 双后端的技术调研与方案评审,可单模型或双模型对比模式运行
• tech-research:标准化技术调研工作流
• multi-orchestrator-playbook:手动触发主代理加载编排手册,仅在需要总调度时使用

它们解决的是"需要第二视角调研"、"需要标准化技术调研工作流"以及"需要显式进入编排手册模式"的场景。

仓库自带一个二进制工具 ccg/codeagent-wrapper,用于统一调用不同 AI CLI 后端。

根据当前 --help 输出,它支持:

• codex
• claude
• gemini
• opencode

也支持:

• --prompt-file
• --skills
• --parallel
• --output
• --worktree

这意味着当前项目不仅能跑 Codex 本身,也为跨 CLI 协作留了接口。

安装脚本支持按需把 MCP 配置合并进 ~/.codex/config.toml:

• 默认启用 context7
• 默认启用 fetch
• 可选启用 exa
• 可选启用 github

其中 exa 和 github 会在安装时读取:

• EXA_API_KEY
• GITHUB_PERSONAL_ACCESS_TOKEN

直接回车跳过即可,不会强制要求。

install.sh 会生成或更新 ~/.codex/config.toml,但不是全量覆盖用户配置,而是保留非托管部分。

当前会被托管的核心内容包括:

• 模型与 provider
• profiles.multi
• context7 / fetch
• agents
• features
• 部分运行时策略

这使它更适合作为"现有 Codex 环境上的增强层"。

前提:

• 已安装 npm
• 有可用的 Codex CLI
• 愿意将本仓库内容安装到当前用户的 ~/.codex

执行:

curl -fsSL https://raw.githubusercontent.com/KT-lcz/codex-harness/master/install-remote.sh | bash

curl | bash 安装时,脚本会直接从当前终端读取 EXA_API_KEY 和 GITHUB_PERSONAL_ACCESS_TOKEN,不受管道 stdin 影响。 如果你不想交互输入,也可以直接用环境变量:

EXA_API_KEY=your_exa_key \
GITHUB_PERSONAL_ACCESS_TOKEN=your_github_pat \
curl -fsSL https://raw.githubusercontent.com/KT-lcz/codex-harness/master/install-remote.sh | bash

如果你是在本地开发或想修改模板后再安装,也可以继续使用仓库内脚本:

git clone https://github.com/KT-lcz/codex-harness.git
cd codex-harness
bash install.sh

安装脚本会做这些事:

• 安装 @fission-ai/openspec
• 复制 templates/ 下的 agents、rules、skills、prompts
• 复制 ccg/codeagent-wrapper
• 合并并生成 ~/.codex/config.toml

如果你只想用默认模式,直接运行:

codex

这时会使用安装后的默认配置,但不一定进入多 agent 编排入口。

当前多 agent 编排的标准使用方式是:

cd ${project path}
openspec init --tools codex // 只需执行一次
codex -p multi

进入后,适合直接给中高复杂度任务,例如:

$openspec-explore 需要给当前项目添加gitlab oauth认证

如果需要主代理进入编排手册模式,请显式触发:

$multi-orchestrator-playbook

当前仓库只做到"手动触发",没有做到把该 skill 强约束为仅 multi profile 可见。

当前仓库自带的 multi-model-research 模板依赖 codeagent-wrapper,支持 Gemini / Claude 单后端或双后端对比模式。例如:

# 单模型模式(claude)
./ccg/codeagent-wrapper \
 --backend claude \
 --prompt-file ./templates/skills/multi-model-research/prompts/claude-explorer.md \
 "评估当前方案是否适合做多 agent 编排"
# 单模型模式(gemini)
./ccg/codeagent-wrapper \
 --backend gemini \
 --prompt-file ./templates/skills/multi-model-research/prompts/gemini-explorer.md \
 "评估当前方案是否适合做多 agent 编排"

更完整的参数请以实际帮助输出为准:

./ccg/codeagent-wrapper --help
./ccg/codeagent-wrapper version

可以先做最小检查:

bash -n install.sh
bash -n install-remote.sh
./ccg/codeagent-wrapper --help

安装完成后再确认:

ls -la ~/.codex
sed -n '1,260p' ~/.codex/config.toml

重点看这些内容是否存在:

• ~/.codex/agents/
• ~/.codex/skills/
• ~/.codex/skills/multi-orchestrator-playbook/SKILL.md
• ~/.codex/agents-prompts/MULTI_BASE.md
• ~/.codex/agents-prompts/ORCHESTRATOR.md
• ~/.codex/ccg/codeagent-wrapper
• ~/.codex/config.toml 中的 [profiles.multi]

OpenSpec 是一个规范驱动开发(SDD)框架,为 AI 编程助手提供结构化的变更管理能力。它通过在代码仓库中创建 openspec/ 目录来管理变更提案、规格、设计和任务。

本项目依赖 OpenSpec 的 SDD 流程,安装脚本会自动安装 @fission-ai/openspec 包。

• codex-harness 提供多 agent 编排能力和本地工作流增强
• OpenSpec 提供规范驱动的变更管理能力
• 两者结合:OpenSpec 负责结构化变更记录,codex-harness 负责多 agent 协作执行

OpenSpec 在执行 bash install.sh 时会自动安装。

# 在项目中初始化 OpenSpec
cd your-project
openspec init
# 刷新 OpenSpec 生成的 skills
openspec update

OpenSpec 在 Codex 环境下只能通过 skill 触发。openspec init --tools codex 或 openspec update 之后,OpenSpec 会把对应 skill 生成到 ~/.codex/skills/openspec-*/SKILL.md,Codex 会按 skill 名识别这些工作流。

当前常用 skill 包括:

OpenSpec 生成的 skill 文件位置:~/.codex/skills/openspec-*/SKILL.md

仓库预置的编排手册 skill 文件位置:~/.codex/skills/multi-orchestrator-playbook/SKILL.md

Core profile(默认)

最简工作流,适合快速启动变更:

在 Codex 对话中使用 OpenSpec skills:
- `openspec-propose`:为用户模块添加双因素认证
- `openspec-apply-change`
- `openspec-archive-change`

RTK(Rust Token Killer)是一个 Token 优化的 CLI 代理,用于减少 shell 命令输出的 token 消耗。

本项目要求所有 shell 命令前缀使用 rtk,原因:

• 自动过滤冗余输出,降低上下文膨胀
• 提供执行统计,帮助识别高消耗命令
• 统一命令执行入口,便于审计和回放

.
├── install-remote.sh # 远程 bootstrap,支持 curl 安装
├── install.sh # 安装脚本
├── ccg/
│ └── codeagent-wrapper # 多后端 AI CLI 包装器
└── templates/
 ├── AGENTS.md
 ├── RTK.md
 ├── agents/ # Agent 角色模板
 ├── agents-prompts/ # 共享提示词与编排手册
 ├── config.base.toml # 基础配置模板
 ├── rules/ # 行为规则
 ├── skills/ # 技能模板
 │ ├── multi-model-research/
 │ ├── multi-orchestrator-playbook/
 │ └── tech-research/
 └── snippets/ # 代码片段

• 这不是一个完整插件平台,也不是一个独立 CLI 产品
• 仓库核心是安装脚本加模板,不是业务应用
• codeagent-wrapper 目前以二进制形式提交,代码在https://github.com/stellarlinkco/myclaude/tree/master/codeagent-wrapper中,可自行编译
• 默认 provider base_url 是一个默认地址,使用时需要手动修改并添加OPENAI_API_KEY,
• install.sh 是交互式安装,不适合直接作为无参 CI 安装脚本
• install-remote.sh 只是下载仓库归档后调用 install.sh,因此同样会保留交互式输入行为
• install.sh 现在支持从 /dev/tty 读取密钥输入,也支持通过环境变量 EXA_API_KEY / GITHUB_PERSONAL_ACCESS_TOKEN 跳过交互
• 多 agent 编排能力当前主要通过 codex -p multi 这个 profile 入口暴露
• 所有 shell 命令请使用 rtk 前缀以优化 token 消耗
• OpenSpec 变更记录存储在项目根目录的 openspec/ 目录下

这个项目并不是要复刻 oh-my-codex。

它更像一个面向 Codex CLI 的轻量替代方案,重点在于:

• 保留多 agent 编排的核心能力
• 减少额外平台层和重量级封装
• 直接复用 ~/.codex 配置与本地模板
• 让你可以更低成本地把多 agent 工作流接到现有 Codex 环境中

如果你要的是更完整、更平台化、更大而全的系统,可以看 oh-my-codex 一类项目。

如果你要的是一个足够轻、足够直接、能马上开始用的 Codex 多 agent harness,这个仓库就是为这个目的写的。

• 增加 autopilot skill
• 增加分析代码库的skill
• 完善tech-research skill
• 增加技术方案审核的skill
• 增加review代码提交的skill
• 增加记忆和召回的prompt
• 增加deep-interview的skill