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

Without content flags, sync push and sync pull present a guided checklist that describes each scope and shows its default as [Y/n] or [y/N]; pressing Enter accepts the capitalized choice. For project environment or memory, enter each source project root separately, then leave the next source prompt empty to finish the list. For local-source operations such as sync push, Codelux first discovers existing project roots referenced by Claude Code and Codex session history and asks about each suggested project on its own [y/N] line. You can then add paths that were not suggested. The supplemental prompt is Additional source project directory (leave empty to finish), so an empty response ends the list after at least one project has been selected. For sync pull, Codelux first uses a separate read-only SSH command to discover candidates from the remote session history, confirms them locally, and then sends the selected roots back when requesting the archive. If the remote version does not support discovery, Codelux reports that suggestions are unavailable and falls back to manual remote paths. Codelux asks for one target project root per source, so the command may run from any directory and can synchronize multiple projects in one transfer. Run pwd inside a project when you need its absolute path. The current directory is suggested only for the first manual local source and only when it is outside the user home, preventing an accidental whole-home project scan. Unix sockets, FIFOs, and device nodes found inside a valid project tree are ignored because they are not portable files; symbolic links remain rejected.

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. For noninteractive multi-project synchronization, 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

未提供内容范围参数时，sync push 和 sync pull 会显示引导式清单，逐项解释同步范围，并用 [Y/n] 或 [y/N] 标出默认选项；直接回车会接受其中的大写选项。同步项目环境或项目记忆时， 请逐个输入每个源项目根目录，在下一个源目录提示处留空即可结束列表。Codelux 会为每个源项目 分别询问目标项目根目录。对于 sync push 这类源数据位于本机的操作，Codelux 会先从 Claude Code 和 Codex 会话历史中发现仍然存在的项目根目录，在独立的 [y/N] 提示行中逐个询问是否 同步，然后允许继续补充未被建议的目录。补充输入行会明确显示 Additional source project directory (leave empty to finish)；已经选择至少一个项目后，直接 回车即可结束列表。sync pull 会先通过独立的只读 SSH 命令从远端会话历史发现候选目录，在 本机逐项确认后，再在请求正式归档时把所选根目录发回远端。如果远端版本尚不支持候选查询， Codelux 会明确提示候选不可用，并回退到手工输入远端路径。命令可以从任意目录运行，也可以在 一次传输中同步多个项目。需要确认绝对路径时，可以进入相应项目执行 pwd。只有第一个手工 本地源项目、且当前目录不属于用户主目录时，Codelux 才会建议当前目录作为快捷默认值，避免 误扫整个主目录。有效项目树中的 Unix socket、FIFO 和设备节点不属于可移植文件，会被忽略； 符号链接仍会被拒绝。

共享项目白名单包括分层 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