Initial Claude Code Codex subagents plugin

Add a daemonless Claude Code MCP plugin for launching OpenAI Codex agents from Claude Code.

Includes read-only defaults, Codex desktop binary resolution, project_dir support, parallel agent runs, Spark model presets, nested Codex subagent configuration, GitHub CI, comprehensive fake/runtime validation, and opt-in live Claude plus real Codex tests.

Author: xuio

.claude-plugin/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "codex-subagents": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/dist/index.js",
+      "env": {
+        "CLAUDE_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}"
+      }
+    }
+  }
+}

.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "codex-subagents",
+  "version": "0.1.0",
+  "description": "Launch OpenAI Codex agents from Claude Code through a daemonless MCP server.",
+  "author": {
+    "name": "xuio"
+  },
+  "license": "MIT",
+  "keywords": ["codex", "subagents", "mcp", "parallel"],
+  "mcpServers": "./.claude-plugin/mcp.json",
+  "skills": "./skills"
+}

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Node ${{ matrix.node }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Test
+        run: npm run test:ci

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.DS_Store
+.env
+*.log
+coverage/
+.vitest/
+tmp/

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Claude Code plugin for launching Codex agents through a daemonless stdio MCP server.
+- Added read-only defaults, non-interactive approvals, Codex desktop binary resolution, and per-call `project_dir`.
+- Added single-agent, parallel-agent, Spark preset, and nested Codex subagent support.
+- Added unit, MCP smoke, reliability, runtime, desktop Claude Code, and opt-in live Claude/Codex validation scripts.

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for improving `claude-code-codex-subagents`.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+npm run test:ci
+```
+
+`test:ci` is the portable suite used by GitHub Actions. It uses the fake Codex binary and does not require Claude Code, the Codex desktop app, or live credentials.
+
+Desktop-only and live-token checks are available when you need end-to-end validation:
+
+```sh
+npm run test:comprehensive
+npm run test:claude-orchestration
+npm run test:claude-real-codex
+```
+
+## Pull Requests
+
+- Keep the default sandbox behavior read-only unless a change explicitly requires otherwise.
+- Prefer small, focused changes with tests that cover the MCP contract.
+- Do not commit credentials, local logs, generated temp files, or machine-specific paths.
+- Run `npm run build` before committing changes to `src/`, because the plugin manifest loads `dist/index.js`.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xuio
+
+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.

README.md

@@ -0,0 +1,90 @@
+# Claude Code Codex Subagents
+
+[![CI](https://github.com/xuio/claude-code-codex-subagents/actions/workflows/ci.yml/badge.svg)](https://github.com/xuio/claude-code-codex-subagents/actions/workflows/ci.yml)
+
+Claude Code plugin that exposes OpenAI Codex agents through a daemonless stdio MCP server.
+
+The plugin lets Claude Code launch one Codex agent or several Codex agents in parallel. It is designed for read-only delegation by default: codebase exploration, review, planning, risk checks, documentation mapping, and other sidecar work where Claude should collect independent Codex results without giving those agents write access.
+
+## Defaults
+
+- Codex binary: prefers `/Applications/Codex.app/Contents/Resources/codex` when the Codex desktop app is installed, then falls back to configured overrides and `codex` on `PATH`.
+- Sandbox: `read-only`.
+- Approvals: non-interactive `approval_policy="never"`.
+- Transport: stdio MCP, launched by Claude Code for the active session. No daemon is required.
+- Prompt delivery: stdin, not command-line arguments.
+
+Optional environment overrides:
+
+- `CODEX_SUBAGENTS_CODEX_BIN`: explicit Codex CLI path.
+- `CODEX_SUBAGENTS_DEFAULT_MODEL`: model to use when a tool call omits `model`.
+- `CODEX_SUBAGENTS_DEFAULT_REASONING_EFFORT`: `minimal`, `low`, `medium`, `high`, or `xhigh`.
+
+## Spark And Nested Subagents
+
+Use `model_preset: "spark"` to launch a top-level Codex agent with `gpt-5.3-codex-spark`. Exact `model` still wins when both are provided.
+
+To let a Codex agent spawn its own Codex subagents, pass:
+
+- `codex_subagents`: custom Codex agent definitions with `name`, `description`, `developer_instructions`, optional `model` or `model_preset`, reasoning effort, sandbox, MCP servers, skills config, and extra config.
+- `subagent_tasks`: the specific built-in or custom subagents the parent Codex run should spawn and wait for.
+- `subagent_runtime`: runtime limits such as `max_threads`, `max_depth`, and `job_max_runtime_seconds`.
+
+Custom subagents are passed to Codex as `agents.<name>...` config overrides and also materialized in a temporary Codex home for the duration of one run. The target project is not modified, and the default sandbox remains `read-only`.
+
+## Installation
+
+```sh
+git clone <repo-url>
+cd claude-code-codex-subagents
+npm install
+npm run build
+claude --plugin-dir .
+```
+
+The plugin manifest points Claude Code at `dist/index.js`, so run `npm run build` after changing TypeScript source. The built file is committed so the plugin can be loaded directly from a clone.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+npm run test:comprehensive
+npm run validate:plugin
+npm run test:claude-desktop
+```
+
+`test:ci` is the GitHub-safe suite. It uses the fake Codex binary and does not require Claude Code, the Codex desktop app, or live model credentials.
+
+`test:comprehensive` runs the TypeScript build, unit tests, stdio MCP smoke test, reliability matrix, Codex desktop runtime probe, Claude plugin validation, and desktop-shipped Claude Code CLI plugin/auth checks. The runtime probe validates local Codex capabilities without invoking a model.
+
+`test:claude-orchestration` is an opt-in live Claude Code test. It loads the plugin inside Claude Code, lets Claude call the plugin MCP tools, and uses the fake Codex binary so no Codex model tokens are spent. It is kept out of `test:comprehensive` because it does spend Claude tokens.
+
+`test:claude-real-codex` is the full opt-in live path: Claude Code loads the plugin and calls real Codex through the desktop app binary, including one single agent, one parallel run, and one nested Spark subagent run. It spends both Claude and Codex tokens, so it is intentionally not part of the default suite.
+
+Run Claude Code with the local plugin:
+
+```sh
+claude --plugin-dir .
+```
+
+After startup, ask Claude to use Codex subagents, or invoke the plugin skill:
+
+```text
+/codex-subagents:codex-subagents run three read-only Codex agents: one for API flow, one for tests, one for security risks
+```
+
+## MCP Tools
+
+`run_agent` launches one Codex `exec` process.
+
+`run_agents` launches multiple Codex `exec` processes concurrently with a bounded `max_parallel` setting.
+
+`codex_status` reports the resolved Codex binary, server working directory, Claude project directory, default model, default reasoning effort, and version probe.
+
+Each agent accepts model, reasoning effort, sandbox, project directory, timeout, and output-size controls. Pass `project_dir` when Claude Code wants Codex to inspect the same repository or subdirectory Claude is currently working in. If `project_dir` is omitted, the server uses `CLAUDE_PROJECT_DIR` when Claude Code provides it. Omit model to use Codex's configured default or the plugin's optional configured default model.
+
+## License
+
+MIT

SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+This plugin launches Codex from Claude Code through a local stdio MCP server. The default execution mode is intentionally conservative:
+
+- Codex runs with `--sandbox read-only`.
+- Codex uses non-interactive `approval_policy="never"`.
+- Prompts are sent over stdin instead of command-line arguments.
+- Custom nested subagents are written to a temporary Codex home and cleaned up after the run.
+
+## Reporting A Vulnerability
+
+Please report security issues through GitHub Security Advisories for this repository. If advisories are not available, open an issue with a minimal description and avoid posting secrets, tokens, private logs, or sensitive project contents.
+
+## Handling Secrets
+
+Do not include API keys, OAuth tokens, local auth files, Claude/Codex account output, `.env` files, or machine-specific private paths in issues or pull requests. The test suite uses a fake Codex binary for portable CI coverage.