Metadata-Version: 2.4
Name: ccoding
Version: 0.2.1
Summary: Curses-based Claude Code launcher
Project-URL: Homepage, https://github.com/8DE4732A/ccode
Project-URL: Repository, https://github.com/8DE4732A/ccode
Project-URL: Issues, https://github.com/8DE4732A/ccode/issues
Author: 8de4732a
License: MIT License
        
        Copyright (c) 2025 8DE4732A
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: claude,claude-code,curses,launcher,tui
Classifier: Environment :: Console :: Curses
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Requires-Dist: windows-curses; sys_platform == 'win32'
Provides-Extra: remote
Requires-Dist: fastapi; extra == 'remote'
Requires-Dist: pexpect; (sys_platform != 'win32') and extra == 'remote'
Requires-Dist: uvicorn[standard]; extra == 'remote'
Requires-Dist: websockets; extra == 'remote'
Provides-Extra: remote-client
Requires-Dist: pexpect; (sys_platform != 'win32') and extra == 'remote-client'
Requires-Dist: websockets; extra == 'remote-client'
Provides-Extra: remote-server
Requires-Dist: fastapi; extra == 'remote-server'
Requires-Dist: uvicorn[standard]; extra == 'remote-server'
Description-Content-Type: text/markdown

# CCode Launcher (Curses UI)

这是一个基于 curses 的 Claude Code 启动器，提供键盘全操作的终端界面，用于配置 Base URL、API Key、模型选择和常用开关，并直接启动 `claude` 命令。

工具的目的是方便启动 claude code 时快速选择想要使用的模型。模型网关可以使用 litellm proxy 或者 CLI Proxy API。

![](screenshot.png)

## 功能特点

- 终端 curses UI，键盘全操作
- 主界面选择 OPUS / SONNET / HAIKU 的 owned_by 与 model_id
- 配置界面编辑 Base URL / API Key 与常用开关
- 自动保存配置到 `~/.ccode/config.json`
- 直接启动 `claude` 并传递额外参数
- Remote/Web 模式：通过 tmux 保留多个 Claude Code 会话，并在浏览器中选择和操作
- 支持本机 local hub，也支持公网中心 `ccode-remote-server` 聚合多台设备
- 动画 Logo（颜色渐变 / 流光 / 轻微波浪）

## 安装

推荐使用 [uv](https://github.com/astral-sh/uv) 安装为全局工具：

```bash
uv tool install ccoding
```

如果需要 Remote/Web 功能，按使用场景安装对应 extra：

```bash
uv tool install 'ccoding[remote-client]'   # 客户端设备：运行 ccode，并连接中心 server
uv tool install 'ccoding[remote-server]'   # 公网中心 server：运行 ccode-remote-server
uv tool install 'ccoding[remote]'          # 同时包含 client/server remote 依赖
```

已经安装过基础版本时，可以用 `--reinstall` 重新安装带 extra 的版本：

```bash
uv tool install --reinstall 'ccoding[remote]'
```

或使用 [pipx](https://pipx.pypa.io)：

```bash
pipx install ccoding
pipx install 'ccoding[remote]'
```

### uv tool extras 区别

`uv tool install 'ccoding[remote-client]'`、`uv tool install 'ccoding[remote-server]'` 和 `uv tool install 'ccoding[remote]'` 安装的都是同一个 Python 包 `ccoding`，因此都会安装基础命令入口。区别只在于额外依赖是否齐全，以及对应 remote 能力是否可用。

| 安装方式 | `ccode` 基础 TUI | `ccode-remote` | `ccode-remote-server` | 安装的额外依赖 | 适合场景 |
|---|---:|---:|---:|---|---|
| `uv tool install ccoding` | 可用 | 命令存在，但 remote 功能依赖不足 | 命令存在，但缺 server 依赖不能运行 | 无 | 只用模型选择 TUI |
| `uv tool install 'ccoding[remote-client]'` | 可用 | 可管理 client connector；local hub 可能缺 FastAPI/uvicorn | 命令存在，但缺 FastAPI/uvicorn 不能运行 | `pexpect`、`websockets` | 客户端设备：启动 Claude session 并连接中心 server |
| `uv tool install 'ccoding[remote-server]'` | 可用 | 命令存在，但 client/local 能力依赖不足 | 可运行 | `fastapi`、`uvicorn[standard]` | 只部署公网中心 server |
| `uv tool install 'ccoding[remote]'` | 可用 | 可用 | 可用 | `pexpect`、`websockets`、`fastapi`、`uvicorn[standard]` | 开发环境或单机全功能 |

推荐选择：

- 只在本机选择模型并启动 Claude：`uv tool install ccoding`
- 这台机器是“客户端设备”，需要用 `ccode` 启动 remote session 并连接中心 server：`uv tool install 'ccoding[remote-client]'`
- 这台机器只负责运行公网中心 server：`uv tool install 'ccoding[remote-server]'`
- 不想区分角色，或开发调试需要本机同时跑 server 和 client：`uv tool install 'ccoding[remote]'`

安装后直接运行：

```bash
ccode
ccode --chrome   # 传递额外参数给 claude
ccode-remote     # 查看 remote hub / client connector 状态
```

## 开发者运行方式

需要 Python >=3.10。基础 TUI 不再强制安装 remote 依赖。Remote/Web 模式需要额外依赖，并需要系统中已安装 `tmux` 和 `claude`；Windows 建议在 WSL 中使用 remote 模式。

```bash
git clone https://github.com/8DE4732A/ccode
cd ccode
uv sync
uv run ccode
```

按需安装 remote extras：

```bash
uv sync --extra remote-client   # 客户端 connector：pexpect + websockets
uv sync --extra remote-server   # 公网中心 server：FastAPI + uvicorn
uv sync --extra remote          # 同时安装 client/server 依赖
```

## 快捷键（主界面）

- `↑ / ↓`：切换 OPUS / SONNET / HAIKU 行
- `← / →`：切换 owned_by / model_id 字段
- `a / d`：循环切换当前字段的可选项
- `b`：刷新模型列表
- `r`：切换 Remote/Web 模式
- `c`：进入配置界面
- `Enter`：校验并启动本地 `claude`；Remote/Web 模式开启时启动 remote session
- `q`：退出

> 提示：首次使用需要先在配置界面设置 Base URL 与 API Key，然后返回主界面按 `b` 获取模型列表。

## 快捷键（配置界面）

- `↑ / ↓`：移动字段焦点
- `Enter / Space`：切换开关项
- 文本输入：编辑 BASE_URL / API_KEY、remote local/server URL/token/device/prefix 等字段
- `g`：在 Remote local token 或 server client token 字段重新生成访问 token
- `ESC`：自动保存并返回主界面

## 配置文件

配置自动保存在：

```
~/.ccode/config.json
```

示例结构：

```json
{
  "base_url": "http://127.0.0.1:8317",
  "api_key": "",
  "models": {
    "opus": {"owned_by": null, "id": null},
    "sonnet": {"owned_by": null, "id": null},
    "haiku": {"owned_by": null, "id": null}
  },
  "toggles": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
    "DISABLE_COST_WARNINGS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "remote": {
    "enabled": false,
    "mode": "local",
    "session_name": "ccode-claude",
    "reuse_session": true,
    "local": {
      "host": "127.0.0.1",
      "port": 8765,
      "token": ""
    },
    "server": {
      "url": "",
      "token": "",
      "device_name": "",
      "device_id": "",
      "auto_connect": true,
      "verify_tls": true
    }
  }
}
```

## Remote/Web 模式

Remote/Web 让 Claude Code 运行在 tmux session 中，浏览器通过 WebSocket attach 到这个 session。它有两种模式：

| 模式 | 浏览器访问 | session 所在位置 | 适合场景 |
|---|---|---|---|
| `local` | 直接访问本机 local hub | 当前这台机器 | 单机使用，或把这一台机器通过 tunnel 暴露出去 |
| `server` | 访问公网中心 `ccode-remote-server` | 各客户端设备本机 | 多设备、NAT 后设备、统一入口管理多个 sessions |

### local 模式

local 模式会在本机启动一个共享 FastAPI hub。浏览器直接访问这个 hub，hub 再 attach 到本机 tmux session。

```text
Browser
  │ HTTP / WebSocket
  ▼
Local ccode remote hub
  │ pexpect attach
  ▼
tmux session
  │
  ▼
claude
```

使用步骤：

1. 安装完整 remote 或至少确保 local hub 依赖可用：

   ```bash
   uv tool install 'ccoding[remote]'
   ```

2. 运行 `ccode`，进入配置页：

   - `MODE`：`local`
   - `LOCAL HOST`：默认 `127.0.0.1`
   - `LOCAL PORT`：默认 `8765`
   - `LOCAL TOKEN`：手动输入，或在该字段按 `g` 生成

3. 回到主界面，按 `r` 开启 Remote/Web，再按 `Enter` 启动 remote session。

4. 浏览器打开终端输出的本地地址，输入 `LOCAL TOKEN`，选择 session 后进入 terminal。

local 模式默认只监听 `127.0.0.1`。终端只输出不带 token 的本地访问地址。浏览器打开页面后需要手动输入 token，前端会用 `sessionStorage` 做浏览器会话级缓存；关闭该浏览器会话后需要重新输入。所有 session list、session API 和 WebSocket 连接仍然需要 token。

每个启用 Remote/Web 的 `ccode` 进程都会创建一个唯一 tmux session，session 名由配置里的 `session_name` 前缀、时间戳和进程号组成，例如 `ccode-claude-20260509-153022-12345`。本机只启动一个共享 remote hub，多个本地 `ccode` 进程会复用同一个 host/port/token。浏览器认证后会先显示 session 列表，选择某个 session 后进入 terminal，也可以返回列表重新选择。

如果通过 Cloudflare Tunnel、Nginx、Caddy 等反向代理暴露 local hub，建议额外叠加 Cloudflare Access、Basic Auth 或 OAuth2 proxy。监听 `0.0.0.0` 会把所有 remote sessions 暴露给网络内可达主机，请保护好访问入口和 token。

```bash
cloudflared tunnel --url http://127.0.0.1:8765
```

local hub 日志写入 `~/.ccode/remote_server.log`，记录 hub 启停、session 注册、session API 和 WebSocket 连接状态，不记录 token。启动 hub 前如果日志超过 5 MiB 会自动轮转，默认保留 3 个历史文件（`.1`、`.2`、`.3`）。

### server 模式和 `ccode-remote-server`

`ccode-remote-server` 是可部署到公网的中心 registry/router/relay。它不创建本地 PTY，也不会保存 Anthropic API key、模型配置、客户端环境变量或 terminal 内容；每台客户端继续负责自己的 tmux/Claude 会话，并通过出站 WebSocket 连接 server。

整体结构：

```text
                  Browser
                     │
                     │ HTTPS/WSS + admin token
                     ▼
          ┌───────────────────────┐
          │ ccode-remote-server   │
          │ registry/router/relay │
          └───────────┬───────────┘
                      │ attach relay
        ┌─────────────┼─────────────┐
        │             │             │
        ▼             ▼             ▼
 ┌────────────┐ ┌────────────┐ ┌────────────┐
 │ Laptop A   │ │ Server B   │ │ Desktop C  │
 │ connector  │ │ connector  │ │ connector  │
 │ tmux/claude│ │ tmux/claude│ │ tmux/claude│
 └────────────┘ └────────────┘ └────────────┘
```

连接方向：

```text
客户端设备  ──出站 WebSocket──▶  ccode-remote-server  ◀──浏览器访问──  Browser
```

server 不反连客户端，所以客户端可以在 NAT、家庭网络或公司内网后面。只要客户端能主动访问 server，就可以注册设备和暴露自己的 remote sessions。

#### server token

server token 不会自动生成，必须通过环境变量显式设置：

- `CCODE_REMOTE_SERVER_ADMIN_TOKEN`：浏览器 Web UI / `/api/*` / browser WebSocket 使用的管理 token。
- `CCODE_REMOTE_SERVER_CLIENT_TOKEN`：各设备客户端 connector 注册和心跳使用的 token。
- `CCODE_REMOTE_SERVER_HOST` / `CCODE_REMOTE_SERVER_PORT`：可选，默认监听 `127.0.0.1:8765`。

启动中心 server：

```bash
CCODE_REMOTE_SERVER_ADMIN_TOKEN="admin-secret" \
CCODE_REMOTE_SERVER_CLIENT_TOKEN="client-secret" \
ccode-remote-server --host 127.0.0.1 --port 8765
```

如果使用源码开发环境运行：

```bash
CCODE_REMOTE_SERVER_ADMIN_TOKEN="admin-secret" \
CCODE_REMOTE_SERVER_CLIENT_TOKEN="client-secret" \
uv run --extra remote-server ccode-remote-server --host 127.0.0.1 --port 8765
```

浏览器访问 server 页面时输入 `admin-secret`。如果未设置 `CCODE_REMOTE_SERVER_ADMIN_TOKEN`，管理 API 会返回 401，页面上任何 token 都无法通过认证。

#### 客户端设备配置

每台客户端设备需要安装 client extra：

```bash
uv tool install 'ccoding[remote-client]'
```

然后运行 `ccode`，在配置页设置：

- `MODE`：`server`
- `SERVER URL`：中心 server 地址，例如 `http://127.0.0.1:8765`；如果只填 `127.0.0.1:8765`，会自动按 `http://127.0.0.1:8765` 处理
- `CLIENT TOKEN`：与 server 的 `CCODE_REMOTE_SERVER_CLIENT_TOKEN` 一致
- `DEVICE NAME`：设备显示名，可留空后由配置迁移填充 hostname
- `DEVICE ID`：稳定设备 ID，可留空后自动生成
- `AUTO CONNECT`：是否默认自动连接中心 server

配置完成后，在主界面按 `r` 开启 Remote/Web，再按 `Enter` 启动 remote session。server 模式会注册本地 tmux session，并确保后台 client connector 运行。浏览器打开中心 server 后即可看到所有在线设备和 sessions。

也可以用命令检查和管理客户端 connector：

```bash
ccode-remote client status
ccode-remote client start
ccode-remote client restart
ccode-remote client stop
```

#### attach 数据流

浏览器点击某个设备上的 session 时，server 会创建一次性短生命周期 `attach_id`，通知目标客户端主动建立 attach WebSocket，然后在浏览器和客户端之间转发 terminal JSON 帧。

```text
1. Browser ── WS /ws/devices/{device_id}/sessions/{session_id} ──▶ Server
2. Server  ── attach_request(attach_id, session_id) ─────────────▶ Client connector
3. Client  ── WS /client/attach/{attach_id} ─────────────────────▶ Server
4. Server  ◀──────────── relay input/output/resize ─────────────▶ Browser
5. Client connector ── pexpect ──▶ local tmux session ──▶ claude
```

server 只做 registry/router/relay，不保存 terminal frame data，不保存 Anthropic API key，不保存模型配置。`cwd`、tmux session 名、创建时间等 metadata 会用于 session 列表展示。

#### Cloudflare Tunnel / 反向代理

如果用 Cloudflare Tunnel 暴露中心 server，只需要 tunnel server 这一处入口，多台客户端设备都配置同一个 `SERVER URL` 和 `CLIENT TOKEN`：

```bash
cloudflared tunnel --url http://127.0.0.1:8765
```

生产环境建议只使用 HTTPS/WSS；如果 `SERVER URL` 使用 `http://`，客户端会提示明文连接风险。建议再叠加 Cloudflare Access、Basic Auth 或 OAuth2 proxy。

### remote 管理命令

`ccode-remote` 会根据当前配置的 `remote.mode` 自动管理 local hub 或 client connector；也可以显式指定 `local` / `client`：

```bash
ccode-remote
ccode-remote status
ccode-remote start
ccode-remote restart
ccode-remote stop

ccode-remote local status
ccode-remote local start
ccode-remote local stop

ccode-remote client status
ccode-remote client start
ccode-remote client restart
ccode-remote client stop
```

日志和状态文件：

| 文件 | 用途 |
|---|---|
| `~/.ccode/remote_sessions.json` | 本机 session registry，只记录 tmux session、cwd、args、创建时间和 owner pid |
| `~/.ccode/remote_server.log` | local hub 日志 |
| `~/.ccode/remote_client.log` | server 模式 client connector 日志 |
| `~/.ccode/remote_hub.pid` | local hub 后台进程 pid |
| `~/.ccode/remote_client.pid` | client connector 后台进程 pid |

浏览器和多个本地终端可以同时 attach 到同一个 tmux session，输入会互相影响，这是预期行为。可用 `Ctrl+B` 然后 `D` 从本地终端 detach；remote hub 或 client connector 会独立留在后台运行，tmux session 不会因为浏览器断开而被 kill。

## 工作原理

基础启动流程：

```text
~/.ccode/config.json
        │
        ▼
ccode curses UI ── fetch /v1/models ──▶ LiteLLM proxy / CLI Proxy API
        │
        ▼
选择 OPUS / SONNET / HAIKU model_id
        │
        ▼
build_env() 注入环境变量
        │
        ▼
subprocess.run(["claude", ...])
```

1. 从 `~/.ccode/config.json` 读取配置（首次运行自动生成）。
2. 根据 Base URL + API Key 拉取模型列表。
3. 选择 OPUS / SONNET / HAIKU 的 owned_by / model_id。
4. 启动 `claude`，并注入相关环境变量。

## 许可证

MIT
