Codex with ZCode CLI

An unofficial Codex plugin that delegates software engineering tasks to the locally installed ZCode CLI with explicit provider and model selection.

This integration invokes ZCode's full coding-agent harness, not a plain chat endpoint. Within the permissions you choose, ZCode can explore repositories, read and edit files, run commands and tests, use skills/plugins/MCP, and continue or resume sessions. Codex remains responsible for reviewing the diff and independently validating the result.

Features

• Discover providers, models, URLs, and credential availability from the ZCode desktop configuration.
• Select a provider/model for each task and maintain a private local preference order.
• Support plan, edit, build, and explicitly authorized yolo modes.
• Support working directories, attachments, denied tools, session resume/continue, and headless targets.
• Keep API keys out of command arguments, logs, and ZCode child-process environments.
• Serialize CLI configuration changes with a global file lock to prevent provider-selection races.
• Never automatically rerun a failed task with another provider after partial repository changes.
• Include a detailed ZCode CLI configuration and troubleshooting reference.

Compatibility

• macOS.
• ZCode installed at /Applications/ZCode.app.
• Tested with ZCode CLI 0.15.2; run a minimal read-only check after upgrading to another version.
• Python 3.
• node available in PATH.
• A ZCode provider configured as anthropic / Anthropic-compatible.

Windows, Linux, custom ZCode installation paths, and OpenAI-compatible providers have not yet been validated end to end. Contributions are welcome.

Prerequisites

1. Install and open the ZCode desktop application.
2. Configure at least one provider in ZCode settings.
3. Confirm that the provider has:
   • an API key;
   • a base URL;
   • at least one model;
   • an Anthropic-compatible protocol.
4. Install a Codex CLI version that supports plugins and marketplaces.

This plugin does not provide accounts, credentials, model access, quotas, subscriptions, or any mechanism for bypassing platform controls.

Install

Add the GitHub marketplace:

codex plugin marketplace add sjduan/codex-w-zcodecli

Install the plugin:

codex plugin add zcode-bridge@codex-w-zcodecli

Start a new Codex task after installation so Codex can load the delegate-to-zcode skill.

Use from Codex

1. Check the environment

Ask Codex:

Use $delegate-to-zcode to check my ZCode CLI, providers, and model configuration.

2. List providers and models

Use $delegate-to-zcode to list the providers and models configured in ZCode without displaying API keys.

3. Configure the default preference order

Use $delegate-to-zcode to set this default order: Provider A / Model X, then Provider B / Model Y, then Provider B / Model Z.

Preferences are stored locally at:

~/.config/zcode-bridge/config.json

This private file is outside the plugin repository and is never uploaded by the plugin.

4. Delegate read-only analysis

Use $delegate-to-zcode to ask ZCode to analyze the authentication flow in this repository with Provider A / Model X in plan mode. Do not modify files. Summarize the findings and independently verify them afterward.

5. Delegate a code change

Use $delegate-to-zcode to ask ZCode to fix this bug with Provider A / Model X in build mode and run the relevant tests. Review the git diff and independently validate the result afterward.

6. Target specific files

Files inside the workspace can be named directly in the prompt:

Ask ZCode to read src/parser.ts and its adjacent tests, then fix the empty-input behavior.

Files outside the workspace should be attached:

Attach /absolute/path/spec.md to ZCode and ask it to update the current repository to match the specification.

7. Continue a session

Use $delegate-to-zcode to continue the latest ZCode session for this repository and fix the remaining failing tests.

You can also provide a sess_... session ID to resume a specific session.

Permission modes

Mode	Intended use
plan	Read, analyze, and design a solution without intended file writes
edit	Make focused file edits
build	Implement changes, run commands, and execute tests; recommended for normal development tasks
yolo	Broadest permissions; use only with explicit user authorization

The bridge does not rely on the native default mode for zcode --prompt, because that default may be broader than intended. Codex should always choose a mode explicitly.

Use the bridge script directly

You can also run the bridge without Codex:

git clone https://github.com/sjduan/codex-w-zcodecli.git
cd codex-w-zcodecli

BRIDGE="plugins/zcode-bridge/skills/delegate-to-zcode/scripts/zcode_bridge.py"

Check the environment:

python3 "$BRIDGE" doctor

List providers and models without displaying API keys:

python3 "$BRIDGE" providers --json

Set a private preference order:

python3 "$BRIDGE" configure \
  --prefer "Provider A" "Model X" \
  --prefer "Provider B" "Model Y"

Preview provider resolution without calling a model:

python3 "$BRIDGE" run \
  --provider "Provider A" \
  --model "Model X" \
  --cwd /absolute/path/to/repo \
  --mode plan \
  --prompt "Analyze this repository" \
  --dry-run

Run a complete development task:

python3 "$BRIDGE" run \
  --provider "Provider A" \
  --model "Model X" \
  --cwd /absolute/path/to/repo \
  --mode build \
  --prompt "Implement the requested change and run focused tests" \
  --print-selection \
  --no-color

View all bridge options:

python3 "$BRIDGE" --help
python3 "$BRIDGE" run --help

Security model

The ZCode desktop application and CLI use different configuration locations:

Desktop: ~/.zcode/v2/config.json
CLI:     ~/.zcode/cli/config.json

The bridge performs the following sequence:

1. Read provider metadata from the desktop configuration.
2. Synchronize only the selected provider into the CLI configuration.
3. Write the CLI configuration atomically with mode 0600.
4. Keep API keys out of argv, stdout/stderr, and ZCode child-process environments.
5. Hold a configuration lock for the lifetime of the ZCode process.
6. Require Codex to inspect git status, the diff, and relevant tests after delegation.

To make a desktop provider available to the CLI, the bridge copies its API key into the local ~/.zcode/cli/config.json. The file is set to mode 0600, but users remain responsible for protecting their account, device, disk, and backups.

Before the first synchronization, the bridge preserves:

~/.zcode/cli/config.json.pre-zcode-bridge.bak

The plugin source and public repository contain no real API keys, private provider UUIDs, custom service URLs, or user-specific absolute paths.

Update

Refresh the marketplace:

codex plugin marketplace upgrade codex-w-zcodecli

Reinstall the latest plugin version:

codex plugin add zcode-bridge@codex-w-zcodecli

Then start a new Codex task to load the updated skill.

Troubleshooting

Model config is missing

Do not call native zcode --prompt directly. Run through the bridge so it can synchronize the provider and model configuration.

missing API key or missing baseURL

The selected desktop provider is incomplete or changed after the previous synchronization. Run:

python3 "$BRIDGE" providers --json
python3 "$BRIDGE" doctor

HTTP 401 / 403

Check the API key, model entitlement, and provider service status.

HTTP 429 / provider code 1308

The account reached a rate or usage limit. Respect the reset time in the error and do not attempt to bypass platform restrictions.

Turn execution failed

Add --verbose only while diagnosing the failure to reveal the cause, HTTP status, provider code, and trace ID.

ZCode failed after modifying files

Do not automatically switch providers and rerun the task. Inspect the current diff and tests first, then decide whether to continue the same session, repair the partial change, or begin a new task.

See ZCODE_CLI.md for the complete CLI reference.

Disclaimer and use restrictions

This project is an unofficial interoperability tool. It is not affiliated with, authorized by, endorsed by, or sponsored by OpenAI, Codex, Z.AI, ZCode, or Zhipu AI.

Users must comply with every applicable current agreement, policy, and technical restriction, including:

• OpenAI Terms of Use
• Z.AI Terms
• all applicable API, model, subscription, Coding Plan, rate-limit, quota, automation-access, and content policies

This plugin does not provide, imply, or grant any right to unlimited platform usage, quota/rate-limit/payment/access-control bypass, credential sharing, or credential abuse. Do not use it to evade platform restrictions, make unauthorized bulk calls, or engage in conduct that violates applicable agreements or laws.

This project is intended only for personal learning, research, evaluation, and non-commercial development workflows. Without explicit written permission from the applicable platforms and project rights holders, do not use it for resale, paid hosted services, commercial SaaS offerings, invocation-as-a-service, revenue-generating bulk automation, or other direct commercial purposes.

Users are solely responsible for their prompts, code, data, credentials, model charges, tool calls, file modifications, generated content, and final use of any result. Do not upload source code, secrets, personal data, or protected material to a third-party provider unless you are authorized to process it there.

This project is provided "as is," without express or implied warranties. The authors are not liable for data loss, code damage, account restrictions, charges, service outages, compliance issues, or other direct or indirect losses. This section is not legal advice. Consult qualified counsel when necessary and always defer to the latest official platform terms.