ccx

Control and monitor native Claude Code and Codex sessions from the CLI, Python or RPC.

You, your agents and your scripts share the same persistent sessions. They run on your own Claude and ChatGPT subscriptions with your existing setup, and you can open any of them live with ccx attach.

npm install -g ccx-native
ccx skills install

▶ Examples · Docs · Unofficial: read Risks and system changes.

Usage

Most work needs five commands, the same for Claude Code and Codex:

ccx new --engine claude "Implement the plan in PLAN.md"   # prints claude:1a2b3c4d-...
ccx wait 1a2b3c4d
ccx report 1a2b3c4d
ccx send 1a2b3c4d "Also update the changelog"
ccx attach 1a2b3c4d

Use --engine codex for a Codex worker. Replace 1a2b3c4d with a unique prefix of at least 8 characters from the id ccx new prints. ccx help lists the other commands.

Features

• Let Codex run Claude Code. Codex starts Claude Code workers, is woken when they finish, reviews their work and sends fixes back. Claude Code can drive Codex workers the same way.
• Runs the official Claude Code and Codex. ccx drives the unmodified claude program through a terminal (PTY), as you would, and codex through its app-server. Workers are signed in as you and run on your Claude or ChatGPT subscription, with no API keys.
• Keep your setup. Your config, CLAUDE.md/AGENTS.md, hooks, skills and MCP servers all apply. Start a worker in any folder, which a subagent can't do.
• Join any session live. ccx attach opens a worker in the engine's own interface while agents keep driving it. ccx import brings in a session you started yourself.
• Find and resume workers. Workers keep their history across turns and restarts, stop when idle and resume on the next message. ccx list finds them; ccx peek shows what one is doing.
• Keep long work going. Steer a running turn, compact a worker's context between steps, and stop work at a usage cap.
• Build on it. A Python API, controllers and a local JSON protocol put workers inside your own tools, dashboards and services.

Examples

Codex drives Claude Code and Codex workers

https://github.com/user-attachments/assets/661f5247-7614-40e8-866b-b8e9742b158b

I asked Codex for a Claude worker to implement a design, then for a Codex worker to check the proxy setup in parallel. Left: the Codex app. Right: its terminal, where I attach to the workers and open the dashboard.

Watch for: 0:33 Claude finishes and Codex wakes up · 1:29 Codex tells Claude about the Codex worker · 1:45 Codex compacts Claude before the next step.

Native Claude Code and Codex, one Python API

https://github.com/user-attachments/assets/849efe10-4f8c-457d-a08e-eea7bf17af17

Right: a web chat built on the ccx Python API. Left: the same Claude Code session, open with ccx attach. Only the chat is used: Claude runs the slow tests in the background and has a Codex worker review its changes.

Controllers

A controller is a Python script that runs a multi-step flow across workers. It can stop at a checkpoint for the owner's decision, then resume without redoing finished steps.

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  participant O as Owner<br/>(you or your agent)
  participant C as Controller
  participant CL as Claude worker
  participant CX as Codex worker
  O->>C: ccx controller run deploy.py --notify-parent
  rect rgba(201, 100, 66, 0.12)
    C->>CL: design template.yaml
    C->>CX: security review
    CX-->>C: findings
    C->>CL: fix the findings
    C->>CL: write the runbook, create the change set
  end
  C-->>O: report: change set ready (wakes the owner)
  Note over C: The controller stops here
  O->>C: ccx controller resume deploy --note "Go"
  Note over C: Finished steps are skipped
  rect rgba(59, 111, 182, 0.12)
    C->>CL: deploy the change set, with the owner's note
    C->>CX: verify the live stack
    C->>CL: write the ops notes
  end
  C-->>O: final report (wakes the owner)

from ccx import WorkerClient, controller, current, task

workers = WorkerClient()

@task
def security_review():                    # a fresh Codex worker returns its findings
    found = {"issues": None}
    workers.create(engine="codex", model="gpt-6.1-sol", cwd=str(current.workspace),
                   prompt=REVIEW_PROMPT, variables=found, wait=True)
    return found["issues"]

# design, fix, prepare, deploy, verify and handover are tasks like this one.

@controller(name="deploy")
def main():
    design()                                      # Claude writes template.yaml
    issues = security_review()
    if issues:
        fix(issues)                               # the same Claude worker fixes them
    change_set = prepare()                        # Claude: runbook + change set
    if not current.inputs:                        # checkpoint: stop until the owner resumes
        return current.report(status="awaiting-approval", checkpoint="deploy",
                              summary="Change set ready. Resume with a note to deploy.",
                              data={"change_set": change_set})
    deploy(change_set, current.inputs[0].comment) # Claude follows the runbook
    verify()                                      # Codex smoke-tests the live stack
    handover()                                    # Claude writes the ops notes
    current.report(status="completed", summary="Deployed, verified and documented.")

Controllers explains resume and has runnable examples.

ccx and the Agent SDK

The Claude Agent SDK runs the Claude Code binary from Python or TypeScript. The program that starts an SDK session drives it while it is live; other processes have no built-in way to inspect or drive that live session. You can resume it later with claude --resume <session-id>.

ccx provides a shared worker lifecycle for Claude Code and Codex:

• Shared, live workers. A worker has a durable id independent of whoever started it. Any agent, shell, Python process or dashboard can inspect, message or steer it, or open it live with ccx attach.
• Every operation is a command. Any agent that can run a shell command can drive workers. Python and RPC interfaces are available too.
• Built-in lifecycle. Send a new message or steer a running turn. Questions and approvals go to whoever is driving. Idle workers stop and revive on the next message. A Codex parent is notified when its Claude worker finishes. The same lifecycle covers Claude Code and Codex.

The SDK and ccx serve different layers and can complement each other in the same workflow.

Install

You need:

• Linux, macOS or WSL2, with Python 3.11 or newer
• Claude Code, Codex or both, installed and signed in

Install ccx with whichever tool you like:

npm install -g ccx-native     # needs Python 3.11+ on your PATH
uv tool install ccx-native
pipx install ccx-native

The package is ccx-native; the command is ccx.

Optionally, teach your agents to use it:

ccx skills install

This adds the ccx skill to Claude Code and Codex (~/.claude/skills, ~/.agents/skills) and keeps it current when you upgrade. Or use skills.sh:

npx skills add ccx-native/ccx -g

Tested with Claude Code 2.1.316 and Codex 0.166 on WSL2, macOS 12 (Intel) and macOS 27 (Apple silicon). If ccx isn't found after installing, see Installing.

Risks and system changes

Docs

Start with Getting started and Concepts. The rest: Permissions · Usage and caps · Codex workers · Controllers · Variables · Troubleshooting · What ccx changes on your machine · Python API · RPC · Architecture. ccx help COMMAND has the details for each command.

Contributing, security, license

Small fixes are welcome as pull requests; for new features, open an issue instead. See CONTRIBUTING.md and SECURITY.md. Released under the MIT License.