Codelux

English | 简体中文

Codelux is a focused command-line provider manager for Claude Code and OpenAI Codex. It is a simpler, terminal-first alternative in the same problem space as cc-switch: register compatible Provider endpoints once, inspect their health, and switch clients explicitly without hand-editing JSON or TOML files.

Website and Provider API: https://codelux.io

Codelux and cc-switch

cc-switch is a broad, cross-platform desktop manager for many AI clients. Codelux takes a narrower approach for users who prefer a small command-line tool:

• Terminal-first: works directly in shell workflows and on headless machines.
• Focused scope: currently manages Claude Code and Codex rather than a large desktop client catalog.
• Explicit changes: add, switch, update, and remove are deliberate commands with clear client selection.
• Conservative safety: configuration states are inspected before changes; unknown, conflicting, or incomplete states fail closed.
• Recoverable local changes: snapshots and private file writes help preserve the previous configuration before switching.
• Open API compatibility: use any Provider that exposes a compatible Claude or OpenAI/Codex API, including codelux.io.

Codelux is not a replacement for every cc-switch feature. Choose cc-switch for a broad graphical manager; choose Codelux when a compact, auditable CLI is the better fit.

Features

• Provider management for Claude Code and Codex
• Read-only configuration and health inspection
• Explicit switching between official and custom Providers
• Snapshot-backed restoration of official configurations
• Fail-closed handling for unknown or incomplete local state
• Encrypted offline archives and OpenSSH-based synchronization
• Explicit conflict handling for synchronized configuration and session data

Security model

Codelux stores Provider credentials in local files protected by operating-system file permissions. These files are not encrypted at rest and cannot protect against processes running as the same user, privileged administrators, malware, compromised accounts, backups, or physical disk access.

Cross-machine archives are encrypted with a user-provided password. Active client configuration is not applied on another machine unless you explicitly request it.

See SECURITY.md for vulnerability reporting and security boundaries.

Installation

Install the latest published release from PyPI:

python3 -m pip install --upgrade codelux

Check the installed version:

codelux --version

Install Claude Code and Codex separately through their official distribution channels before managing them with Codelux.

Usage

Show all available commands:

codelux --help

Show the installed Codelux version:

codelux version

Inspect the detected Claude Code configuration and process state:

codelux status --client claude

List registered Providers without displaying credentials:

codelux list

Register a Provider and activate it for Claude Code. Codelux prompts for the API key without echoing it:

codelux add codelux-io --url https://codelux.io --client claude

Activate an already registered Provider for Codex:

codelux switch codelux-io --client codex

Return Claude Code to its official configuration or login flow:

codelux switch official --client claude

Replace the URL or credential for an existing Provider binding:

codelux update codelux-io --client claude

Remove a Provider binding after Codelux checks whether it is still in use:

codelux remove codelux-io --client claude

Synchronize selected Provider state to another machine over SSH:

codelux sync push --ssh user@host.example --providers

Synchronize selected Provider state from another machine over SSH:

codelux sync pull --ssh user@host.example --providers

When synchronizing Claude Code or Codex session history, enter the real absolute project directory on the target machine. The most reliable method on macOS and Linux is to run pwd inside that project and paste its output. Do not enter Claude Code's internal storage key, such as -Users-user-work-project; Codelux generates that key automatically. Local pull targets and remote push targets must already exist and be directories. A client that is not selected for session synchronization does not need to be stopped.

Use --help on any command to inspect its current options and safety prompts.

Supported environments

• macOS 12 or later, Intel or Apple Silicon
• Linux distributions with Python 3.9–3.12
• Claude Code and Codex installed and available on PATH
• A writable user home directory for client configuration and Codelux state

Windows is not currently a supported runtime target. Codelux is alpha software; verify the exact Claude Code/Codex versions and Provider API compatibility in your environment before production use.

License

MIT

Codelux

English | 简体中文

Codelux 是一个面向 Claude Code 和 OpenAI Codex 的命令行 Provider 管理工具。它与 cc-switch 解决同一类问题，但采用更简洁、终端优先的实现：Provider 只需注册一次，即可检查健康状态并明确切换，无需手工编辑 JSON 或 TOML 配置文件。

官网与 Provider API： https://codelux.io

Codelux 与 cc-switch

cc-switch 是面向多种 AI 客户端的跨平台桌面管理工具。Codelux 则专注于喜欢轻量命令行工具的用户：

• 终端优先： 适合 Shell 工作流、远程服务器和无桌面环境。
• 聚焦核心场景： 当前管理 Claude Code 和 Codex，而不是覆盖大量桌面客户端。
• 变更明确： add、switch、update、remove 都是需要明确指定客户端的操作。
• 保守安全： 修改前先检查配置状态；未知、冲突或不完整状态默认拒绝修改。
• 本地变更可恢复： 切换前创建快照，并使用私有文件写入保护原配置。
• 兼容公开 API： 可使用任何兼容 Claude 或 OpenAI/Codex API 的 Provider，包括 codelux.io。

Codelux 并不试图覆盖 cc-switch 的全部功能：需要广泛图形化管理时可以选择 cc-switch；需要紧凑、可审计的命令行工具时，可以选择 Codelux。

主要能力

• 管理 Claude Code 和 Codex 的 Provider
• 只读检查配置与进程健康状态
• 在官方配置和自定义 Provider 之间明确切换
• 通过快照恢复官方配置
• 对未知或不完整本地状态执行失败关闭
• 加密离线归档和基于 OpenSSH 的同步
• 对同步配置和会话数据执行明确的冲突处理

安全模型

Codelux 将 Provider 凭据保存在受操作系统文件权限保护的本地文件中。这些文件未进行静态加密，无法防御以同一用户身份运行的进程、特权管理员、恶意软件、账号失陷、备份泄露或物理磁盘访问。

跨机器归档使用用户提供的密码加密。除非你明确要求，否则不会在另一台机器上应用活动客户端配置。

漏洞报告方式和详细安全边界见 SECURITY.zh-CN.md。

安装

从 PyPI 安装最新正式发布版本：

python3 -m pip install --upgrade codelux

查看已安装版本：

codelux --version

请先通过官方渠道单独安装 Claude Code 和 Codex，再使用 Codelux 管理它们。

使用方法

查看全部命令：

codelux --help

查看 Codelux 版本：

codelux version

检查 Claude Code 当前配置和进程状态：

codelux status --client claude

列出已注册的 Provider，不显示凭据：

codelux list

注册 Provider 并为 Claude Code 激活。输入 API key 时不会回显：

codelux add codelux-io --url https://codelux.io --client claude

为 Codex 激活已经注册的 Provider：

codelux switch codelux-io --client codex

将 Claude Code 恢复到官方配置或官方登录流程：

codelux switch official --client claude

替换已有 Provider 绑定的 URL 或凭据：

codelux update codelux-io --client claude

在 Codelux 检查 Provider 是否仍被使用后，删除绑定：

codelux remove codelux-io --client claude

通过 SSH 将选定的 Provider 状态同步到另一台机器：

codelux sync push --ssh user@host.example --providers

通过 SSH 从另一台机器同步选定的 Provider 状态：

codelux sync pull --ssh user@host.example --providers

同步 Claude Code 或 Codex 会话历史时，请输入目标机器上的真实绝对项目目录。在 macOS 和 Linux 上，最可靠的方式是在目标项目中运行 pwd 并粘贴输出。不要输入 -Users-user-work-project 这类 Claude Code 内部存储键；Codelux 会自动生成该键。本地 pull 目标和远端 push 目标都必须已经存在且是目录。未选择同步会话的客户端不需要停止。

可以对任意命令使用 --help 查看当前选项和安全提示。

当前支持的系统环境

• macOS 12 或更高版本，支持 Intel 和 Apple Silicon
• 安装 Python 3.9–3.12 的 Linux 发行版
• Claude Code 和 Codex 已安装，并且命令位于 PATH
• 可写的用户主目录，用于客户端配置和 Codelux 状态文件

当前暂不支持 Windows 作为运行环境。Codelux 仍处于 Alpha 阶段，正式使用前请在目标环境验证具体的 Claude Code/Codex 版本和 Provider API 兼容性。

许可证

MIT