Metadata-Version: 2.5
Name: csm-cli
Version: 0.1.0
Summary: Claude Code 会话管理器：一屏浏览/过滤/收藏全部会话，回车 resume；TUI + 本地 Web 界面
Project-URL: Homepage, https://github.com/cainli/csm
Project-URL: Issues, https://github.com/cainli/csm/issues
Project-URL: Changelog, https://github.com/cainli/csm/blob/main/CHANGELOG.md
Author: cainli
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,cli,manager,session,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich>=13
Description-Content-Type: text/markdown

# csm — Claude Code 会话管理器

终端里开了一堆 Claude 会话分不清哪个是哪个？`csm` 一屏列出**全局所有项目**的 Claude 会话——AI 生成的标题、首条输入、运行状态、所属项目、消息轮数、worktree 归属、Session ID——输入即过滤，回车直接 resume。

- **只读**：对 `~/.claude` 严格只读，绝不写入或清理用户数据（唯一可写的是 csm 自有的收藏文件）
- **轻量**：Python ≥ 3.10；`prompt_toolkit`/`rich` 随包安装，开箱即用
- **发射后不管**：resume 用 `execvp` 接管进程，csm 不持有、不托管任何会话（Web 后台服务除外，见 `serve`）

三种前端：**TUI**（默认，fzf 式体验）、**Web 界面**（`csm serve`，含对话流预览与 diff，可后台守护/开机自启）、**表格/JSON**（`--list`，管道友好）。

## 功能速览

| 能力 | TUI | Web | `--list/--json` |
|---|:-:|:-:|:-:|
| 全局会话列表 + 即时过滤（多词 AND、`#标签`） | ✅ | ✅ | ✅（管道 grep/jq） |
| 运行状态（●busy/idle/waiting，pid 三重判活防复用） | ✅ | ✅ | ✅ |
| ◉本终端标记（tmux 下精确到 pane） | ✅ | ✅ | ✅ |
| 收藏两档（⭐/★）置顶 + 标签 | ✅ `s` 键 | ✅ 点星/编辑标签 | ✅ 字段输出 |
| 六档分类过滤（全部/运行中/本终端/收藏/已关闭/单轮） | ✅ `1`-`6` | ✅ chips | — |
| **worktree 感知**（`repo/wt ⎇分支 +未合并数`） | ✅ | ✅ | ✅ |
| 对话流预览（Markdown 渲染 + 工具调用折叠） | ✅ Tab 最近 50 条 | ✅ 完整分页 | — |
| **Edit/Write/MultiEdit 行级 diff**（红删绿增） | — | ✅ 完整级别 | — |
| **双开保护**（活会话在他终端 → 确认拦截） | ✅ | — | — |
| 复制 resume 命令（终端/tmux/headless 三变体） | — | ✅ | — |
| SDK 子进程会话标记（`sdk-cli` → SDK） | ✅ | ✅ | ✅ |
| **Web 后台守护**（`csm serve start/stop/status`，launchd 开机自启） | — | ✅ | — |

## 安装

PyPI 正式分发（包名 `csm-cli`，安装后命令为 `csm`）：

```zsh
pipx install csm-cli          # 或：uv tool install csm-cli
```

升级 / 卸载：`pipx upgrade csm-cli` / `pipx uninstall csm-cli`（uv 同理 `uv tool upgrade` / `uv tool uninstall`）。

需要 Python ≥ 3.10；`prompt_toolkit`/`rich` 随包自动安装。

<details><summary>从源码运行（开发/旧 alias）</summary>

```zsh
git clone https://github.com/cainli/csm.git && cd csm
python3 -m pytest                       # 跑测试
alias csm="$PWD/csm.py"                 # 仓库自带的兼容 shim
```

</details>

## 快速开始

```zsh
csm                    # TUI：打字过滤，回车 resume
csm serve start        # 后台起 Web 界面（127.0.0.1:8737，打印 URL）
csm --list             # 终端表格；csm --list --json | jq '.[] | .title'
```

## 命令行参数

```zsh
csm                          # 交互式 TUI（默认；stdout 非 tty 时自动降级 --list）
csm --list                   # 非交互表格
csm --list --json            # JSON 输出，可配 jq
csm --list --full-scan       # 表格带完整消息数（较慢 ~0.6s）
csm --project voicemouse     # 按项目路径过滤（大小写不敏感）
csm --new [PATH]             # 在 PATH（默认当前目录）起新会话，不进列表
csm --no-cd                  # resume 时停留在当前目录（默认切到原项目目录）
csm --limit 50               # 最多列出 50 条（默认全部）
csm --no-color / --version
```

### Web 服务：`csm serve`

```zsh
csm serve                    # 前台运行（调试用，端口占用自动顺延，Ctrl-C 停）
csm serve start              # 后台启动（固定 8737，打印 URL；日志 ~/.claude/csm/serve.log）
csm serve start --port 9000 --open
csm serve status             # running/stopped（pid + 探活）
csm serve restart
csm serve stop               # SIGTERM 优雅停（5s 超时强杀兜底）
csm serve install-launchd    # macOS 开机自启 + 崩溃自动拉起（launchd KeepAlive）
csm serve uninstall-launchd
csm --web                    # 兼容别名 = csm serve（前台）
```

launchd 模式日志在 `~/.claude/csm/launchd.{out,err}.log`；停 launchd 管理的服务请用 `uninstall-launchd`（手动 `stop` 会提示）。

## TUI

```
csm — 77 会话 (22 运行中) ★3 ⭐7  过滤:全部 68/77  1-6过滤 s星标 Tab预览 ^L清空 ^R重扫 esc退出
 ◉★ 11:20 ●busy  修复登录超时问题 #线上         claude-tools/fleet-features    12  757f8670-…
    10:29 ●idle  Orca 多 Agent 开发环境         swain                          8  892a5d70-…
```

### 键位

| 键 | 列表视图 | 预览视图 |
|---|---|---|
| `↑` `↓` / `j` `k`（输入为空时） | 选择 | 滚动消息 |
| `PgUp` `PgDn` `Home` `End` | 翻页/跳转 | 翻页/顶底 |
| 直接打字 | 过滤（标题/首输入/项目路径/SID，多词 AND；`#标签` 精确筛） | 同左 |
| `1`-`6` | **分类过滤**：全部/运行中/本终端/收藏/已关闭/单轮 | — |
| `s` | **星标循环**：无 → ⭐ → ★ → 无（收藏永久置顶） | — |
| `Tab` | **进入会话预览**（最近 50 条消息流） | 返回列表（保持原选择） |
| `Enter` | resume 选中会话（先 cd 到原项目目录；见他终端运行会触发双开确认） | resume 该会话 |
| `Ctrl-L` / `Ctrl-R` | 清空过滤 / 重新扫描 | 清空 / 刷新预览 |
| `Esc` / `Ctrl-C` | 退出（码 130） | 返回列表 / 退出 |

列表列：`◉本终端+★收藏 · 活跃时间 · ●运行状态 · 标题(或首条输入)#标签 · 项目 · 轮数 · Session ID`。闭会话若是 SDK 启动显示 `sdk` 标记；worktree 会话项目列显示 `主仓库/worktree名`。

每 30s 静默重扫：新会话自动出现在列表顶部，不打断当前选择与滚动（sid 桥接恢复状态）；正在输入过滤词时跳过当轮重扫。

## Web 界面（`csm serve`）

后台常驻（`csm serve start`，关终端不影响；`install-launchd` 开机自启）或前台调试（`csm serve` / 兼容别名 `--web`）。

- 左侧列表（搜索 + 分类 chips、NEW/◉本终端/SDK/worktree 徽章、星形按钮、收藏置顶浅色段）+ 右侧对话流
- **预览两级深度**：摘要（默认）/ 完整；消息按 **Markdown 渲染**（代码块/粗斜体/标题/列表/引用/链接/表格；先转义再白名单转换，免疫 XSS，离线自实现无 CDN）
- **行级 diff**：完整级别下点击 🔧 Edit/Write/MultiEdit 行展开——红删/绿增/无色上下文，LCS 对齐；MultiEdit 逐段标注
- **复制命令三变体**：`claude --resume`（终端）/ `tmux new-window -c`（并行恢复，落到原项目目录）/ `claude -p --resume`（headless 续跑）
- 每 5s 自动轮询（页面隐藏时暂停）；深浅色跟随系统；窄窗口（≤860px）自动单栏
- 消息解析缓存（mtime/size 失效）：14MB 会话首次解析 ~几十 ms，二次 <15ms

## 会话生命周期

### 双开保护

resume 一个正在**其他终端**运行的会话时，csm 警告并要求确认——两处同时写入同一会话文件（jsonl）可能导致内容交叉错乱。本终端运行的会话不拦；tty 无法识别时宁可误拦。

### `--new`：快速发射

`csm --new ~/dev/workspace/swain` 直接在该目录起新会话。与 resume 同为 `execvp` 接管——csm 始终不持有会话进程。

### worktree 感知

会话工作目录是 git worktree 时（EnterWorktree / `git worktree add` 后），读 `.git` 的 gitdir **指针**反解归属（不猜目录名，submodule 不误判），显示 `主仓库/worktree名 ⎇分支 +未合并提交数`：

- jsonl 的 `cwd` 逐行随 cd 变化——检测用**最后一条 cwd**（会话当前所在）；`project_path`（第一条 cwd，出生地）语义不变
- 未合并数由后台线程跑 `git rev-list --count` 补齐（超时 2s 静默降级）
- 全程只读：不创建、不清理任何 worktree

## 收藏与标签

- 存储在 `~/.claude/csm/favorites.json`（csm 自有命名空间，唯一可写文件；原子写 + 跨进程锁）
- 星标两档：⭐ 普通收藏 / ★ 重要；永久置顶（★ 段前于 ⭐ 段，段内按活跃时间）
- 标签在 Web 详情栏添加；搜索 `#标签名` 精确筛（多标签 AND）；TUI 与 Web 双向同步（≤30s）

## 分类口径（诚实声明）

- **运行状态**：busy/idle/waiting 来自 Claude 活跃注册表，pid 三重判活（存活 + 进程名含 claude + 启动时间容差比对）防 pid 复用；已关闭 = jsonl 在而注册表无活记录
- **本终端**：会话进程 tty == csm 进程 tty（tmux 下精确到 pane）；被 GUI 嵌套调用时可能无法识别，过滤器自动降级
- **单轮**：恰 1 条用户输入的会话。`claude -p` 无法从官方数据可靠识别（`entrypoint` 对交互与 `-p` 同为 `cli`），「单轮」是最接近的客观特征；SDK 子进程（`sdk-cli`）可识别并标记 SDK

## 数据来源（只读）

| 路径 | 用途 |
|---|---|
| `~/.claude/projects/*/*.jsonl` | 会话转录；文件名即 Session ID；标题取最后一条 `ai-title`；行内 `cwd`/`entrypoint` |
| `~/.claude/sessions/*.json` | 运行中会话注册表 → 状态 + tty 关联 |
| `~/.claude/history.jsonl` | 无标题会话的首条输入回退 |
| `~/.claude/csm/favorites.json` | **csm 自有**：收藏与标签（唯一可写） |

进程信息：单次 `ps -axo pid,ppid,tty,lstart,command` 快照三用（会话 tty / 进程名校验防 pid 回绕 / PPID 链上溯识别本终端）。
支持 `CLAUDE_CONFIG_DIR` 重定向配置目录（测试注入用）。

## 性能

三级渐进扫描：启动只 stat + 头尾各 64KB 轻扫（<0.2s）；消息轮数/worktree 未合并数由后台线程补齐；全文件解析仅在预览时发生且有 LRU 缓存，14MB 会话二次读取 <15ms。

## 开发

```zsh
python3 -m pytest    # 全部单测：离线假数据 + 真 git worktree 集成，不碰真实 ~/.claude
```

- 包布局 `src/csm_cli/`：`cli.py` 入口/CLI/resume/双开保护 · `scanner.py` 数据层+消息解析（唯一文件 I/O）·
  `ui.py` TUI · `web.py` Web 服务端 · `web.html` Web 前端（单文件，无构建，importlib.resources 读取）·
  `serve.py` 守护进程 · `fmt.py` 纯函数格式化；仓库根 `csm.py` 为兼容 shim
- `fmt.py` 中 `rel_time()` / `fuzzy_score()` 为故意留空的降级实现（学习场景），实装后 `test_fmt.py` 的 `skipif` 自动生效
- `web.html` 顶部 CSS 变量可整体换肤；打包见 `pyproject.toml`（hatchling，`csm-cli`）
