Metadata-Version: 2.4
Name: codex-cc
Version: 0.1.0
Summary: A lightweight local bridge that translates OpenAI Responses API calls to DeepSeek Chat Completions API — enabling Codex CLI and other OpenAI-compatible tools to use DeepSeek models.
Author: codex-cc contributors
License: MIT
Project-URL: Homepage, https://github.com/your-username/codex-cc
Project-URL: Source, https://github.com/your-username/codex-cc
Project-URL: Issues, https://github.com/your-username/codex-cc/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: uvicorn[standard]>=0.30.0
Dynamic: license-file

# codex-cc

> A lightweight local bridge that translates **OpenAI Responses API** calls to **DeepSeek Chat Completions API** — enabling Codex CLI, Claude Code, and other OpenAI-compatible tools to use DeepSeek models.

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Why codex-cc?

**The problem:** Codex CLI, Claude Code, and many AI coding tools speak the OpenAI Responses API protocol. DeepSeek, like most open-source model providers, exposes a Chat Completions API — these two protocols are incompatible.

**The solution:** codex-cc runs a local adapter at `127.0.0.1:8787` that translates between the two protocols transparently. Your tools talk to it as if it were OpenAI; it talks to DeepSeek in the background.

```
  Codex CLI / Claude Code / OpenAI SDK
         │
         │ OpenAI Responses API (SSE streaming)
         ▼
  ┌─────────────────────────┐
  │       codex-cc          │     127.0.0.1:8787
  │                         │
  │  Responses ↔ Chat       │
  │  Protocol Translation   │
  └──────────┬──────────────┘
             │
             │ DeepSeek Chat Completions API
             ▼
       api.deepseek.com
```

---

## Quick Start

### 1. Install

```bash
pip install codex-cc
```

### 2. Configure

```bash
codex-cc setup
```

The interactive wizard will ask for:
- **DeepSeek API Key** — get one at [platform.deepseek.com](https://platform.deepseek.com)
- **Bridge API Key** — auto-generated (used by your tools to authenticate)
- **Port** — defaults to `8787`
- **Host** — defaults to `127.0.0.1` (local only)

### 3. Run

```bash
codex-cc run
```

You should see:

```
🚀  codex-cc v0.1.0 starting...
    Listening: http://127.0.0.1:8787
    Model:     deepseek-v4-flash
    Health:    http://127.0.0.1:8787/healthz
```

### 4. Verify

```bash
# Health check
curl http://127.0.0.1:8787/healthz

# Send a test request
curl -X POST http://127.0.0.1:8787/v1/responses \
  -H "Authorization: Bearer YOUR_BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello, what is 2+2?", "model": "deepseek-v4-flash"}'
```

### 5. Connect Your Tool

**Codex CLI:** Set your OpenAI base URL to `http://127.0.0.1:8787/v1` and API key to your bridge key.

**Claude Code:** Configure the model provider to use `http://127.0.0.1:8787/v1` as the Responses API endpoint.

**Any OpenAI SDK:** Point `base_url` to `http://127.0.0.1:8787/v1`.

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `codex-cc run` | Start the bridge server |
| `codex-cc setup` | Interactive configuration wizard |
| `codex-cc status` | Check if the bridge is running |
| `codex-cc diagnose` | Check environment and troubleshoot issues |
| `codex-cc update` | Check for new versions |
| `codex-cc --version` | Show version |

### `codex-cc setup`

Interactive configuration stored in `~/.codex-cc/.env`:

```
🧙  codex-cc setup — Interactive Configuration

Step 1/4: DeepSeek API Key
  DeepSeek API Key: [your-key-here]

Step 2/4: Bridge API Key
  Bridge API Key [auto-generated]:

Step 3/4: Port
  Port [8787]:

Step 4/4: Host
  Host [127.0.0.1]:
```

Setup also validates your API key by connecting to DeepSeek.

### `codex-cc diagnose`

Runs 5 checks to identify common issues:

```
🔍  codex-cc diagnostics

  [1/5] Python      ✅  Python 3.12.2
  [2/5] Config      ✅  C:\Users\you\.codex-cc\.env
  [3/5] DeepSeek Key ✅  sk-abc1****f9x
  [4/5] Port 8787   ✅  Available
  [5/5] DeepSeek API ✅  Connected. Models: deepseek-v4-flash, deepseek-v4-pro
```

---

## Configuration

All configuration is stored in `~/.codex-cc/.env`. You can also set these as environment variables.

| Variable | Default | Description |
|----------|---------|-------------|
| `DEEPSEEK_API_KEY` | — | Your DeepSeek API key (required) |
| `CODEX_CC_BRIDGE_KEY` | auto-generated | Key clients use to authenticate |
| `CODEX_CC_HOST` | `127.0.0.1` | Bind address |
| `CODEX_CC_PORT` | `8787` | Listen port |
| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | Default model name |
| `DEEPSEEK_FORCE_MODEL` | `true` | Override client's model name |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com/v1` | DeepSeek API endpoint |
| `STREAM_TIMEOUT_SEC` | `600` | Streaming request timeout |
| `CODEX_CC_CORS_ORIGINS` | — | Comma-separated allowed CORS origins (empty = no CORS) |

> **Legacy support:** codex-cc also reads the older env var names (`DEEPSEEK_BRIDGE_API_KEY`, `BRIDGE_HOST`, `BRIDGE_PORT`, `DEEPSEEK_MODEL`) if the new names are not set. No migration needed if you're upgrading from the original bridge.

---

## API Endpoints

### `GET /healthz`

Returns the bridge status and configuration summary.

### `POST /v1/responses`

The main proxy endpoint. Accepts standard [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) requests and translates them to DeepSeek Chat Completions.

Supports:
- Text generation
- Streaming (SSE)
- Tool / Function calling
- Reasoning content
- Instructions / system prompts

### `POST /v1/responses/compact`

Context compaction endpoint for long-running Codex sessions. Summarizes the conversation history to fit within context limits.

---

## Security

- **Bound to `127.0.0.1` by default** — not exposed to the network.
- **Bridge API key** required for all requests to `/v1/responses`.
- **API key sanitization** — error messages are scrubbed of potential key leaks.
- **No CORS** by default — browser-based cross-origin access is disabled unless explicitly enabled via `CODEX_CC_CORS_ORIGINS`.
- **File permissions** — `.env` file is created with owner-only read/write on Unix systems.
- **Log rotation** — logs are capped at 10 MB with 3 backup files.

> **Warning:** If you set `CODEX_CC_HOST=0.0.0.0`, the bridge will be accessible to anyone on your local network. Use a firewall or restrict access appropriately.

---

## Troubleshooting

| Problem | Likely Cause | Solution |
|---------|-------------|----------|
| `Connection refused` | Bridge not running | Run `codex-cc run` |
| `401 Unauthorized` | Wrong bridge key | Run `codex-cc setup` to regenerate |
| `502 Bad Gateway` | DeepSeek API unreachable | Check your network / API key / proxy settings |
| `Port 8787 already in use` | Another service on that port | `codex-cc setup` to change port, or kill the other process |
| Antivirus flags the binary | PyInstaller false positive | Use `pip install codex-cc` instead of the binary |

Run `codex-cc diagnose` for an automated environment check.

---

## Comparison with Similar Projects

| Project | Language | Focus |
|---------|----------|-------|
| **codex-cc** | Python | **Minimal, auditable DeepSeek bridge** — ~200 LOC core |
| [AI Adapter](https://github.com/dyrnq/ai-adapter) | Rust | High-performance proxy for Codex CLI |
| [Responses Proxy](https://github.com/CallOrRet/responses-proxy) | Rust | Bidirectional Responses ↔ Chat proxy |
| [LLM-Rosetta](https://github.com/Oaklight/llm-rosetta) | Python | Universal protocol translation library |
| [LiteLLM](https://github.com/BerriAI/litellm) | Python | Enterprise API gateway (100+ models) |

codex-cc prioritizes **simplicity and auditability** over feature breadth. It does one thing — bridge DeepSeek and OpenAI protocols — and does it transparently.

---

## Development

```bash
# Clone and install in dev mode
git clone https://github.com/your-username/codex-cc
cd codex-cc
pip install -e ".[dev]"

# Run tests
pytest tests/

# Build package
pip install build
python -m build
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## 🌏 中文指南 / Chinese Guide

> codex-cc 是一个轻量级的本地桥接工具，将 **OpenAI Responses API** 协议转换为 **DeepSeek Chat Completions** 协议，让 Codex CLI、Claude Code 等 AI 编码工具可以使用 DeepSeek 模型。

### 快速开始

```bash
# 1. 安装
pip install codex-cc

# 2. 配置（会引导你输入 API Key）
codex-cc setup

# 3. 一键启动桥接 + Codex
codex-cc launch
```

### 配置要求

- **DeepSeek API Key** — 在 [platform.deepseek.com](https://platform.deepseek.com) 注册获取
- **Python 3.10+** — 建议使用 Python 3.12

### 中文环境

如果你是 Codex 桌面版用户且希望使用中文界面，运行项目提供的脚本：

```powershell
# Windows PowerShell
powershell -File scripts/codex-zh.ps1
```

该脚本会自动设置 `ELECTRON_LOCALE=zh-CN` 环境变量并启动 Codex 中文版。

### 常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| `codex-cc launch` 找不到 Codex | Codex 未安装 | 先手动安装 Codex 桌面版 |
| **CC-Switch** 用户切换模型 | 自动注册 | `codex-cc setup` 或 `launch` 会自动在 CC-Switch 中注册提供商 |
| 连接 DeepSeek 超时 | 网络问题 | 检查是否需要配置代理 |
| Windows 杀软误报 | PyInstaller 打包特征 | 改用 `pip install codex-cc` |

### 完整命令参考

```bash
codex-cc run        # 前台启动桥接
codex-cc start      # 后台启动桥接
codex-cc stop       # 停止后台桥接
codex-cc setup      # 配置向导
codex-cc status     # 查看状态
codex-cc diagnose   # 环境诊断
codex-cc launch     # 一键启动（桥接 + Codex）
codex-cc update     # 检查更新
```

### 项目地址

GitHub: [github.com/gtbwpkwjnb-alt/codex-cc](https://github.com/gtbwpkwjnb-alt/codex-cc)

如有问题或建议，欢迎提交 [Issue](https://github.com/gtbwpkwjnb-alt/codex-cc/issues) 或 Pull Request。
