Retinue

Retinue 让 Codex 把本地 coding agents 当作可控子代理来运行。

Codex 提交一个 coding job，Retinue 立刻返回 job handle；之后可以查状态、等待完成、读取结果、继续外部会话、终止任务或清理本地产物。Claude Code、OpenCode 仍然负责自己的 provider、model、quota、proxy、login 和运行策略；Retinue 负责把这些本地 agent runtime 变成 Codex 可调用、可追踪、可接回的子代理能力。

Codex / MCP client
  -> Retinue MCP 或 CLI
    -> backend adapter
      -> Claude Code / OpenCode
    -> local job state + bounded result artifacts

核心能力

能力	说明
启动子代理	让 Codex 启动 Claude Code 或 OpenCode coding job，并快速拿到 `jobId`
查询状态	用 `status` 查看 running、completed、failed、killed、orphaned、abandoned 等状态
等待和轮询	用 `wait` 在短时间窗口内等待终态，不阻塞主 agent 的整段任务
读取结果	用 `result` 获取 bounded stdout/stderr、exit metadata、外部 session id 和本地 artifact path
继续会话	后端支持时，用 `continue` 接回已有 Claude/OpenCode session 继续工作
终止和清理	用 `kill` 终止指定 job，或用 `cleanup` 删除终态 job 目录，同时保留运行中或状态不确定的任务

边界

Retinue 是本地子代理执行面，不是模型网关，也不是 provider router。

不选择或切换模型供应商。
不接管 Claude Code / OpenCode 的登录、配额、代理、模型默认值或运行策略。
不把 prompt 放进子代理进程 argv；CLI 调试场景请避免在敏感 prompt 上使用 --prompt。
不在默认 status 响应里返回完整 prompt。
不把自己扩展成通用进程管理器或云端队列。

快速开始

0.2.0 默认使用 OpenCode 后端，并让 OpenCode 使用 explore agent。用户不需要 clone、安装依赖或编译 Retinue。Retinue 面向 Windows、WSL/Linux 和 macOS；文档示例以 WSL/Linux 为主。

前置条件：

Node.js 20+
Codex CLI 0.128+
OpenCode 1.14+，优先使用官方安装脚本：

curl -fsSL https://opencode.ai/install | bash

官方脚本默认把 OpenCode 安装到 $HOME/.opencode/bin/opencode。Retinue 也兼容常见 npm/pnpm/bun 全局安装路径，但 0.2.0 的默认文档和冒烟验收以官方脚本安装为准。

把 Retinue 插件市场加入 Codex：

codex plugin marketplace add Disaster-Terminator/Retinue

打开 Codex，运行 /plugins，按键盘右方向键切到 [Retinue Local] 插件市场，按 Enter 打开 Retinue 详情页，然后选择 Install plugin。安装后重新打开 Codex，然后让 Codex 使用 Retinue：

Use Retinue to spawn an OpenCode explore subagent. Ask it to reply exactly: RETINUE_OK. Wait for the result and close the child agent.

预期结果：

Codex 能看到 Retinue skill。
Codex 能调用 retinue_spawn_agent。
retinue_wait_agent 返回包含 RETINUE_OK 的结果。
retinue_close_agent 返回 terminal 状态。
retinue_list_agents 可列出当前 MCP 会话内仍在运行的 Retinue 子代理。

说明：Codex CLI 0.128 的 codex plugin marketplace add/upgrade/remove 只管理插件市场；插件安装在 Codex TUI 的 /plugins 里完成。codex plugin marketplace upgrade retinue-local 只用于更新已有市场，不是安装命令。

平台说明

Windows：需要本机 Node.js、Codex CLI 和 OpenCode 可用；Retinue 会优先查找官方脚本安装的 %USERPROFILE%\.opencode\bin\opencode，再回退到常见 pnpm/npm/bun shim。默认插件配置会管理本机 OpenCode server 生命周期。
WSL / Linux：默认插件配置会优先使用 127.0.0.1:4096，并在端口被外部服务占用时尝试 4097 到 4127。
macOS：按同样的 Node.js、Codex CLI、OpenCode 前置条件运行；支持仍在验证中。

默认插件配置

插件默认 MCP 配置位于 plugins/retinue/.mcp.json，随包出厂默认值位于 plugins/retinue/retinue.config.json。0.2.0 的 MCP 环境只负责启动后端：

{
  "RETINUE_BACKEND": "opencode",
  "RETINUE_OPENCODE_AUTO_SERVE": "1",
  "RETINUE_OPENCODE_HOST": "127.0.0.1"
}

随包 retinue.config.json 默认是：

{
  "maxConcurrentAgents": 3,
  "opencode": {
    "agent": "explore"
  }
}

这意味着：

Codex 只调用 Retinue，不选择具体后端。
Retinue 默认管理 OpenCode server 生命周期，优先使用 127.0.0.1:4096，端口被外部服务占用时尝试 4097 到 4127。
OpenCode 使用当前本机 profile，包括 provider、model、login、plugin 和 skill。
Retinue 通过官方 OpenCode SDK 调用本机 OpenCode server；手写 HTTP client 只保留为部署诊断/兼容回退。这个选择不改变 OpenCode 对 provider 和 model 的所有权。
explore 是 0.2.0 的默认 agent。Retinue 不再提供产品级 access_mode，也不再用自己的 read-only prompt/tool 覆盖 OpenCode 行为。
OpenCode 使用当前 profile，并按 OpenCode agent/profile 语义决定工具和权限。Retinue 只为直接 child session 派生 TaskTool-compatible session permission，例如按 OpenCode 语义补 todowrite/task deny。
retinue_spawn_agent 只接受任务、工作目录、任务名和 OpenCode agent 选择。不要传 backend、profile、model、OpenCode server、access_mode 或 bash_policy。
retinue_wait_agent 会把单次 MCP wait 限制在宿主安全窗口内，默认最大 180 秒。这个窗口覆盖 OpenCode 默认 45 秒 soft-stall 检测和一次 final-answer rescue；长任务仍可重复调用 wait 轮询，也可用 RETINUE_MCP_WAIT_MAX_MS 调整上限。
每个 Retinue MCP server 会话默认最多保留 3 个 active 子代理。默认 overflow 策略是 RETINUE_OVERFLOW_STRATEGY=queue：超过 session 或机器级 active 槽位时，retinue_spawn_agent 会快速返回 status: "queued" 的 job handle，后续 wait/list/close/spawn 会在空槽出现时 opportunistic promote。需要旧低延迟行为时可显式设置 RETINUE_OVERFLOW_STRATEGY=evict，只驱逐同一 MCP session 内最旧的 running 子代理并返回 evictedJobId。
同一 RETINUE_STATE_DIR 下还会执行机器级 active-agent 预算，避免多个 Codex/Hermes MCP server 把本地槽位相乘。RETINUE_MAX_CONCURRENT_AGENTS 只限制单个 MCP server 会话，包默认值为 3；RETINUE_GLOBAL_AGENT_BUDGET 限制共享 state dir 下的总 active 子代理数，未设置时默认是 max(5, RETINUE_MAX_CONCURRENT_AGENTS)。队列长度由 RETINUE_MAX_QUEUED_AGENTS 限制，默认 20；队列满时新的 spawn 返回 resource_exhausted 和 reason: "queue_full"，不会继续创建后端子代理。
retinue.config.json 是安装缓存内的包默认值，插件更新或缓存同步可能覆盖它；持久调整请写环境变量，例如 Codex [env] 或 Hermes MCP env 中的 RETINUE_MAX_CONCURRENT_AGENTS 和 RETINUE_GLOBAL_AGENT_BUDGET。

当 retinue_wait_agent 返回 status: "running" 时，子代理仍在运行。继续用同一个 jobId 再次调用 retinue_wait_agent；只有任务进入 failed、killed、stalled 或其他终态时，才需要按终态处理或重新启动。

running 响应会包含 stdoutTail、stderrTail、tracePath 和 job artifact 路径。先看 tail 字段；复杂 OpenCode 任务可能会连续几分钟处在 tool-call 阶段，单次 wait 超时不等于子代理失败。

OpenCode 后端长时间没有产出可信最终文本时，Retinue 会把任务报告为 stalled，并在响应中提供诊断摘要。可恢复的后端失败可以启动一次新的 task-level attempt；原 job 仍是 stalled 非证据，wait 响应会带 requestedJobId、selectedAttemptJobId 和 attemptChain。部署可以用 RETINUE_OPENCODE_TASK_ATTEMPT_MAX=0 关闭 fresh attempt；诊断窗口的细粒度环境变量见开发者文档。

retinue_spawn_agent 会同时返回请求的 cwd 和 OpenCode 实际 session 的 externalSessionDirectory。如果两者不一致，先关闭这个子代理，再用目标仓库的绝对路径重新 spawn；在此之前不要相信仓库相关结论。

日志

Retinue 把本地诊断写入 RETINUE_STATE_DIR。未设置时默认位置：

Windows：%LOCALAPPDATA%\retinue
Linux / WSL / macOS：$XDG_STATE_HOME/retinue 或 $HOME/.local/state/retinue

常用文件：

<stateDir>/logs/retinue.jsonl：Retinue trace，包括 OpenCode server 生命周期和 wait 诊断。
<stateDir>/jobs/<jobId>/meta.json：job 元数据。
<stateDir>/jobs/<jobId>/stdout.log 和 stderr.log：终态结果和单 job 诊断。

Claude Code 后端

Claude Code 后端走 Claude Agent SDK 路径。0.2.0 默认不启用它。需要切换时，修改部署配置：

RETINUE_BACKEND=claude-code

Claude Code 的模型、endpoint、权限和 profile 仍由 Claude Code 自己管理。

npm 安装

npm 包用于直接安装 Retinue runtime，适合自定义 MCP 配置或开发者环境：

npm install -g @disaster-terminator/retinue@0.2.0
codex mcp add retinue \
  --env RETINUE_BACKEND=opencode \
  --env RETINUE_OPENCODE_BASE_URL=http://127.0.0.1:4096 \
  --env RETINUE_OPENCODE_AGENT=explore \
  -- retinue-mcp

普通 Codex 用户优先使用插件市场安装；npm 路径不安装 Retinue skill。

Hermes Agent

Hermes Agent 可以把 Retinue 当作 master-agent MCP 集成来用。Hermes 不是 Retinue 后端；Hermes 通过 mcp_servers 加载 Retinue，然后调用带前缀的工具：mcp_retinue_retinue_spawn_agent、mcp_retinue_retinue_wait_agent、mcp_retinue_retinue_close_agent、mcp_retinue_retinue_list_agents。

安装 npm runtime，并把 integrations/hermes/mcp-retinue.yaml 合并进 ~/.hermes/config.yaml；完整说明见 Hermes Agent Integration。默认仍然是 OpenCode explore，并由 Retinue 管理 OpenCode server 生命周期。

验证

Retinue 的发布门控覆盖单元测试、集成测试、包形态校验和真实后端路径。维护者命令和原始验证记录保留在仓库 runbook 与发布会话日志中；面向用户的发布说明只记录产品边界和升级事项。

Name		Name	Last commit message	Last commit date
Latest commit History 294 Commits
.agents/plugins		.agents/plugins
.beads		.beads
.claude		.claude
.githooks		.githooks
.github/workflows		.github/workflows
dist		dist
docs		docs
integrations/hermes		integrations/hermes
plugins/retinue		plugins/retinue
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Retinue

核心能力

边界

快速开始

平台说明

默认插件配置

日志

Claude Code 后端

npm 安装

Hermes Agent

验证

开发者文档

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Retinue

核心能力

边界

快速开始

平台说明

默认插件配置

日志

Claude Code 后端

npm 安装

Hermes Agent

验证

开发者文档

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages