cc-codex-run 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.1 — 2026-11-04
+
+- Published to npm as `cc-codex-run`. No code changes.
+
+## 0.1.0 — 2026-11-04
+
+First public version, extracted from a private Claude Code skill.
+
+- Runs Codex turns on the local app-server daemon; threads stay visible and resumable in the Codex app.
+- Question round-trips (`status=question` / `--answer`), including questions asked by Codex subagents.
+- `--attach`, `--stop`, `--ps`, `--review`, `--schema` (validated locally with Ajv), `--json`, `--install-skills`.
+- Sandbox precedence: `-s`, then the role's `sandbox_mode`, then Codex's own config. No sandbox is forced by default. Each thread's sandbox is recorded; `--resume` reapplies it only when the daemon reports a wider one (a reloaded thread falls back to the config default), and never widens a narrower one. `--answer`/`--attach` reject `-s`: the waiting turn keeps its sandbox.
+- Refuses app-servers older than 0.164.0.
+- Fixes over the private version:
+  - events from another turn on the same thread no longer end the run
+  - a stop signal while `turn/start` is in flight now interrupts the new turn
+  - `--attach` reads back a final answer produced before it attached
+  - `--ps` lists every loaded thread instead of the first 100
+  - an explicit `workspace-write` turn keeps `network_access`, `writable_roots` and the `/tmp` settings from `[sandbox_workspace_write]` instead of resetting them to the defaults
+  - an overdue `turn/completed` is resolved by reading the turn status back from the daemon; a turn still active is never reported as done

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kcng0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# codex-run
+
+[简体中文](README.zh-CN.md)
+
+Claude Code skills and a CLI for handing work to [OpenAI Codex](https://github.com/openai/codex) from Claude Code.
+
+Tasks run on the **local Codex app-server daemon**, the same one the Codex app uses. Every thread `codex-run` starts can be watched, resumed or taken over in the Codex app.
+
+What it adds over calling `codex exec`:
+
+- **Questions round-trip.** When Codex (or one of its subagents) asks something, the run exits with `status=question`. The turn keeps waiting on the daemon, and `--answer` sends the reply into that same turn.
+- **Runs are auditable.** Each run records the commands Codex reported (with exit codes), the files it patched, the model and sandbox actually used, and the full event log.
+- **Runs are recoverable.** If the client dies, `--attach` re-follows a running turn. `--stop` interrupts it. A model that is at capacity is retried on the same thread.
+
+## Requirements
+
+- Linux or macOS. Windows is not supported because the daemon listens on a Unix socket; use WSL.
+- Node.js ≥ 20.
+- Codex CLI ≥ 0.164.0, signed in (`codex login`). `codex-run` starts the daemon itself (`codex app-server daemon start`).
+
+## Install
+
+As a Claude Code plugin (recommended):
+
+```
+/plugin marketplace add kcng0/cc-codex-run
+/plugin install codex-run@cc-codex-run
+```
+
+From npm, as a CLI plus skills copied into `~/.claude/skills`:
+
+```bash
+npm install -g cc-codex-run
+codex-run --install-skills          # add --force to move existing codex/codex-delegate skills aside
+```
+
+## Skills
+
+- **`codex`** teaches Claude how to dispatch, answer, resume, attach to, stop and review with `codex-run`.
+- **`codex-delegate`** is a delegation policy. By default Codex implements modules whose interface contract is fixed and does independent verification and pre-commit review; UI work stays with Claude. Your own CLAUDE.md can widen or narrow this.
+
+## CLI
+
+```bash
+codex-run --role implement -C ~/repo task.md            # new thread
+codex-run --resume <thread> -C ~/repo follow-up.md      # next turn on the same thread
+codex-run --answer <question thread> -C ~/repo answer.md
+codex-run --attach <thread> -C ~/repo
+codex-run --review --base main -C ~/repo [focus.md]
+codex-run --ps | --stop <thread> | --roles | --models
+```
+
+A run prints `key=value` lines (or one JSON object with `--json`): `status`, `job`, `session`, `model`, `sandbox`, `report` and `commands`, then changed files, questions, or the error. It exits 0 for `ok` and `question`, and 1 for any other status. Run `codex-run -h` for every option.
+
+### Roles
+
+A role is a Codex agent TOML file. `--role NAME` reads `$CODEX_HOME/agents/NAME.toml` first and falls back to the examples bundled in `plugin/skills/codex/roles/` (`implement`, `check`, `critic`, `explore`). The bundled roles set no model, so your Codex config decides.
+
+To customize a role, create a file of the same name in `$CODEX_HOME/agents/`; it shadows the bundled one. New names work the same way. `codex-run --roles` shows every role and marks the bundled ones. Only these keys are read:
+
+```toml
+# ~/.codex/agents/implement.toml
+description = "Implements one module within an explicit file ownership"
+model = "gpt-6.1-sol"             # optional, from `codex-run --models`; omit to use your Codex config
+model_reasoning_effort = "high"   # optional
+sandbox_mode = "workspace-write"  # optional: read-only | workspace-write | danger-full-access
+developer_instructions = """
+...
+"""
+```
+
+If you also register the same file as a Codex agent role (`[agents.<name>] config_file = ...` in `config.toml`), Codex's own subagents use it too, so its `sandbox_mode` and instructions apply to both.
+
+### Sandbox and approvals
+
+The sandbox comes from `-s` first, then the role's `sandbox_mode`. Without either, a new thread gets Codex's own config default. For each thread, `codex-run` records the sandbox it ran with (in `$CODEX_RUN_HOME/threads/`, kept 90 days). `--resume` without `-s` or a role reapplies it only when the daemon reports a wider sandbox (a thread reloaded from disk falls back to the config default), and never widens a narrower one. `--answer` and `--attach` reject `-s`, because the waiting turn keeps the sandbox it started with.
+
+Approvals are always off (`approvalPolicy=never`) because nobody is there to approve. A command that needs to leave a restricted sandbox fails instead of prompting, so pick a sandbox wide enough for the task. `danger-full-access` gives Codex unrestricted access to your machine.
+
+What the restricted sandboxes allow for shell commands (measured on Linux with Codex 0.164.0). Codex's built-in web search is not a shell command and works under `read-only` too.
+
+| | read-only | workspace-write |
+|---|---|---|
+| read files | yes | yes |
+| write in the `-C` dir and `/tmp` | no | yes |
+| write elsewhere (`~/.cache`, `~/.npm`, `~/.cargo`, …) | no | no |
+| write `.git` (commit, branch) | no | no |
+| network, including localhost servers | no | only with `network_access = true` |
+| talk to the Codex daemon | no | no |
+
+So under `workspace-write` with Codex's defaults, installing dependencies, builds that keep a cache in your home directory (Go, Cargo, Playwright), starting a local server for an end-to-end check, and committing all fail. Either widen the sandbox in `~/.codex/config.toml`:
+
+```toml
+[sandbox_workspace_write]
+network_access = true
+writable_roots = ["/home/you/.cache"]   # optional: only to write outside the -C dir and /tmp; absolute paths
+```
+
+or pass `-s danger-full-access` for that task. `codex-run` carries these `[sandbox_workspace_write]` settings into every `workspace-write` turn it starts.
+
+#### Roles that need MCP tools or script-running skills
+
+Under `read-only` and `workspace-write`, two things a role may rely on fail:
+
+- **MCP tools.** With approvals off, Codex rejects any MCP call that needs approval ("MCP tool call requires approval, but approval policy is never"). In Codex's default `auto` mode that is every tool not annotated read-only, so most servers (search, docs, code-context, browser) fail. `danger-full-access` calls them without approval.
+- **Skills and CLIs run through the shell**, such as a docs lookup that calls a CLI over the network, or a skill script that writes a cache or temp file. They get the shell limits in the table above.
+
+Codex has no global switch for MCP approval. It can only be set per server (`[mcp_servers.<id>] default_tools_approval_mode = "approve"`), and every server added later needs it too.
+
+The recommended setup: give every role that needs MCP tools, script-running skills or the network `sandbox_mode = "danger-full-access"`, and keep the read-only boundary in its `developer_instructions` ("read-only: do not modify files"). That boundary is then enforced by the instructions, not by the sandbox. Keep `read-only` only for roles that just read files and run simple commands. Remember that a role file in `$CODEX_HOME/agents/` that is also registered in `config.toml` applies to Codex's own subagents too.
+
+### Files and environment
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CODEX_HOME` | `~/.codex` | Codex home (roles in `agents/`) |
+| `CODEX_RUN_HOME` | `$XDG_STATE_HOME/codex-run` or `~/.local/state/codex-run` | job directories in `jobs/` |
+| `CODEX_RUN_JOB_TTL_DAYS` | `7` | finished jobs older than this are pruned at start; `0` disables |
+
+Each job directory holds `task.md`, `report.md`, `meta.json`, `events.jsonl` and, when present, `commands.jsonl`, `questions.json` and `stderr.log`.
+
+## Before you use it
+
+- The `codex` skill pre-approves its own script (`allowed-tools`), so Claude can start Codex runs without a permission prompt. What Codex may then do is bounded only by the sandbox; choose roles and `-s` accordingly.
+- Runs use your Codex account and count against its usage limits.
+- Runs share the daemon with the Codex app: threads appear there, and the daemon keeps running after `codex-run` exits.
+- Codex's own subagents are off unless you pass `--allow-subagents`.
+
+## Limitations
+
+- The app-server protocol is marked experimental by Codex. `codex-run` refuses versions older than 0.164.0, but newer versions may change it.
+- `commands.jsonl` lists commands Codex reports as `commandExecution` items. Commands Codex runs through its code-mode `exec` tool are not reported by the daemon. "Changed files" covers apply_patch only; use `git status` for the real scope.
+- Older Codex versions sometimes never sent `turn/completed` for a parent turn with subagents (not reproduced on 0.164.0). As a fallback, if the final answer exists, all subagents have ended and 5 s have passed quietly, `codex-run` reads the turn status back from the daemon. A finished turn or an idle thread ends the run with an `inferred=` line; a turn that is still active is followed further and never reported as done.
+
+## Compared with openai/codex-plugin-cc
+
+The official plugin also talks to the app-server, but through its own per-workspace broker. It offers rescue/review commands and a Stop-hook review gate. `codex-run` instead uses the shared Codex daemon, so there is no broker process to leak or kill, and focuses on question round-trips, re-attaching, and auditable run records.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,167 @@
+# codex-run
+
+[English](README.md)
+
+在 Claude Code 里把任务交给 [OpenAI Codex](https://github.com/openai/codex) 的 skills 和 CLI。
+
+任务运行在**本机的 Codex app-server daemon** 上，和 Codex app 用的是同一个 daemon，所以 `codex-run` 开的每个会话都能在 Codex app 里查看、续接或接手。
+
+相比直接调用 `codex exec`：
+
+- **提问可以往返**：Codex（或它的子代理）中途提问时，`codex-run` 以 `status=question` 退出，turn 留在 daemon 上等待；之后用 `--answer` 把答复送回同一个 turn。
+- **运行过程可核验**：每次运行都会记录 Codex 上报的命令及退出码、改动的文件、实际使用的模型和沙箱，以及完整的事件日志。
+- **中断后可恢复**：客户端退出后可用 `--attach` 重新跟随正在运行的 turn，用 `--stop` 中断它。模型满载时在同一会话上自动续跑。
+
+## 运行要求
+
+- Linux 或 macOS。daemon 监听 Unix socket，所以不支持 Windows，请用 WSL。
+- Node.js ≥ 20。
+- Codex CLI ≥ 0.164.0，并已登录（`codex login`）。daemon 由 `codex-run` 自动启动（`codex app-server daemon start`）。
+
+## 安装
+
+推荐作为 Claude Code 插件安装：
+
+```
+/plugin marketplace add kcng0/cc-codex-run
+/plugin install codex-run@cc-codex-run
+```
+
+也可以通过 npm 安装 CLI，再把 skills 复制到 `~/.claude/skills`：
+
+```bash
+npm install -g cc-codex-run
+codex-run --install-skills          # 已有同名 codex / codex-delegate skill 时，加 --force 会先把它们改名备份
+```
+
+## Skills
+
+- **`codex`**：教 Claude 用 `codex-run` 派发任务、答复提问、续接、重新跟随、停止和 review。
+- **`codex-delegate`**：委派策略。默认交给 Codex 的是三类工作：接口合同已定的模块实现、独立验收、提交前审查；UI 工作留给 Claude。范围可以在你自己的 CLAUDE.md 里放宽或收窄。
+
+## CLI
+
+```bash
+codex-run --role implement -C ~/repo task.md            # 新会话
+codex-run --resume <thread> -C ~/repo follow-up.md      # 在同一会话上开下一轮
+codex-run --answer <提问线程> -C ~/repo answer.md
+codex-run --attach <thread> -C ~/repo
+codex-run --review --base main -C ~/repo [focus.md]
+codex-run --ps | --stop <thread> | --roles | --models
+```
+
+输出格式：
+
+- 默认是 `key=value` 行，依次为 `status`、`job`、`session`、`model`、`sandbox`、`report`、`commands`，后面跟改动文件、问题或错误信息。
+- 加 `--json` 时改为输出一个 JSON 对象。
+- 退出码：`ok` 和 `question` 为 0，其余状态为 1。
+
+全部参数见 `codex-run -h`。
+
+### 角色
+
+角色就是一个 Codex agent TOML 文件。`--role NAME` 先读 `$CODEX_HOME/agents/NAME.toml`；找不到时回退到 `plugin/skills/codex/roles/` 里自带的示例角色（`implement`、`check`、`critic`、`explore`）。自带角色不指定模型，由你的 Codex 配置决定。
+
+要自定义角色，在 `$CODEX_HOME/agents/` 下建同名文件，它会覆盖自带角色；新名字同理。`codex-run --roles` 列出全部角色，并标出哪些是自带的。只读取以下字段：
+
+```toml
+# ~/.codex/agents/implement.toml
+description = "在明确的文件归属内实现一个模块"
+model = "gpt-6.1-sol"             # 可选，取自 `codex-run --models`；不写则用 Codex 配置
+model_reasoning_effort = "high"   # 可选
+sandbox_mode = "workspace-write"  # 可选：read-only | workspace-write | danger-full-access
+developer_instructions = """
+...
+"""
+```
+
+如果同一个文件也注册成了 Codex 的 agent role（在 `config.toml` 里写 `[agents.<name>] config_file = ...`），Codex 自己的子代理也会用它，其中的 `sandbox_mode` 和说明对两边同时生效。
+
+### 沙箱与审批
+
+沙箱按以下优先级确定：
+
+1. `-s` 参数；
+2. 角色的 `sandbox_mode`；
+3. 两者都没有时，新会话使用 Codex 配置的默认沙箱。
+
+`codex-run` 会记录每个会话运行时的沙箱（存于 `$CODEX_RUN_HOME/threads/`，保留 90 天）。不带 `-s` 或角色执行 `--resume` 时：
+
+- 如果 daemon 报告的沙箱比记录的更宽（daemon 从磁盘重新加载会话后会退回配置默认值），就重新应用记录值；
+- 如果比记录的更窄，就保持不变，绝不放宽。
+
+`--answer` 和 `--attach` 不接受 `-s`，因为正在等待的 turn 保留它启动时的沙箱。
+
+审批始终关闭（`approvalPolicy=never`），因为没有人在旁边批准。在受限沙箱里，需要越界的命令会直接失败而不是等待批准，所以要按任务选够用的沙箱。`danger-full-access` 意味着 Codex 可以不受限制地访问本机。
+
+受限沙箱对 shell 命令的限制如下（Linux、Codex 0.164.0 实测）。Codex 内置的 web search 不是 shell 命令，在 `read-only` 下也能用。
+
+| | read-only | workspace-write |
+|---|---|---|
+| 读文件 | 可以 | 可以 |
+| 写 `-C` 目录和 `/tmp` | 不可以 | 可以 |
+| 写其他位置（`~/.cache`、`~/.npm`、`~/.cargo` 等） | 不可以 | 不可以 |
+| 写 `.git`（commit、建分支） | 不可以 | 不可以 |
+| 网络，包括本机 localhost 服务 | 不可以 | 仅当 `network_access = true` |
+| 连接 Codex daemon | 不可以 | 不可以 |
+
+所以在 Codex 默认配置的 `workspace-write` 下，安装依赖、把缓存放在主目录的构建（Go、Cargo、Playwright）、为端到端验证启动本地服务、提交，都会失败。可以在 `~/.codex/config.toml` 里放宽：
+
+```toml
+[sandbox_workspace_write]
+network_access = true
+writable_roots = ["/home/you/.cache"]   # 可选：仅在需要写 -C 目录和 /tmp 以外的位置时；绝对路径
+```
+
+或者对该任务传 `-s danger-full-access`。`codex-run` 启动的每个 `workspace-write` turn 都会带上这些 `[sandbox_workspace_write]` 设置。
+
+#### 需要 MCP 工具或会执行脚本的 skills 的角色
+
+在 `read-only` 和 `workspace-write` 下，角色可能依赖的两类能力会失败：
+
+- **MCP 工具。** 审批关闭时，凡是需要审批的 MCP 调用都会被 Codex 直接拒绝（"MCP tool call requires approval, but approval policy is never"）。Codex 默认的 `auto` 模式下，没有标注只读的工具都需要审批，所以大多数 server（搜索、文档、代码上下文、浏览器）都用不了。`danger-full-access` 下调用不需要审批。
+- **通过 shell 执行的 skills 和 CLI**，比如要联网调用 CLI 的文档查询，或者会写缓存、临时文件的 skill 脚本。它们受上表中 shell 命令的同样限制。
+
+Codex 没有全局的 MCP 审批开关，只能按 server 单独设置（`[mcp_servers.<id>] default_tools_approval_mode = "approve"`），以后每新增一个 server 都要再加一次。
+
+推荐做法：需要 MCP 工具、会执行脚本的 skills 或网络的角色，一律设为 `sandbox_mode = "danger-full-access"`，只读要求写进角色的 `developer_instructions`（例如"只读：不修改文件"）。这时只读靠指令约束，不再由沙箱强制。只读文件、跑简单命令的角色才保留 `read-only`。注意：`$CODEX_HOME/agents/` 里的角色文件如果也在 `config.toml` 里注册了，对 Codex 自己的子代理同样生效。
+
+### 文件与环境变量
+
+| 变量 | 默认值 | 用途 |
+|---|---|---|
+| `CODEX_HOME` | `~/.codex` | Codex 主目录（角色放在 `agents/`） |
+| `CODEX_RUN_HOME` | `$XDG_STATE_HOME/codex-run`，未设置时为 `~/.local/state/codex-run` | job 目录放在 `jobs/` |
+| `CODEX_RUN_JOB_TTL_DAYS` | `7` | 启动时清理早于这个天数的已结束 job；`0` 表示不清理 |
+
+每个 job 目录包含 `task.md`、`report.md`、`meta.json`、`events.jsonl`，以及按需生成的 `commands.jsonl`、`questions.json` 和 `stderr.log`。
+
+## 使用须知
+
+- `codex` skill 预先批准了自己的脚本（`allowed-tools`），Claude 启动 Codex 任务时不会弹权限确认。之后 Codex 能做什么只受沙箱限制，请据此选择角色和 `-s`。
+- 运行消耗你的 Codex 账号额度。
+- 运行与 Codex app 共用 daemon：会话会出现在 Codex app 里，`codex-run` 退出后 daemon 仍在运行。
+- 除非加 `--allow-subagents`，Codex 自身的子代理是关闭的。
+
+## 已知限制
+
+- Codex 把 app-server 协议标为 experimental。`codex-run` 会拒绝 0.164.0 以下的版本，但更新的版本仍可能改动协议。
+- `commands.jsonl` 只记录 Codex 以 `commandExecution` 上报的命令；Codex 通过 code-mode `exec` 工具执行的命令，daemon 不会上报。"改动文件"只包含经 apply_patch 写入的文件，实际改动范围以 `git status` 为准。
+- 较旧的 Codex 在带子代理时偶尔收不到父 turn 的 `turn/completed`（0.164.0 实测未复现）。作为兜底：
+  - 最终回复已出现、子代理都已结束，且静默 5 秒后，`codex-run` 会向 daemon 查询 turn 状态；
+  - turn 已结束或线程已 idle，就结束运行，并输出 `inferred=` 行；
+  - turn 仍在运行，就继续跟随，不会误报完成。
+
+## 与 openai/codex-plugin-cc 的区别
+
+官方插件也通过 app-server 调用 Codex，但每个工作区自建一个 broker 进程，提供 rescue、review 命令和 Stop hook review 关卡。
+
+`codex-run` 直接使用 Codex 共享的 daemon，没有要管理的 broker 进程，因此不会出现 broker 进程泄漏或被误杀的问题。它的重点是提问往返、重新跟随运行中的任务和可核验的运行记录。
+
+## 开发
+
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cc-codex-run",
+  "version": "0.1.1",
+  "description": "Claude Code skills and CLI for delegating work to OpenAI Codex through the local Codex app-server daemon",
+  "type": "module",
+  "bin": {
+    "codex-run": "plugin/skills/codex/scripts/codex-run.mjs"
+  },
+  "files": [
+    "plugin/",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node scripts/build.mjs && node --test test/*.test.mjs",
+    "check:bundle": "node scripts/build.mjs && git diff --exit-code -- plugin/",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "openai-codex",
+    "agent",
+    "skills"
+  ],
+  "author": "kcng0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kcng0/cc-codex-run.git"
+  },
+  "homepage": "https://github.com/kcng0/cc-codex-run#readme",
+  "bugs": "https://github.com/kcng0/cc-codex-run/issues",
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "esbuild": "^0.28.2",
+    "smol-toml": "^1.9.1",
+    "ws": "^8.22.1"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "codex-run",
+  "version": "0.1.1",
+  "description": "Delegate tasks, questions and reviews to OpenAI Codex through the local Codex app-server daemon",
+  "author": {
+    "name": "kcng0"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/kcng0/cc-codex-run",
+  "homepage": "https://github.com/kcng0/cc-codex-run#readme",
+  "keywords": [
+    "codex",
+    "openai",
+    "delegation",
+    "review"
+  ]
+}

package/plugin/skills/codex/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: codex
+description: Run tasks on OpenAI Codex through the local Codex app-server daemon — pick a role or model, run several in the background, answer Codex's questions, resume a thread by id, or run Codex's built-in review. Use whenever you need to call Codex.
+allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/codex-run.mjs *)
+---
+
+# Calling Codex
+
+Script: `${CLAUDE_SKILL_DIR}/scripts/codex-run.mjs` (always call it by this full path; `-h` lists options). Tasks run on the local Codex app-server daemon (started automatically). Thread names start with `[codex-run·<role>]`, and the user can watch or take over them in the Codex app.
+
+## Dispatching
+
+1. Write the task to a file. Codex cannot see this conversation, so the task must stand alone: goal, working directory, file ownership, known facts, constraints, a checkable definition of done, and what to do when information is missing (assume and report it, or stop and report blocked). Put one task in each run, and dispatch unrelated work separately.
+2. Run it with Bash `run_in_background: true`:
+
+   ```bash
+   ${CLAUDE_SKILL_DIR}/scripts/codex-run.mjs --role <role> -C <workdir> <task file>
+   ```
+
+   - **Roles** set the responsibilities and the default model, effort and sandbox. `--roles` lists them; roles in `$CODEX_HOME/agents/` shadow the bundled examples. If the task is clearly lighter or harder than the role's default, override with `-m`/`-e` (pick from `--models`). If results are weak, first tighten the task (definition of done, verification), then start a new thread with higher effort.
+   - **Without a fitting role**, pass only `-m`/`-e`. The task file then has to state the definition of done and the report format (first line complete / partial / blocked).
+   - **Timeout**: 5400 s by default; change it with `-t`.
+   - **Sandbox**: `-s` wins, then the role's `sandbox_mode`. Without either, a new thread gets Codex's own config default, and `--resume` keeps the thread's current sandbox. If the daemon reports a wider sandbox than codex-run recorded for that thread (a thread reloaded from disk falls back to the config default), the recorded one is reapplied; a narrower one is never widened. `--answer`/`--attach` do not take `-s`, because the waiting turn keeps its sandbox. Approvals are always off (`approvalPolicy=never`), so a command that needs to leave a restricted sandbox fails with "Approval requests were disabled". Choose a sandbox wide enough for the task rather than expecting escalation. Under `read-only`, shell commands cannot write anywhere, not even `/tmp`. Under `workspace-write`, only the `-C` dir and `/tmp` are writable, `.git` is read-only (no commits), and the network, localhost included, is off unless the user enabled `network_access`. Pass `-s danger-full-access` when the task must install dependencies, start a local server, use caches in the home directory, or commit. Codex's built-in web search works in every sandbox. Outside `danger-full-access`, MCP tool calls fail with "MCP tool call requires approval" (Codex has no global switch for this), and skills that run scripts get the shell limits. A task that needs MCP tools, such skills or the network gets `-s danger-full-access` (or a role that has it); state any read-only requirement in the task file instead.
+   - **Subagents**: Codex's own subagents are off by default because orchestration is yours. Add `--allow-subagents` only when the task really needs Codex to split it. If `turn/completed` is overdue (a final answer exists, all subagents ended, 5 s of quiet), the script reads the turn's status back from the daemon. A finished turn or an idle thread ends the run with an `inferred=` line; a turn still active keeps being followed.
+   - **Structured results**: `--schema <JSON Schema file>` sets the turn's `outputSchema` and validates the final message locally. A message that is not JSON or does not match gives `status=failed`, and the schema's fields replace the first-line convention. For independent verification, use `${CLAUDE_SKILL_DIR}/schemas/check.json`. The schema is bound to the turn: after a question, answering with `--answer` keeps the same turn and the same schema, so do not re-run with `--resume` just to get structured output.
+   - `--json` prints one JSON object instead of `key=value` lines.
+3. **Do not poll.** When the completion notification arrives, read `status`, `session`, `model`, `sandbox` and `report`, then read the whole report (first line complete / partial / blocked, or the schema's `status` field).
+   - `model` and `sandbox` are what the run actually used. If they differ from what you expected, find out why before trusting the result.
+   - `commands=` points to the commands Codex reported (exit code, cwd, including subagents). Commands Codex runs through its code-mode `exec` tool are not reported there.
+   - `--- changed files ---` lists files written through apply_patch only. Treat `git status` / diff as the real scope of changes.
+   - Use these to check the report's claims about checks run and file ownership.
+   - **partial / blocked** means there are open issues: if information is missing, provide it and resume; if it is a design decision, decide it yourself and resume; if it is outside the delegated scope, take it over or ask the user.
+4. **`status=question`**: Codex asked something (an async question, or a blocking `request_user_input`). The turn is still waiting on the daemon; the client exited and printed the questions with their options. Options marked "free-form answer allowed" may be answered outside the list.
+   - **You answer it, not the user**: decide whatever the task, docs, code or earlier decisions settle. Questions that belong to the user (product trade-offs, scope, irreversible effects) go to the user first. If the question points out a conflict between the task file and the docs, check which one is right and fix the task file.
+   - **Sending the answer**: write the answer to a file and run the printed `--- answer ---` command in the background: `codex-run --answer <question thread> --role <same role> -C <same dir> [--schema <same schema>] <answer file>`.
+     - If a subagent asked, the question thread is the subagent's (`question_thread=`); the run still follows the root turn and reports on `session`.
+     - Write the answer itself (an option's label for a choice).
+     - When several questions with ids are listed, write JSON `{"<question id>": "answer"}`. A malformed answer gives `status=failed` while Codex keeps waiting; fix the file and `--answer` again.
+5. **Any other non-`ok` status**: diagnose from the printed error and `<job>/stderr.log` before re-dispatching; do not retry blindly. `disconnected` means the daemon connection dropped (for example a daemon update). The thread is kept, so continue it with `--resume`.
+6. **Model at capacity**: the script handles `Selected model is at capacity` itself. After Codex's own retries inside the turn run out, the script backs off (60→300 s) and continues on the same thread and model until the timeout, noting each retry on stderr. Do not switch models or threads for this. If it is still at capacity at the timeout, `--resume` later with the same input.
+7. **Job directories** are under `$CODEX_RUN_HOME/jobs` (default `~/.local/state/codex-run/jobs`). Finished jobs older than 7 days are pruned automatically. You may delete a job directory once you are done with it; leave other jobs alone, since they may belong to other sessions.
+
+## Watching and stopping
+
+- `--ps` lists threads with a turn in progress on the daemon (model, directory, parent for subagents). Use it as the truth for how many tasks are running.
+- **Stop**: TaskStop on the background Bash is enough. On SIGTERM the script interrupts the turn on the daemon, including a turn whose start request was still in flight, and prints `status=interrupted`. If the client is already gone (killed, or left over from another session), use `--stop <thread>`. Ending only the client does not stop the turn.
+- **Re-attach**: if the client exited while the turn is still running, run `--attach <thread> -C <same dir>` in the background. It sends no input and does not interrupt, and if the final answer was produced before you attached, it is read back. To replace a running client, `kill -KILL <old client pid>` first (SIGKILL skips the interrupt handler, so the turn is unaffected); do not use TaskStop for this.
+
+## Parallel runs
+
+- Several background calls in one message run in parallel. Their file ownership must not overlap. When changes would cross, give each task its own git worktree as `-C` and merge them yourself.
+- Tell each task that other collaborators exist and must not have their changes reverted, and assign shared resources (ports, databases, whether dependencies may be installed).
+
+## Resuming
+
+By default every task gets a new thread. Resume only when the next turn depends on **the same task's** context in that thread: filling in what a partial / blocked report lacked, re-checking counterexamples it reported, discussing a disagreement about its result, or continuing after `disconnected` or a capacity timeout.
+
+Start a new thread, and hand over the needed conclusions in the task file, when:
+- it is a new task or goal (even with the same directory and role)
+- the direction changed
+- you need a different model or effort
+- the thread has many turns whose history would bias a new judgment
+- you need a judgment independent of earlier conclusions
+
+When unsure, start a new thread.
+
+```bash
+${CLAUDE_SKILL_DIR}/scripts/codex-run.mjs --resume <thread> --role <same role> -C <same dir> <follow-up file>
+```
+
+Resume by thread id (parallel runs make "last thread" ambiguous). The follow-up file holds only the new instructions.
+
+A resumed thread keeps its model and effort and does not accept `-m`/`-e`. `--role` contributes its instructions and sandbox, never its default model. To switch models, start a new thread and hand over the earlier conclusions and open questions.
+
+## Review
+
+```bash
+${CLAUDE_SKILL_DIR}/scripts/codex-run.mjs --review [--base <branch> | --commit <sha>] -C <repo> [focus file]
+```
+
+Runs Codex's built-in read-only review of git changes; uncommitted changes (including untracked files) by default. The optional focus file names the risks to look at. `--review` takes no `--role`, `--resume`, `-s` or `--schema`.
+
+## Treating results
+
+Codex is a colleague, not an authority. Treat the report as leads. Read the diff and confirm the behavior on the real entry point before delivering. Settle disagreements by resuming the thread: say you are Claude, which model you are, and give evidence. If you still disagree, hand it to the user.

package/plugin/skills/codex/roles/check.toml

@@ -0,0 +1,11 @@
+description = "Independent verification of someone else's change: reads the implementation for counterexamples, exercises the real entry point; does not edit product code"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+You are an independent verifier. Your goal is to find the inputs or orderings under which the delegated change does not behave as expected, not to confirm that it works. The author's claims and test results are leads, not evidence.
+Look only at the delegated change and the behavior it directly affects. Read the implementation for counterexamples first, then pick boundary inputs from the input surface the change actually touches: empty values, very long values, missing items, no permission, letter case, symlinks, relative paths escaping the directory, non-UTF-8, concurrency and races, dropped connections, duplicate submissions, timeout boundaries. Use only inputs reachable from the real entry point or at a system boundary.
+For each counterexample give the triggering input, actual output and expected output. Take expected values from outside the code under test (upstream docs, real user input, examples given in the task), never from the implementation's own constants. Also trigger the feature once through the stated real entry point and record what really happens. Test results, source matches, files existing or HTTP 200 are only probes.
+Do not modify product code, dependencies or assertions. Put scratch scripts in the system temp directory and delete them when done. Check the environment and the scope of side effects before running anything; production or sensitive data needs explicit authorization in the task.
+Report only counterexamples that affect correctness or the requirements; list the rest as optional. Do not invent findings to fill a quota.
+Start the final message with complete / partial / blocked, then give the real entry point and its actual behavior; counterexamples (input, actual vs. expected, location, impact); optional issues; what was and was not covered.
+"""

package/plugin/skills/codex/roles/critic.toml

@@ -0,0 +1,8 @@
+description = "Read-only review of a high-impact decision: goals, scope, assumptions, acceptance criteria; flags risks that would change the plan"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+Read-only, for local files and external data alike. Review the decision's goals, scope, assumptions and acceptance criteria, and raise only issues that would change the direction or cause major rework.
+Ground each issue in facts: the condition under which the assumption holds, counter-evidence (file:line or source), and the real impact. Compare alternatives only when they would change the decision. Do not invent issues to fill a quota or add process. Stop once the evidence is sufficient.
+Start the final message with complete / partial / blocked, then list issues by impact with their conditions, evidence and the decision needed. State uncertainty explicitly.
+"""

package/plugin/skills/codex/roles/explore.toml

@@ -0,0 +1,9 @@
+description = "Read-only: locates entry points, call paths and file ownership for a well-scoped code question"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Read-only, for local files and external data alike. Locate the entry points, relevant call paths and file ownership for the delegated question. Reuse known facts, and stop searching once you can answer.
+Separate verified relations from inferences and unchecked branches. Prefer reading code over guessing.
+If the question leads into complex causality beyond its scope, return partial with the specific gap instead of expanding into a whole-repository analysis.
+Start the final message with complete / partial / blocked, then give the conclusion, key files and symbols (file:line), evidence, and what was not covered.
+"""

package/plugin/skills/codex/roles/implement.toml

@@ -0,0 +1,12 @@
+description = "Implements one self-contained module within an explicit file ownership; reports the real entry point to exercise it"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Investigate, implement and fix within the files the task assigns to you. Prefer the project's existing mechanisms, and keep design choices inside the delegated scope.
+The implementation must hold for every valid input: no hard-coding, no special cases for particular inputs. If the task is infeasible or the requirement looks wrong, report it instead of working around it.
+You are not the only collaborator. Change only the files you own, and keep and adapt to changes you did not make. Hand cross-boundary contract changes or shared-resource conflicts back to whoever delegated the task.
+Follow the repository's conventions. When information is missing, use the default the task specifies (or a reasonable assumption you report), or stop and report blocked.
+Write only high-value tests: regression tests for bugs, key branches of pure logic, key paths of external contracts. No snapshot tests.
+Run probes such as builds, type checks and existing tests, and fix failures you introduced. Passing probes do not prove the feature works: exercise the real entry point where you can, and say what you ran and what you could not run.
+Start the final message with complete / partial / blocked, then give the behavior change, changed files, the real entry point (where and how a user triggers it), checks run with results, and open issues. Separate facts from inferences.
+"""