Claude → Codex

Moving from Claude Code to Codex should not mean giving up the workflows you already rely on. This is the migration hub for translating those workflows to Codex-native tools, beginning with dynamic workflows.

Dynamic workflows

A dynamic workflow is a small JavaScript program that coordinates agents at runtime. JavaScript owns predictable control flow—fan-out, fan-in, loops, branches, and aggregation—while agents own reasoning and tool use.

Claude Code provides this pattern through its dynamic workflows. The dynamic-workflow plugin in this repository provides equivalent orchestration for Codex through an installable skill and a durable JavaScript runtime.

What carries over

You can still create and run dynamic workflows that coordinate multiple agents and adapt as the work progresses.

What changes

Claude Code’s interactive /workflows command does not carry over to Codex.

Install in Codex

Plugin installation needs no Python or npm

The plugin already contains the skill and a compiled JavaScript runner. It does not require the repository’s Python package or an npm install step. Node.js 20 or newer must merely be available to execute the bundled runner. The optional Python helper described below only simplifies completion callbacks.

1. Add this repository as a Codex marketplace

   Codex accepts GitHub owner/repo marketplace sources:

   codex plugin marketplace add pchalasani/claude-code-tools

2. Install the dynamic workflow plugin

   codex plugin add dynamic-workflow@cctools-codex-plugins

   This is the complete installation. There is no separate Python package, skill-installation step, MCP server, API key, or npm package to configure.

3. Start a new Codex thread

   A new thread ensures Codex discovers the newly installed skill.

Run your first workflow

Mention the skill explicitly when you want guaranteed activation:

$dynamic-workflow Create a read-only workflow that discovers every API route,
audits at most 30 routes with four workers, and synthesizes the findings.
Show me the workflow and its agent cap before launching it.

Codex can also select the skill implicitly when you casually ask for a dynamic workflow, but the $dynamic-workflow mention removes any ambiguity.

The skill will:

• create a reviewable JavaScript workflow under .codex/workflows/
• validate it before execution
• explain its worker count, concurrency, permissions, and likely cost
• ask before launching newly generated workflow code
• preserve completed steps so a failed or paused run can resume
• enforce reviewed agent, runtime, fan-out, prompt, and result limits
• terminate runaway workflow JavaScript and worker process trees

Keep chatting and receive completion

The same day-to-day behavior

Start the workflow, continue chatting in the main session, and let that same session notify you when the background work finishes. This matches the interaction pattern of Claude Code dynamic workflows without holding the conversation open on a wait command.

Outside a callback-ready session, a detached workflow is durable but the current Codex turn must poll or wait to learn that it finished. Passive supervision makes no model calls, but it cannot wake an idle thread. For the Claude-style behavior where you keep chatting and the original thread speaks up later, launch Codex through its shared app server.

Install the optional one-command helper:

uv tool install claude-code-tools

If the package is already installed, refresh it with uv tool install --force claude-code-tools. Then start Codex normally through the helper:

codex-dynamic

To continue the most recent conversation instead of starting a new one:

codex-dynamic resume --last

Plugin updates do not require a restart

After installing or upgrading the plugin, run codex-dynamic normally. It starts a fresh server generation while existing sessions and callbacks keep using their original generation. Forced lifecycle commands are needed only for explicit cleanup, and they disconnect every retained session.

Omit --last to use Codex’s session picker. codex-dynamic quietly starts or reuses the local app server, then hands the terminal directly to Codex. The server remains available after the TUI exits. Passive server supervision makes no model calls. Callbacks require Codex CLI 0.136.0 or newer; it is the first compatible CLI release for this callback protocol. The helper rejects older versions before starting the server or TUI. Callback preflight also validates the connected App Server before creating a workflow.

The Python package is only a convenience for this callback setup. Without it, use Codex’s manual two-terminal form:

# Terminal 1
codex app-server --listen unix://

# Terminal 2
codex --remote unix://

An already-running local TUI cannot reconnect itself in place; exit it first, then resume it with codex-dynamic as shown above.

Now the request is simple:

$dynamic-workflow Run the approved workflow in the background. Let me keep
using this thread, and notify me here when it finishes.

The skill requests command-scoped approval for the exact trusted supervisor command. Every workflow run or resume needs this narrow host execution so durable state and headless workers do not inherit the outer tool sandbox. The same approval lets a callback notifier reach the host Unix socket. Workflow JavaScript stays in the restricted VM, and each worker retains its declared sandbox. If the thread is idle at completion, Codex starts a result-reporting turn. If a conversation turn is active, it steers the result into and extends that turn. You do not copy a thread ID, install MCP, run npm, or configure another API key.

codex-dynamic makes callbacks the code-level default for detached workflow runs, so a forgotten --notify-current-thread flag does not silently lose the notification. The user can opt out with --no-notify-current-thread.

The no-monitor behavior begins only when the launch response reports an armed callback. At that point the skill reports the run ID and ends the launch turn; it must not start a wait process, poll status, or create a background watcher. Without an armed callback, the normal bounded monitoring behavior still applies.

Codex does not currently display a persistent background-workflow card, spinner, or running-status message in the conversation. After an armed launch, the chat simply looks normal until completion arrives. You can ask Codex for an explicit status check, but the absence of an indicator is not a reason for the agent to monitor automatically.

Monitor running workflows

The Python package also installs codex-workflows. Run it from any directory to see active workflows across all projects:

codex-workflows
codex-workflows watch
codex-workflows show RUN_ID

The default view shows active runs and the project that launched each one. watch refreshes the display, while show expands one run’s steps, callback, errors, and complete working directory. See the codex-workflows command reference for filters, status meanings, JSON output, and the observational safety model.

Use codex-server status or codex-server logs for nondisruptive inspection. Stopping or restarting requires --force and must be done only after exiting all connected TUIs. See the codex-dynamic tool reference for lifecycle and safety details.

Passive supervision and the local app server add no model calls. Completion reporting starts a new turn only while the thread is idle; otherwise it extends the active turn. Either reporting path invokes the model and consumes tokens. Callback delivery has a 24-hour retry deadline, at most five submissions, and separate status, so an app-server outage does not turn a successful workflow into a failed one.

Codex app-server status

Codex currently labels the app-server and remote TUI interfaces as experimental. The plugin uses their documented unix:// transport, but their CLI and protocol surfaces may evolve. See the official Codex app-server documentation.

Port an existing workflow

Point the skill at the existing script and ask it to port and review it:

$dynamic-workflow Port .claude/workflows/audit-routes.js to Codex. Preserve its
fan-out and structured results, add explicit bounds, and do not launch it yet.

The script-body format is intentionally familiar, but this is not a universal drop-in compatibility layer. Imported modules and direct Node.js filesystem or shell access are unavailable inside workflow code; delegate that work to Codex agents instead.

Review before launch

Generated workflow JavaScript is a capability boundary, not a hardened hostile-code sandbox. Review the script, agent cap, deadline, context-heavy fan-in, and requested write permissions before approving execution.

Durable controls and reference

Runs support status inspection, logs, pause, resume, and cancellation. The skill handles those commands for ordinary use, while the Dynamic Workflow plugin reference documents the JavaScript API, direct CLI, cache model, and safety boundaries.

This migration hub will grow to cover project instructions, skills and command surfaces, and session-continuity strategies as more Codex equivalents are added to the repository.