npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

awesome-codex-subagents-opencode

v0.3.0

Published

174 Codex subagent definitions adapted for OpenCode, with locale-aware descriptions in 5 languages

Readme

awesome-codex-subagents → OpenCode

English | 简体中文

174 个专家 agent,一条命令装进 OpenCode。

OpenCode 的 @ 菜单,显示 reviewer、debugger 等 agent 及其权限

OpenCode 自带的 subagent 只有 general 和 explore 两个。当你需要一次真正到位的 PR 级代码审查、一份能落地的威胁建模、一次跨文件的架构重构规划,往往只能靠主 agent 一边读上下文一边现编 —— 既占上下文,质量也不稳定。

这个仓库把它变成了开箱即用的东西:

npx awesome-codex-subagents-opencode --global

装完重启 OpenCode,敲 @reviewer 就能让一个只读的审查者独立跑完整个 diff,只把结论 带回你的对话。它不会污染主上下文,也不会顺手改你的文件。不需要 clone,也不需要先装依赖。

它解决什么问题

| 痛点 | 这个仓库的做法 | | --- | --- | | 长任务把主上下文塞满 | 每个 agent 在独立子会话里跑,只回传结论 | | 审查类工作容易越界改代码 | 99 个只读 agent 用 permission 硬性限制,连写文件都不允许 | | 换模型就得改一堆配置 | 一个模型都不写死,subagent 自动继承你当前的模型 | | @ 菜单全是英文看不懂 | 中文系统自动装中文描述,也可随时切换 | | 不知道自己该用哪个 | 按领域分组,从 debugger 到 hipaa-compliance 都有 |

覆盖范围

174 个 agent,覆盖 13 个领域:

| 领域 | 代表 agent | | --- | --- | | 核心开发 | backend-developer frontend-developer code-mapper | | 语言与框架 | python-pro typescript-pro golang-pro rust-engineer …31 个 | | 基础设施 | kubernetes-specialist terraform-engineer docker-expert | | 质量与安全 | reviewer security-auditor debugger test-automator | | 数据与 AI | data-engineer ml-engineer eval-engineer | | LLM 工程 | llm-architect prompt-engineer mcp-developer | | 设计与产品 | ui-designer product-manager ux-researcher | | 专项领域 | fintech-engineer payment-integration blockchain-developer | | 合规法务 | hipaa-compliance gdpr-ccpa-compliance license-engineer |

完整清单见 agents/。


快速开始

最快的方式不需要 clone:

npx awesome-codex-subagents-opencode --global

把 174 个 agent 装进 ~/.config/opencode/agents,重启 OpenCode 后即可用 @agent名 调用。

包名就是命令。 npx ocagents 这类简写不能用 —— npm 会去找同名包并失败。 请始终使用上面的完整包名。

只想装一部分?174 个会让 @ 菜单很长,也会稀释模型的自动选择:

npx awesome-codex-subagents-opencode --global --preset minimal

或者从仓库安装

想读源码或自己改的话。下面所有命令都假定你已经在仓库目录内:

git clone https://github.com/He-Xun/awesome-codex-subagents-opencode.git
cd awesome-codex-subagents-opencode

node install.mjs            # -> 在运行命令的项目里创建 ./.opencode/agents
node install.mjs --global   # -> ~/.config/opencode/agents(所有项目生效)

零依赖,只需 Node 18+。

脚本会自己解析路径,所以从任意目录执行 node /path/to/repo/install.mjs --global 也可以, 不需要先 cd。

参数

-g, --global          装到 ~/.config/opencode/agents
    --dir <path>      装到指定目录
    --lang <code>     描述语言(默认跟随系统)
    --preset <name>   只装预设子集(minimal / web / backend)
    --only <a,b>      只装指定 agent
    --skip <a,b>      排除指定 agent
    --list-presets    查看预设
    --dry             只预览,不写文件
-h, --help            查看帮助

--flag value 和 --flag=value 两种写法都支持。

用 npm 脚本(在仓库根目录)

npm run install:global      # 装到全局
npm run install:local       # 装到当前项目
npm run verify              # 校验所有产物
npm run switch -- --to=en   # 切换描述语言
npm run presets             # 查看可用预设

预设

| 预设 | 数量 | 内容 | | --- | --- | --- | | minimal | 10 | 审查、定位、改代码、写测试 —— 通用默认 | | web | 15 | 前端 / UI / 可访问性 | | backend | 17 | 服务端 / 数据库 / 基础设施 | | data-ai | 11 | ETL、分析、建模、MLOps、实验设计 | | llm-ai | 11 | prompt、评估、可观测性、agent 编排 | | security | 10 | 安全审计、合规、许可证、质量 | | devops | 10 | CI/CD、Kubernetes、IaC、事故响应 | | mobile | 7 | iOS、Android、Flutter、React Native | | docs | 6 | 技术写作、API 文档、README、文案质量 | | product | 8 | 需求、backlog、规划、市场分析 |

预设就是纯文本名单(presets/*.txt),可以直接改或加新的。预设里如果引用了不存在的 agent,npm run verify 会直接失败。

三个设计取舍

这三点决定了它和「直接把文件复制过来」的差别:

1. 不写死模型。 源仓库每个 agent 都绑定了 gpt-6.1-sol,这个模型在你的 provider 上大概率不存在,硬套过去等于 174 个 agent 全部不可用。本仓库完全不输出 model 字段, 让 subagent 继承调用方的模型 —— 换 provider、换模型都不用重新生成。

2. MCP 依赖去厂商化。 源仓库有 agent 绑定 OpenAI 自家的文档服务。这里替换成通用的 websearch + webfetch,任何厂商的文档都能查。

3. 语言只翻描述,不翻正文。 详见下方为什么 —— 中文 反而更费 token,全量汉化是负优化。


项目来源

本仓库是 VoltAgent/awesome-codex-subagents (6.4k star)的 OpenCode 移植版。上游提供的是 Codex 格式的 .toml 定义,本项目将其 转换为 OpenCode 的 Markdown agent 格式,并解决了上述三个移植问题。

只做格式适配,不改写 prompt 语义:正文原文照搬,便于上游更新时重新生成。

上游更新后重新生成:

cd awesome-codex-subagents-opencode      # 切到仓库根目录
git clone --depth 1 https://github.com/VoltAgent/awesome-codex-subagents.git ../src
node tools/codex-subagents-to-opencode.mjs ../src/categories agents

描述语言:随系统自动选择,可随时切换

prompt 正文始终是英文,只有 description(也就是 @ 菜单里显示的那一行)会跟着语言变化。

安装时自动检测

tools/install.mjs 按以下顺序决定语言,没有匹配译表时回退到英语:

  1. --lang=xx 或环境变量 OPENCODE_SUBAGENTS_LANG
  2. LC_ALL / LC_MESSAGES / LANG / LANGUAGE
  3. Intl 报告的系统 locale
  4. 回退 → 英语

内置语言:English (en) · 简体中文 (zh) · 日本語 (ja) · Português (pt) · Español (es) · Русский (ru) · 한국어 (ko)。

--lang 接收的是语言代码,也就是 ISO 639-1 的两位标签(zh、ja、pt、es、ru、ko、en)。 它同时也是 tools/i18n/ 下译表的文件名,所以两者不会对不上。 完整的系统 locale(zh-CN、es_ES、pt_BR)只是检测时的输入,不是传给 --lang 的值。

当 LANG 或 LC_ALL 已设置但没有对应译表时,结果是英语,而不是再从 Intl 推断另一个 locale。显式设置了环境变量,就按用户意图处理。

node install.mjs                          # 跟随系统 locale
node install.mjs --lang=en                # 强制英文
node install.mjs --lang=zh                # 强制中文
node install.mjs --only=reviewer,debugger # 只装部分

系统 locale 的映射规则:先去掉地区部分,再与已有译表匹配。

| 系统 locale | 解析为 | 原因 | | --- | --- | --- | | zh-CN、zh-TW | zh | 基础 zh 有译表 | | ja-JP | ja | 基础 ja 有译表 | | pt-BR、pt-PT | pt | 基础 pt 有译表 | | es_ES、es-MX | es | 基础 es 有译表 | | ru_RU | ru | 基础 ru 有译表 | | ko_KR | ko | 基础 ko 有译表 | | en_US | en | 基础 en 有译表 | | de_DE | en | 没有 de 译表 → 回退英语 |

随时切换

--dir 默认是 ./.opencode/agents:

cd awesome-codex-subagents-opencode      # 切到仓库根目录
node tools/switch-lang.mjs --list                                   # 查看可用语言
node tools/switch-lang.mjs --to=zh                                  # 切中文
node tools/switch-lang.mjs --to=en                                  # 切回英文
node tools/switch-lang.mjs --to=zh --dir=~/.config/opencode/agents  # 指定目录
node tools/switch-lang.mjs --to=zh --dry                            # 预演

切换器只改写 frontmatter 里的 description 那一行,正文和权限原样保留,并保持原有的 引号风格,因此中英来回切换不会产生多余 diff(已验证 174 个文件往返 0 差异)。

添加新语言

在 tools/i18n/ 下新建 <lang>.json,<lang> 是 ISO 639-1 语言代码,也就是你传给 --lang 的值(法语用 fr.json,德语用 de.json)。键为 agent 名:

{
  "reviewer": "需要 PR 式评审,聚焦正确性、安全性、行为回归与测试缺失时使用。",
  "debugger": "需要做深度缺陷定位时使用。"
}

无需改代码,install.mjs / switch-lang.mjs 会自动发现,随后即可用 --lang=fr 选择。 缺条目时该 agent 保留英文。

只用基础语言码,不要带地区:文件名必须是 fr.json 而不是 fr-FR.json,因为检测时会先 去掉地区部分再匹配。

内置译表遵循的敬语规范(贡献新语言时请沿用):

| 语言 | 体裁 | 句式 | | --- | --- | --- | | ja | 仅用 です・ます 礼貌体,不用 だ・である 简体 | …ときに使用します。 | | pt | 中性专业体,用 você,不用 tu 或口语 | Use quando … | | es | 仅用正式体 usted,不用 tú/vosotros | Úselo cuando … | | ru | 仅用 вы 敬语,不用 ты | Используйте, когда … | | ko | 仅用 -십시오 / -합니다 正式体,不用 반말 | …할 때 사용하십시오. |

validate.mjs 会自动强制这些体裁规范:混入口语的译文会直接让 CI 失败,而不是被发出去。


为什么只翻译 description

先看实测数据。同一份内容的中英对照:

| 分词器 | 英文 | 中文 | 差值 | | --- | --- | --- | --- | | GPT-4o (o200k) | 1196 | 1479 | +23.7% | | DeepSeek-V2 | 1324 | 1427 | +7.8% | | GLM-4 | 1202 | 1307 | +8.7% | | Qwen 2.5 | 1203 | 1351 | +12.3% |

来源:Chinese vs. English Tokens。

国产模型分词器对中文友好得多(从 +24% 降到 +8%),但方向从未逆转:中文更费 token。 英文可以整词压成单个 token,汉字基本一字一 token 或更多。

换算到本仓库:中文 description 字符数少 66%,但 token 数增加约 50%。全量汉化正文会让 327k 字符的 prompt 再涨约 8%。

所以:语言的价值是可读性和触发准确性,不是省 token。 想省 token 应该精简 agent 数量, 而不是换语言。


设计细节

1. 不写死模型

源文件里的 model = "gpt-6.1-sol" 是 Codex 专用模型,换到 OpenCode 上大概率不存在。 转换器完全不输出 model 字段,让 subagent 继承调用方 agent 的模型 —— 这是 OpenCode 的文档行为,好处是与 provider 无关,换模型不用重跑转换。

需要给特定 agent 钉死模型时:

cd awesome-codex-subagents-opencode      # 切到仓库根目录
node tools/codex-subagents-to-opencode.mjs <src> agents \
  --model-map=gpt-6.1-sol=anthropic/claude-sonnet-5,gpt-6-luna=anthropic/claude-haiku-5

2. MCP 依赖去厂商化

Codex 允许在 agent 文件内联 [mcp_servers.NAME],OpenCode 不允许(必须写在 opencode.json)。仓库里的两个依赖处理如下:

| 源 MCP | 处理 | 原因 | | --- | --- | --- | | openaiDeveloperDocs(docs-researcher) | 替换为 websearch + webfetch | 无需 API key,但只索引 OpenAI 自家文档,与通用适配相悖 | | chrome_devtools(browser-debugger) | 保留依赖 | 本身开源,且无通用替代品 |

替换规则集中在 MCP_REPLACEMENTS 常量,需要时可扩展。

3. 权限映射

Codex 的 sandbox_mode 是沙箱级强制,OpenCode 的 permission 是 allow/ask/deny 三级:

| Codex | OpenCode | | --- | --- | | read-only | edit: deny, bash: deny | | workspace-write | edit: allow, bash: allow |

174 个 agent 中 99 个只读、75 个可写。

例外:有 3 个只读 agent 的核心工作离不开执行命令 —— debugger 要看 stack trace 和 失败测试、performance-engineer 要跑测量、security-auditor 要复现问题。它们设成 bash: ask(每条命令仍需你批准),既保持只读语义,又不至于完全不可用。 名单在 READ_ONLY_NEEDS_SHELL 常量里。


字段映射

| Codex (.toml) | OpenCode (.md) | | --- | --- | | name | 文件名 xxx.md(同时是 agent id) | | description | frontmatter description | | model | 不输出,继承父 agent(可用 --model-map 覆盖) | | model_reasoning_effort | frontmatter reasoningEffort | | developer_instructions | 正文(prompt,原文保留) | | sandbox_mode | frontmatter permission | | [mcp_servers.*] | 不进入文件,转换报告里列出 | | 分类目录 | frontmatter color(仅视觉区分) |

正文中的 Codex 会被替换为 the parent agent,避免提示词指向另一个产品。


CLI 参数

| 参数 | 说明 | | --- | --- | | --only=reviewer,debugger | 只转换指定 agent | | --category=04,05 | 按分类目录前缀过滤 | | --skip=a,b | 追加要跳过的 agent | | --all | 连 Codex 专用 agent 也一并转换 | | --dry | 只打印报告,不写文件 | | --model-map=k=v,... | 覆盖模型映射 | | --lang=zh | 把 description 本地化成中文,正文保持英文(默认自动检测,见上) | | --keep-reasoning | 保留 reasoningEffort 字段 |

默认跳过 agent-installer、workflow-orchestrator:它们的 prompt 讲的是 「往 ~/.codex/agents/ 里装文件」,移植到 OpenCode 后语义为空。


对非 GPT 与开源模型的说明

  • reasoningEffort 是 GPT 系专属参数。 只有 OpenAI 风格的接口认识它;Claude、Llama、 Mistral、Gemma、GLM、DeepSeek、Qwen 以及多数开源权重模型都会忽略。 默认不再输出,如果你的 provider 支持,再用 --keep-reasoning 恢复。
  • 若给特定 agent 钉模型,用 --model-map。值的形式是 provider/model-id,provider 前缀取自你自己的 opencode.json:--model-map=gpt-6.1-sol=<provider>/<model-id>。

已知限制

  1. 自动触发很弱(平台机制)。OpenCode 把 subagent 列表以 id: description 拼进 task 工具的 description,只靠文本让模型自行判断。内置 explore 的 description 带具体例句, 更容易被选中。174 个候选会稀释信号 —— 这是 OpenCode 的行为,不是转换问题。 建议要么用 --only 只装常用子集,要么始终 @agent名 手动调用。

  2. 常驻上下文成本。全量安装会让 task 工具描述增加约 7.5k token。

  3. prompt 同质化。源仓库 174 份 prompt 共用一个模板 (Working mode / Focus on / Quality checks / Return),长度 129/174 落在 1–2k 字符区间, 差异主要在领域词汇。不要期待它们之间有精细分工。

  4. browser-debugger 需要 chrome-devtools MCP(默认 localhost:3000/mcp)。 未配置时该 agent 会被加载但缺少工具。


仓库结构

.
├── bin/{cli,lang}.mjs                    # npm 包入口(ocagents / ocagents-lang)
├── tools/
│   ├── install.mjs                       # 安装(系统语言 + 预设)
│   ├── switch-lang.mjs                   # 随时切换 description 语言
│   ├── detect-lang.mjs                   # 语言检测(含回退到英语)
│   ├── validate.mjs                      # 校验产物、译表、预设(CI 用)
│   ├── i18n/{en,zh}.json                 # description 译表,加语言只需加文件
│   ├── codex-subagents-to-opencode.mjs   # 从上游 TOML 重新生成 agents/
│   ├── analyze-subagents.mjs             # 产物分析
│   ├── compare-lang.mjs                  # 中英文 token 成本对比
│   └── verify-load.mjs                   # 验证 OpenCode 能否正确加载
├── presets/{minimal,web,backend}.txt     # 装哪些 agent 的预设名单
├── agents/                                # 174 个 OpenCode agent(英文基准)
├── .github/workflows/validate.yml         # CI
├── package.json
├── README.md                              # English
├── README.zh-CN.md                        # 本文件
└── LICENSE

agents/ 是英文基准版本,可以直接复制到任意 OpenCode 项目使用。 想换描述语言用 switch-lang.mjs,不要手动改。

校验

npm run verify

检查 frontmatter 合法性、mode: subagent、无硬编码 model、权限键有效、prompt 完整且无 Codex 残留、译表与 agent 一一对应、预设引用的 agent 都存在。

CI 在 Node 18 / 20 / 22 上运行,并额外验证「从上游重新生成的结果与提交版本一致」, 防止产物悄悄漂移。


许可证

本仓库的转换脚本与 README 以 MIT 发布。 agents/ 下的内容派生自 VoltAgent/awesome-codex-subagents, 同样为 MIT,版权归原作者及贡献者所有。