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
• Selective synchronization of Claude Code and Codex project/user environments and project memory

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.

Synchronize a project's portable agent environment together with local overrides, user-level agent configuration, and Claude project memory:

codelux sync push --ssh user@host.example \
  --project-env --local-project-env --user-env --memory \
  --project-map /work/my-project=/srv/my-project

The shared project allowlist includes hierarchical AGENTS.md, AGENTS.override.md, CLAUDE.md, project-contained Claude imports, .mcp.json, selected Claude settings/rules/skills/agents/commands, and selected Codex configuration/rules/hooks. Local-only files such as CLAUDE.local.md and .claude/settings.local.json require --local-project-env. With multiple projects, repeat --project-map SOURCE=TARGET; mappings are explicit and never depend on option order. Offline imports expose only opaque project IDs and use --target-project PROJECT_ID=TARGET.

Authentication databases, OAuth/account state, Provider routing, Codex trust, and user-level Codex MCP server tables are excluded. Secret-shaped JSON fields are removed, and an MCP command argument array is cleared in full when it contains a credential flag or recognized token prefix; reconfigure that command on the target. Free-form instructions and commands can still contain private material, so review selected files and use an encrypted export or a trusted SSH peer.

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

AI collaborative development

Codelux is developed through human-guided collaboration between developers and AI coding agents. Implementation, review, and governance are assigned by task: substantial changes are independently reviewed where practical, claims are backed by reproducible tests and checks, and human maintainers retain final responsibility for project direction, security boundaries, merges, and releases.

Developers and AI agents are welcome to join the project. Contributions can begin with an issue, review, test, documentation improvement, or focused pull request. Please make the intended scope, validation evidence, and any security or privacy assumptions clear so that both human and AI collaborators can evaluate the change reliably.

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 的同步
• 对同步配置和会话数据执行明确的冲突处理
• 按需同步 Claude Code 和 Codex 的项目/用户环境及项目记忆

安全模型

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 目标都必须已经存在且是目录。未选择同步会话的客户端不需要停止。

同步项目的可移植 Agent 环境、本地覆盖、用户级 Agent 配置和 Claude 项目记忆：

codelux sync push --ssh user@host.example \
  --project-env --local-project-env --user-env --memory \
  --project-map /work/my-project=/srv/my-project

共享项目白名单包括分层 AGENTS.md、AGENTS.override.md、CLAUDE.md、项目内 Claude 导入文件、.mcp.json、选定的 Claude settings/rules/skills/agents/commands，以及选定的 Codex 配置/rules/hooks。CLAUDE.local.md、.claude/settings.local.json 等仅本地文件必须 显式使用 --local-project-env。同步多个项目时，重复提供 --project-map SOURCE=TARGET； 映射是显式的，不依赖参数顺序。离线导入只暴露不透明项目 ID，并使用 --target-project PROJECT_ID=TARGET 指定目标。

认证数据库、OAuth/账号状态、Provider 路由、Codex trust 和用户级 Codex MCP server 表 不会同步。JSON 中疑似秘密的字段会被移除；如果 MCP command 参数数组包含凭据参数名或 已识别的令牌前缀，整个参数数组都会被清空，需要在目标机器重新配置该命令。自由格式的 指令和命令仍可能包含私密内容，因此传输前应审查所选文件，并使用加密导出或可信 SSH 对端。

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

AI 协同开发

Codelux 采用人类引导的开发者与 AI 编码 Agent 协同开发模式。实现、复审和治理角色按任务 分配：重要变更会在条件允许时进行独立复审，各项结论需要可复现的测试与检查作为证据， 项目方向、安全边界、合并和发布的最终责任仍由人类维护者承担。

我们欢迎更多开发者和 AI Agent 加入项目。你可以从 Issue、代码复审、测试、文档改进或 范围明确的 Pull Request 开始参与。提交贡献时，请清楚说明目标范围、验证证据，以及相关的 安全或隐私假设，帮助人类与 AI 协作者可靠地评估变更。

当前支持的系统环境

• 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