Claude Executor

claude-executor is a Codex skill and local stdio MCP server that delegates a bounded implementation task to the installed Claude Code CLI. Codex keeps ownership of planning, review, and the final decision; Claude performs the scoped file edits and optional mechanical checks.

The executor is deliberately local. It does not add an HTTP listener, npm runtime dependency, scheduler, or network fetcher. It uses Claude Code's native authentication and starts the native claude executable directly.

Requirements

• Node.js 18 or newer

• Claude Code with --safe-mode and --permission-prompts support

• A working Claude Code authentication on the local machine

The implementation has been exercised with Claude Code 2.1.296 and Node.js 22. The Windows path uses claude.exe; POSIX systems use claude.

Related MCP server: Codex to OpenCode MCP Server

Contents

• SKILL.md: Codex skill instructions and operating boundaries

• agents/openai.yaml: Codex skill metadata and MCP dependency declaration

• scripts/mcp-server.mjs: stdio MCP server exposing claude_execute

• scripts/run-task.mjs: one-call execution with bounded acceptance checks and automatic rework

• scripts/delegate.mjs: standalone CLI and Claude subprocess wrapper

• scripts/*.test.mjs: deterministic subprocess and MCP behavior tests

Install as a Codex skill

Clone or copy this directory into the Codex skills directory as claude-executor:

<CODEX_HOME>/skills/claude-executor/

Restart or reload the Codex MCP configuration after installation so the claude_executor server is available. The current skill expects the MCP tool named claude_execute; it does not silently fall back to a polling workflow.

Run the tests

No package installation is needed:

npm test

The equivalent direct command is:

node --test scripts/delegate.test.mjs scripts/mcp.test.mjs

Standalone CLI

The CLI accepts a UTF-8 task brief and writes an exclusive artifact directory containing the execution result and stream log:

node scripts/delegate.mjs \
  --cwd /absolute/path/to/project \
  --brief /absolute/path/to/brief.md \
  --model opus

On Windows PowerShell:

node .\scripts\delegate.mjs `
  --cwd 'C:\path\to\project' `
  --brief 'C:\path\to\brief.md' `
  --model opus

Use --read-only for a planning-only run. Shell checks, writes, commits, pushes, MCP tools, and agent delegation are blocked by the wrapper. If checks are granted, pass each one as an explicit native executable and argument list; shell command strings are not interpreted.

MCP configuration

The MCP server is a stdio process. A host configuration can point at the checked-out script:

{
  "mcpServers": {
    "claude_executor": {
      "command": "node",
      "args": ["/absolute/path/to/claude-executor/scripts/mcp-server.mjs"]
    }
  }
}

Call claude_execute once for an implementation or rework batch and keep that request pending until it returns. Supply an absolute cwd, a self-contained task, and explicit acceptance checks when needed. The server serializes executions and rejects a duplicate active call.

Safety and scope

The wrapper passes --safe-mode, disables slash commands, uses an empty strict MCP configuration, and denies commits, pushes, listeners, clipboard changes, and delegation. Acceptance commands are started without a shell and are bounded by the total timeout. Diagnostics are treated as data and are not executed as instructions.

This project is an orchestration wrapper, not a replacement for semantic review. A successful execution or passing mechanical check does not by itself certify the implementation.

License

Apache License 2.0. See LICENSE.