Metadata-Version: 2.4
Name: codelux
Version: 0.1.0a5
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
- 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](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.

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

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

## 安全模型

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

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

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

