ccoding 0.1.0__tar.gz → 0.2.1__tar.gz

ccoding-0.2.1/PKG-INFO

@@ -0,0 +1,441 @@
+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