ClaudeKit + Codex CLI Guide

Run ClaudeKit workflows in native Codex CLI

Codex CLI is OpenAI's native terminal runtime. Use ck migrate -a codex to install ClaudeKit content into Codex-native locations, then launch through CCS with ccsx, ccsx codex, or ccsxp — all without permanently rewriting your Codex provider config.

First time hearing about CCS?

Codex setup is covered step-by-step below. For deeper context on CCS itself — providers, OAuth accounts, routing, and the dashboard — open the dedicated guide.

Open the CCS guide

How the pieces fit together

Two jobs, no overlap. ck migrate -a codex reads ClaudeKit source from the current working directory and writes Codex-native files to global locations. CCS only launches Codex with the right runtime target and transient provider overrides.

-g scope fix (v4.2.0+): -g now correctly reads SOURCE from global scope. On older versions, SOURCE always read CWD even with -g — if you're pre-4.2.0, cd ~ first.

SOURCE

Source project (./.claude/)

ck migrate discovers source files from the current repo first, then falls back to ~/.claude/* when a source type is missing locally.

MIGRATE

Global Codex CK files

With -g: writes ~/.codex/{agents,hooks} + ~/.agents/skills/ + ~/.codex/AGENTS.md. Commands land as source-command- skills, not ~/.codex/prompts/.
Drop -g for project-local equivalents under .codex/ and .agents/skills/.

ROUTE

CLIProxyAPI :8317

Local HTTP proxy embedded inside CCS Runtime.

ccsx codex → via CCS Runtime, CLIProxy under the hood, no extra config
ccsxp → direct CLIProxy; via CCS set CLIPROXY_API_KEY=ccs-internal-managed, or pass your own key if self-hosting

Skipped in bare native auth mode.

RUNTIME

Codex CLI runtime

The same OpenAI codex binary, but launched by CCS so it inherits provider routing and OAuth config — calling codex directly bypasses CCS. Common entrypoints:

ccsx (native GPT OAuth subscription)
ccsx codex (CCS Runtime + CLIProxy)
ccsxp (direct CLIProxy shortcut)

Setup (per source project) ck migrate -a codex ~/.codex/{prompts,agents,hooks} + ~/.agents/skills

Runtime (per launch) ccsx codex CCS injects -c model_provider="ccs_runtime" :8317/api/provider/codex

Prompts vs Skills in Codex

ck migrate -a codex writes reusable skill directories and may still write compatibility prompt files when commands are discovered. Treat the prompt output as legacy compatibility, not the main Codex workflow surface.

prompt file

No longer written

Used to live at ~/.codex/prompts/*.md. OpenAI deprecated Codex custom prompts, and claudekit-cli followed suit in v4.1.0 — commands now migrate as scoped skills. The legacy prompts path is no longer written.

skill directory

Workflow playbook

Lives in ~/.agents/skills/skill-name/SKILL.md. Skills carry the deeper instructions, references, scripts, and rules Codex can load when the task matches.

In current Codex CLI, $skill-name is what invokes migrated ClaudeKit content — that is the workflow surface. /command-name is reserved for Codex CLI built-ins (e.g. /init, /compact) and does NOT run migrated CK commands.

Project and global Codex agents are independent — they don't merge or override. Keep repo-only definitions in .codex/agents/agent-name.toml and repo-only rules in project AGENTS.md so they travel with the codebase, not with your machine.

Why keep CCS in the loop?

Plain Codex CLI is enough for a single local account. Add CCS when you want Codex plus shared account routing, live quota checks, and one dashboard for the runtime layer.

Quota-aware account routing

For CCS-routed Codex sessions, CLIProxy owns the runtime rotation. CCS gives you the knobs: routing set, pause, resume, and default so exhausted or parked accounts can be skipped.

Live Codex quota visibility

ccs cliproxy quota --provider codex fetches live Codex quota windows across authenticated accounts, including five-hour and weekly usage windows when upstream exposes them.

Central runtime analytics

ccs config opens the dashboard with CLIProxy stats: total requests, success/failure counts, model breakdown, and token totals split into input and output.

One place to manage the bridge

Use the same dashboard to manage providers, OAuth accounts, routing state, analytics, and Codex-compatible runtime settings instead of editing scattered files.

Important: CCS does not magically create more quota. Rotation only helps when you have multiple eligible accounts or projects with independent quota pools — for example, several OpenAI ChatGPT subscription accounts, each with its own Codex usage window. If accounts share the same upstream quota pool, failover will still hit the same limit.

Five-minute setup

Run the machine setup once. Run ck init in each project, then run ck migrate -a codex from the project whose ClaudeKit content you want copied into Codex-native locations. Without -g, writes are project-local (.codex/, .agents/skills/); add -g to write globally (~/.codex/, ~/.agents/skills/).

Version note: this guide tracks claudekit-cli v4.2.0+. Run ck update -y to update.

Step 01 · one-time

Install CCS and ClaudeKit

Already installed? Update with ccs update and ck update -y. CCS handles routing; ClaudeKit ships skills and legacy prompt compatibility files.

shell

verify ccs --version · ck --version
```
$npm install -g @kaitranntt/ccs
$npm install -g claudekit-cli
```
Step 02 · oauth

Authenticate Codex via CCS

Two ways to wire one or more Codex OAuth accounts into CLIProxyAPI. Pick whichever fits your workflow — both end up at the same OAuth flow.
Option A · Dashboard

Add via the CLIProxy dashboard

Open ccs config → click CLIProxy (/cliproxy) → pick Codex → scroll to Accounts → Add. A model picker appears; complete OAuth in the browser.
$ccs config # → CLIProxy → Codex → Accounts → Add
Option B · CLI

Add via one-shot CLI prompt

ccs codex --auth reports how many Codex accounts are already authenticated and prompts to add another. Press y to launch the browser OAuth flow (paste-callback fallback if headless).
$ccs codex --auth # [i] 1 account(s) already authenticated for Codex # [?] Add another account? (y/N): y
Step 03 · verify

Confirm the Codex bridge is healthy

Run ccs doctor and look for the Codex Auth row. Seeing [OK] Authenticated (DD/MM/YYYY) means the bridge is wired up and you can move on. Pipe through grep -i codex to focus on just the Codex rows.

shell

success Codex Auth row reads [OK] Authenticated
```
$ccs doctor 2>&1 | grep -i codex
# Codex Auth │ [OK] │ Authenticated (09/05/2026)
```
Step 04 · migrate

Initialize ClaudeKit, then migrate from that project

ck init plants the ClaudeKit source layout. ck migrate -a codex then copies that content into Codex-native locations.

important
-g scope: fixed in v4.2.0+

Flag

Source (read)

Destination (write)

no flag

CWD has .claude/*

.codex/* — project-local

-g

CWD has .claude/* (upstream bug)

~/.codex/* — global

v4.2.0+: -g correctly reads SOURCE from global scope. Pre-4.2.0: -g only affected destination — run cd ~ first to align SOURCE. Always --dry-run to verify.

shell

init plant .claude/* source layout in CWD
```
$cd your-project
$ck init
```
preview

Prints SOURCE and DESTINATION without touching disk. Confirm SOURCE matches what you want copied.
$ck migrate -a codex --dry-run
apply

Writes Codex-native files for real. Run only after --dry-run looks correct.
$ck migrate -a codex --yes
Step 05 · launch

Launch Codex with ClaudeKit available

Both entrypoints below open Codex through CCS. Pick interactive for $ck:* work; pick exec for one-shot prompts and scripts. Use ccsx codex when you specifically want CCS Runtime quota routing.
interactive

Multi-turn Codex session

Opens a native Codex REPL. Best for $ck:plan, $ck:cook, and $ck:review chains where you continue the same context.
$ccsx codex # alias for: ccs codex --target codex
non-interactive

One-shot via codex exec

Streams a single prompt non-interactively, prints the response, exits. Use for shell pipelines, CI hooks, and quick edits.
$ccsx codex exec 'draft a $ck:plan for the auth refactor'

Launching Codex with CCS

CCS exposes several runtime entrypoints for native Codex CLI. If you omit the prompt text, CCS opens an interactive Codex session — best for multi-turn $ck:* work because you can inspect the plan, refine instructions, and continue in the same Codex context.

Runtime entrypoints, decoded

CCS exposes native Codex target aliases plus one cliproxy shortcut. Pick based on whether you want normal GPT OAuth routing, CCS Runtime quota rotation, or direct CLIProxy.

Command	Routes through	Use when
`ccsx`	Native Codex target with existing GPT/Codex OAuth routing	You want the shortest native Codex launcher and a single GPT/Codex OAuth account is enough.
`ccsx codex`	Built-in Codex profile through CCS Runtime + CLIProxy	Recommended You want quota rotation across multiple GPT accounts and live quota visibility through `ccs cliproxy quota --provider codex`.
`ccsxp`	Direct CLIProxy provider override	You want a thinner path that skips CCS Runtime and talks straight to CLIProxy. Via CCS set `CLIPROXY_API_KEY=ccs-internal-managed`; self-hosting CLIProxy pass your own key into `CLIPROXY_API_KEY`. Pins `CODEX_HOME` to `~/.codex` unless `CCSXP_CODEX_HOME` is set.

Heads-up: these entrypoints inject model_provider, base_url, and env_key via -c at launch — runtime only. The dashboard editor at ccs config → Compatible → Codex CLI shows the persisted user layer, not these overrides.

ccsx

Routes through: Native Codex target with existing GPT/Codex OAuth routing
Use when: You want the shortest native Codex launcher and a single GPT/Codex OAuth account is enough.

ccsx codex

Routes through: Built-in Codex profile through CCS Runtime + CLIProxy
Use when: You want quota rotation across multiple GPT accounts and live quota visibility through ccs cliproxy quota --provider codex.

Recommended

ccsxp

Routes through: Direct CLIProxy provider override
Use when: You want a thinner path that skips CCS Runtime and talks straight to CLIProxy. Via CCS set CLIPROXY_API_KEY=ccs-internal-managed; self-hosting CLIProxy pass your own key into CLIPROXY_API_KEY. Pins CODEX_HOME to ~/.codex unless CCSXP_CODEX_HOME is set.

Full-permission mode (`--yolo`)

The --yolo flag passes --dangerously-bypass-approvals-and-sandbox to the underlying Codex binary. Works at every entrypoint: ccsx --yolo, ccsx codex --yolo, ccsxp --yolo, or directly codex --yolo without CCS. Codex then approves every tool call automatically — file writes, shell commands, package installs — just like Claude Code's --dangerously-skip-permissions.

shell

$ccsx --yolo
$ccsx codex --yolo
$codex --yolo

No guardrails. --yolo disables all confirmation prompts. Codex can delete files, run destructive commands, and install packages without asking. Only use in disposable environments or when you fully trust the prompt scope.

Invoke ClaudeKit workflows with `$...`

After migration, Codex can use the installed CK content. In interactive mode, run one workflow at a time and let Codex continue the same session.

codex repl

>$ck:plan design the billing retry flow
>$ck:cook plans/260509-1231-billing-retry/

Workflows that map cleanly to Codex

These ClaudeKit chains work best after `ck migrate -a codex` has installed the Codex-compatible skills, agents, rules, legacy prompts, and hooks.

Build loop

Plan → Cook → Test

Classic build loop. $ck:plan drafts the design, $ck:cook implements, $ck:test verifies. Codex tends to be fast on the cook step.

$ck:plan $ck:cook $ck:test

shell · ccsx

$ccsx '$ck:plan add OAuth2 PKCE flow'
$ccsx '$ck:cook plans/260509-0807-oauth-pkce/'
$ccsx '$ck:test --coverage'

Triage loop

Fix → Test → Review

$ck:fix triages a failing test or log, then $ck:test re-runs and $ck:review audits the diff before commit.

$ck:fix $ck:test $ck:review

shell · ccsx

$ccsx '$ck:fix flaky billing webhook test'
$ccsx '$ck:test billing/'
$ccsx '$ck:review --staged'

Investigation

Scout → Brainstorm → Plan

$ck:scout discovers files, $ck:brainstorm weighs trade-offs, $ck:plan locks in the approach. Pure investigation, no edits.

$ck:scout $ck:brainstorm $ck:plan

shell · ccsx

$ccsx '$ck:scout where rate-limit logic lives'
$ccsx '$ck:brainstorm sliding window vs token bucket'
$ccsx '$ck:plan adopt token bucket'

Reference

Full command catalog

Every $ck:* command, what it does, and when to reach for it.

Reference

All workflow recipes

Longer chains: ship, debug, retro, and more.

Run ClaudeKit workflows in native Codex CLI

First time hearing about CCS?

How the pieces fit together

Source project (./.claude/)

Global Codex CK files

CLIProxyAPI :8317

Codex CLI runtime

Prompts vs Skills in Codex

No longer written

Workflow playbook

Why keep CCS in the loop?

Quota-aware account routing

Live Codex quota visibility

Central runtime analytics

One place to manage the bridge

Five-minute setup

Install CCS and ClaudeKit

Authenticate Codex via CCS

Add via the CLIProxy dashboard

Add via one-shot CLI prompt

Confirm the Codex bridge is healthy

Initialize ClaudeKit, then migrate from that project

`-g` scope: fixed in v4.2.0+

Launch Codex with ClaudeKit available

Multi-turn Codex session

One-shot via `codex exec`

Launching Codex with CCS

Runtime entrypoints, decoded

Full-permission mode (`--yolo`)

Invoke ClaudeKit workflows with `$...`

Workflows that map cleanly to Codex

Plan → Cook → Test

Fix → Test → Review

Scout → Brainstorm → Plan

Run ClaudeKit workflows in native Codex CLI

First time hearing about CCS?

How the pieces fit together

Source project (./.claude/)

Global Codex CK files

CLIProxyAPI :8317

Codex CLI runtime

Prompts vs Skills in Codex

No longer written

Workflow playbook

Why keep CCS in the loop?

Quota-aware account routing

Live Codex quota visibility

Central runtime analytics

One place to manage the bridge

Five-minute setup

Add via the CLIProxy dashboard

Add via one-shot CLI prompt

-g scope: fixed in v4.2.0+

Multi-turn Codex session

One-shot via codex exec

Launching Codex with CCS

Runtime entrypoints, decoded

Full-permission mode (--yolo)

Invoke ClaudeKit workflows with $...

Workflows that map cleanly to Codex

Plan → Cook → Test

Fix → Test → Review

Scout → Brainstorm → Plan

`-g` scope: fixed in v4.2.0+

One-shot via `codex exec`

Full-permission mode (`--yolo`)

Invoke ClaudeKit workflows with `$...`