codexctl

codexctl is a native, single-binary control plane for Codex CLI. It manages normal Codex TOML files and SQLite logs, and it can run multiple isolated Claude-compatible endpoints through an embedded OpenAI Responses bridge. No separate bridge executable, Node.js, Python, systemd, or Docker service is required.

Build from source

The repository is self-contained: the embedded bridge source lives in crates/codex-claude-bridge/ and is linked into the codexctl binary.

git clone https://github.com/ztm983620369/codexctl.git
cd codexctl
cargo test --workspace --all-targets
cargo build --release -p codexctl
./target/release/codexctl --version

Source layout:

• src/: native control-plane CLI
• crates/codex-claude-bridge/: embedded Anthropic Messages to OpenAI Responses bridge
• tests/: CLI and lifecycle regression tests
• scripts/build-termux.sh: Android AArch64/Termux package builder
• docs/CLI_GUIDE.md: complete operational guide

Claude quick start

Run the all-CLI wizard. It asks for the name, URL, model, hidden credential, and whether to start immediately:

codexctl claude add

No environment export or manual JSON/TOML editing is required. After the wizard, run codexctl claude status and codexctl claude run NAME.

Run a non-interactive Codex request through the selected Claude endpoint:

codexctl claude run ugf -- exec "Explain this repository"

The credential is copied once into the endpoint's mode-0600 auth.json; it is not stored in the transparent registry, audit log, process arguments, or bridge environment. The registry stores only a SHA-256 fingerprint. Each endpoint has its own URL, model, credential, loopback port, Codex home, PID, and log.

Add and switch between more endpoints by repeating the same CLI workflow:

codexctl claude add main \
  --url https://gateway.example.com \
  --model claude-opus-4-8 \
  --auth-mode auto \
  --beta-mode claude-code \
  --key-prompt \
  --start

codexctl claude add backup \
  --url https://backup.example.com \
  --model claude-sonnet-4-5 \
  --key-prompt \
  --start

codexctl claude list
codexctl claude use backup
codexctl claude start --all
codexctl claude stop --all

Change runtime settings or rotate a credential:

codexctl claude set ugf --url https://new.example.com --model claude-opus-4-8
codexctl claude key ugf
codexctl claude restart ugf

Protocol behavior is configurable per endpoint and visible in claude show: --auth-mode auto follows Claude Code semantics (sk-ant-* uses x-api-key, gateway tokens use Bearer), --beta-mode claude-code selects only source-aligned betas required by the emitted request, repeated --beta values add gateway-specific capabilities, and --prompt-cache true|false controls Codex-to-Anthropic cache mapping. Use --beta-mode off --prompt-cache false for minimal proxies.

Runtime changes restart an already-running endpoint automatically. Pass --no-restart to stage them; claude status then reports restart-required. Credential-only rotation does not restart the bridge. Plaintext --key TOKEN arguments are intentionally unsupported; humans use hidden --key-prompt, while agents use --key-stdin.

The complete Chinese guide is embedded in the installed binary. AI agents also get a stable machine-readable capability contract:

codexctl guide
codexctl claude guide
codexctl schema
codexctl --json claude status

Useful operational commands:

codexctl claude show ugf
codexctl claude endpoint ugf
codexctl claude test ugf --local-only
codexctl claude test ugf
codexctl claude logs ugf -n 100
codexctl claude logs ugf --follow
codexctl claude audit --name ugf -n 100
codexctl --json claude status
codexctl --json claude endpoint ugf

Destructive removal supports a no-change preview and requires confirmation outside an interactive terminal:

codexctl claude remove ugf --dry-run
codexctl claude remove ugf --yes

Every permanent mutation follows the same transaction:

1. Parse the requested TOML value and candidate document.
2. Ask the installed Codex binary to load the candidate.
3. Acquire an exclusive mutation lock.
4. Refuse the write if the source changed concurrently.
5. Create a mode-0600 backup.
6. Atomically replace the target file in the same directory.
7. Append a secret-redacted JSONL audit event (append-only by this tool).

Quick reference

codexctl status --verbose
codexctl use gpt-5.6-sol
codexctl url
codexctl url https://new.example.com --dry-run
codexctl get model_reasoning_effort
codexctl set model_reasoning_effort max
codexctl log -n 50

codexctl config show --raw
codexctl config get model_reasoning_effort
codexctl param set model_reasoning_effort max
codexctl param set 'features.goals' true --dry-run

codexctl provider list
codexctl provider add lab --url https://api.example.com --wire-api responses
codexctl provider set-url https://new.example.com --provider lab --dry-run
codexctl provider use lab

codexctl model list --catalog
codexctl model add fast --id gpt-5.6-sol --provider OpenAI --reasoning low
codexctl model run fast -- exec --skip-git-repo-check 'Explain this repository'
codexctl model use fast

codexctl logs tail -n 50
codexctl logs errors --since 6h
codexctl logs search 'stream disconnected' --since 7d
codexctl logs stats --since 24h

codexctl backup create --label before-experiment
codexctl backup list
codexctl backup diff BACKUP_ID
codexctl backup restore BACKUP_ID --dry-run

codexctl doctor --strict
codexctl doctor --full --network
codexctl test --profile fast
codexctl run --profile fast -- --search

--json is global and makes operational commands machine-readable. Config and log output always redacts likely credentials. Managed Claude credentials are only read when explicitly adding or rotating an endpoint.

Paths

• Main config: $CODEX_HOME/config.toml
• Native profiles: $CODEX_HOME/<name>.config.toml
• Logs: $CODEX_HOME/logs_2.sqlite
• Backups: $CODEX_HOME/backups/codexctl/
• Audit: $CODEX_HOME/codexctl/audit.jsonl
• Lock: $CODEX_HOME/codexctl/mutation.lock
• Claude registry: $CODEXCTL_HOME/claude/registry.json
• Claude audit: $CODEXCTL_HOME/claude/audit.jsonl
• Per-endpoint Codex home: $CODEXCTL_HOME/claude/instances/NAME/codex/
• Per-endpoint PID and log: $CODEXCTL_HOME/claude/instances/NAME/state/

The default CODEX_HOME is ~/.codex. CODEXCTL_HOME defaults to $XDG_DATA_HOME/codexctl, or ~/.local/share/codexctl when XDG_DATA_HOME is unset.

Termux native build

The verified Termux target is Android AArch64/Bionic with a minimum API level of 24. Build the single native binary, Debian package, portable archive, completion, manifest, and checksums with:

./scripts/build-termux.sh

Artifacts are written to dist/termux/aarch64/. Override discovery with ANDROID_NDK_HOME, or the minimum API with TERMUX_MIN_API.