Metadata-Version: 2.4
Name: codelux
Version: 0.1.0a4
Summary: Unified Provider management CLI for AI coding assistants
License: MIT
License-File: LICENSE
Keywords: ai,llm,provider,claude,codex
Author: Codelux AI Initiative
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: click (>=8.1.0,<9.0.0)
Requires-Dist: cryptography (>=41,<47)
Project-URL: Homepage, https://github.com/codelux-io/codelux
Project-URL: Repository, https://github.com/codelux-io/codelux
Description-Content-Type: text/markdown

# Codelux

[English](README.md) | [简体中文](README.zh-CN.md)

Codelux is a focused command-line provider manager for [Claude Code](https://www.anthropic.com/claude-code) and [OpenAI Codex](https://github.com/openai/codex). It is a simpler, terminal-first alternative in the same problem space as [cc-switch](https://github.com/farion1231/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](https://codelux.io)

## Codelux and cc-switch

[cc-switch](https://github.com/farion1231/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](https://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](SECURITY.md) for vulnerability reporting and security boundaries.

## Installation

Install the latest published release from PyPI:

```bash
python3 -m pip install --upgrade codelux
```

Check the installed version:

```bash
codelux --version
```

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

## Usage

Show all available commands:

```bash
codelux --help
```

Show the installed Codelux version:

```bash
codelux version
```

Inspect the detected Claude Code configuration and process state:

```bash
codelux status --client claude
```

List registered Providers without displaying credentials:

```bash
codelux list
```

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

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

Activate an already registered Provider for Codex:

```bash
codelux switch codelux-io --client codex
```

Return Claude Code to its official configuration or login flow:

```bash
codelux switch official --client claude
```

Replace the URL or credential for an existing Provider binding:

```bash
codelux update codelux-io --client claude
```

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

```bash
codelux remove codelux-io --client claude
```

Synchronize selected Provider state to another machine over SSH:

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

Synchronize selected Provider state from another machine over SSH:

```bash
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](README.md) | [简体中文](README.zh-CN.md)

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

**官网与 Provider API：** [https://codelux.io](https://codelux.io)

## Codelux 与 cc-switch

[cc-switch](https://github.com/farion1231/cc-switch) 是面向多种 AI 客户端的跨平台桌面管理工具。Codelux 则专注于喜欢轻量命令行工具的用户：

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

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

## 主要能力

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

## 安全模型

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

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

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

## 安装

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

```bash
python3 -m pip install --upgrade codelux
```

查看已安装版本：

```bash
codelux --version
```

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

## 使用方法

查看全部命令：

```bash
codelux --help
```

查看 Codelux 版本：

```bash
codelux version
```

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

```bash
codelux status --client claude
```

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

```bash
codelux list
```

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

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

为 Codex 激活已经注册的 Provider：

```bash
codelux switch codelux-io --client codex
```

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

```bash
codelux switch official --client claude
```

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

```bash
codelux update codelux-io --client claude
```

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

```bash
codelux remove codelux-io --client claude
```

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

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

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

```bash
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

