csm-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,15 @@
1
+ # Python 字节码与缓存
2
+ __pycache__/
3
+ *.py[cod]
4
+ .pytest_cache/
5
+
6
+ # 虚拟环境
7
+ .venv/
8
+ venv/
9
+
10
+ # IDE
11
+ .idea/
12
+ .vscode/
13
+
14
+ # macOS
15
+ .DS_Store
@@ -0,0 +1,32 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-22)
4
+
5
+ 首个正式发布。四轮功能迭代汇总:
6
+
7
+ ### 核心:会话浏览与切换
8
+ - 全局列出所有项目的 Claude 会话(mtime 排序,AI 标题 + 首条输入摘要)
9
+ - TUI:输入即过滤(多词 AND)、`#标签` 语法、回车直接 `claude --resume`(先 cd 原项目目录)
10
+ - 三种前端:prompt_toolkit TUI(默认)、本地 Web(`csm serve`)、rich 表格(`--list`/`--json`)
11
+ - resume 双开保护:会话活在他终端时警告确认;`--new [PATH]` 直接起新会话
12
+
13
+ ### 会话预览
14
+ - TUI `Tab` 预览视图 + Web 侧栏对话流:用户输入 / 助手回复 / 工具调用折叠行
15
+ - 消息流解析:assistant 跨行分段合并、tool_result 100% 回填、行级 diff(Edit/Write/MultiEdit)
16
+ - Web 消息 Markdown 渲染(代码块/表格/列表等,先转义再白名单转换,免疫 XSS)
17
+ - 大文件(14MB)解析 ~30ms,LRU 缓存(mtime/size 失效)
18
+
19
+ ### 分类与收藏
20
+ - 分类过滤(数字键 1-6 / Web chips):全部/运行中/本终端/已关闭/单轮/收藏
21
+ - tty 关联识别「本终端」(ps 快照 + PPID 链上溯,tmux 精确到 pane);worktree 会话显示分支与未合并提交数
22
+ - 收藏两档(⭐/★)永久置顶 + 自定义标签,存 `~/.claude/csm/favorites.json`(TUI/Web 互通)
23
+ - `claude -p` 无法从官方数据识别(entrypoint 不可区分,二进制验证)——「单轮」为客观近似
24
+
25
+ ### Web 服务与守护
26
+ - `csm serve`:前台运行或 daemon(`start`/`stop`/`status`/`restart`,pidfile + 日志)
27
+ - `csm serve install-launchd`:macOS 开机自启 + 崩溃自动拉起
28
+ - 新会话 ≤5s 自动出现(前端轮询 + 服务端 stat 级增量 diff);深浅色跟随系统
29
+
30
+ ### 工程
31
+ - Python ≥3.10;PyPI 包 `csm-cli`(命令名 `csm`);GitHub Actions Trusted Publishing
32
+ - 56 个离线单测(假数据注入,不碰真实 `~/.claude`)
csm_cli-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 cainli
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
csm_cli-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.5
2
+ Name: csm-cli
3
+ Version: 0.1.0
4
+ Summary: Claude Code 会话管理器:一屏浏览/过滤/收藏全部会话,回车 resume;TUI + 本地 Web 界面
5
+ Project-URL: Homepage, https://github.com/cainli/csm
6
+ Project-URL: Issues, https://github.com/cainli/csm/issues
7
+ Project-URL: Changelog, https://github.com/cainli/csm/blob/main/CHANGELOG.md
8
+ Author: cainli
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude,claude-code,cli,manager,session,tui
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Environment :: Web Environment
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: POSIX
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Software Development
25
+ Classifier: Topic :: Utilities
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: prompt-toolkit>=3.0
28
+ Requires-Dist: rich>=13
29
+ Description-Content-Type: text/markdown
30
+
31
+ # csm — Claude Code 会话管理器
32
+
33
+ 终端里开了一堆 Claude 会话分不清哪个是哪个?`csm` 一屏列出**全局所有项目**的 Claude 会话——AI 生成的标题、首条输入、运行状态、所属项目、消息轮数、worktree 归属、Session ID——输入即过滤,回车直接 resume。
34
+
35
+ - **只读**:对 `~/.claude` 严格只读,绝不写入或清理用户数据(唯一可写的是 csm 自有的收藏文件)
36
+ - **轻量**:Python ≥ 3.10;`prompt_toolkit`/`rich` 随包安装,开箱即用
37
+ - **发射后不管**:resume 用 `execvp` 接管进程,csm 不持有、不托管任何会话(Web 后台服务除外,见 `serve`)
38
+
39
+ 三种前端:**TUI**(默认,fzf 式体验)、**Web 界面**(`csm serve`,含对话流预览与 diff,可后台守护/开机自启)、**表格/JSON**(`--list`,管道友好)。
40
+
41
+ ## 功能速览
42
+
43
+ | 能力 | TUI | Web | `--list/--json` |
44
+ |---|:-:|:-:|:-:|
45
+ | 全局会话列表 + 即时过滤(多词 AND、`#标签`) | ✅ | ✅ | ✅(管道 grep/jq) |
46
+ | 运行状态(●busy/idle/waiting,pid 三重判活防复用) | ✅ | ✅ | ✅ |
47
+ | ◉本终端标记(tmux 下精确到 pane) | ✅ | ✅ | ✅ |
48
+ | 收藏两档(⭐/★)置顶 + 标签 | ✅ `s` 键 | ✅ 点星/编辑标签 | ✅ 字段输出 |
49
+ | 六档分类过滤(全部/运行中/本终端/收藏/已关闭/单轮) | ✅ `1`-`6` | ✅ chips | — |
50
+ | **worktree 感知**(`repo/wt ⎇分支 +未合并数`) | ✅ | ✅ | ✅ |
51
+ | 对话流预览(Markdown 渲染 + 工具调用折叠) | ✅ Tab 最近 50 条 | ✅ 完整分页 | — |
52
+ | **Edit/Write/MultiEdit 行级 diff**(红删绿增) | — | ✅ 完整级别 | — |
53
+ | **双开保护**(活会话在他终端 → 确认拦截) | ✅ | — | — |
54
+ | 复制 resume 命令(终端/tmux/headless 三变体) | — | ✅ | — |
55
+ | SDK 子进程会话标记(`sdk-cli` → SDK) | ✅ | ✅ | ✅ |
56
+ | **Web 后台守护**(`csm serve start/stop/status`,launchd 开机自启) | — | ✅ | — |
57
+
58
+ ## 安装
59
+
60
+ PyPI 正式分发(包名 `csm-cli`,安装后命令为 `csm`):
61
+
62
+ ```zsh
63
+ pipx install csm-cli # 或:uv tool install csm-cli
64
+ ```
65
+
66
+ 升级 / 卸载:`pipx upgrade csm-cli` / `pipx uninstall csm-cli`(uv 同理 `uv tool upgrade` / `uv tool uninstall`)。
67
+
68
+ 需要 Python ≥ 3.10;`prompt_toolkit`/`rich` 随包自动安装。
69
+
70
+ <details><summary>从源码运行(开发/旧 alias)</summary>
71
+
72
+ ```zsh
73
+ git clone https://github.com/cainli/csm.git && cd csm
74
+ python3 -m pytest # 跑测试
75
+ alias csm="$PWD/csm.py" # 仓库自带的兼容 shim
76
+ ```
77
+
78
+ </details>
79
+
80
+ ## 快速开始
81
+
82
+ ```zsh
83
+ csm # TUI:打字过滤,回车 resume
84
+ csm serve start # 后台起 Web 界面(127.0.0.1:8737,打印 URL)
85
+ csm --list # 终端表格;csm --list --json | jq '.[] | .title'
86
+ ```
87
+
88
+ ## 命令行参数
89
+
90
+ ```zsh
91
+ csm # 交互式 TUI(默认;stdout 非 tty 时自动降级 --list)
92
+ csm --list # 非交互表格
93
+ csm --list --json # JSON 输出,可配 jq
94
+ csm --list --full-scan # 表格带完整消息数(较慢 ~0.6s)
95
+ csm --project voicemouse # 按项目路径过滤(大小写不敏感)
96
+ csm --new [PATH] # 在 PATH(默认当前目录)起新会话,不进列表
97
+ csm --no-cd # resume 时停留在当前目录(默认切到原项目目录)
98
+ csm --limit 50 # 最多列出 50 条(默认全部)
99
+ csm --no-color / --version
100
+ ```
101
+
102
+ ### Web 服务:`csm serve`
103
+
104
+ ```zsh
105
+ csm serve # 前台运行(调试用,端口占用自动顺延,Ctrl-C 停)
106
+ csm serve start # 后台启动(固定 8737,打印 URL;日志 ~/.claude/csm/serve.log)
107
+ csm serve start --port 9000 --open
108
+ csm serve status # running/stopped(pid + 探活)
109
+ csm serve restart
110
+ csm serve stop # SIGTERM 优雅停(5s 超时强杀兜底)
111
+ csm serve install-launchd # macOS 开机自启 + 崩溃自动拉起(launchd KeepAlive)
112
+ csm serve uninstall-launchd
113
+ csm --web # 兼容别名 = csm serve(前台)
114
+ ```
115
+
116
+ launchd 模式日志在 `~/.claude/csm/launchd.{out,err}.log`;停 launchd 管理的服务请用 `uninstall-launchd`(手动 `stop` 会提示)。
117
+
118
+ ## TUI
119
+
120
+ ```
121
+ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星标 Tab预览 ^L清空 ^R重扫 esc退出
122
+ ◉★ 11:20 ●busy 修复登录超时问题 #线上 claude-tools/fleet-features 12 757f8670-…
123
+ 10:29 ●idle Orca 多 Agent 开发环境 swain 8 892a5d70-…
124
+ ```
125
+
126
+ ### 键位
127
+
128
+ | 键 | 列表视图 | 预览视图 |
129
+ |---|---|---|
130
+ | `↑` `↓` / `j` `k`(输入为空时) | 选择 | 滚动消息 |
131
+ | `PgUp` `PgDn` `Home` `End` | 翻页/跳转 | 翻页/顶底 |
132
+ | 直接打字 | 过滤(标题/首输入/项目路径/SID,多词 AND;`#标签` 精确筛) | 同左 |
133
+ | `1`-`6` | **分类过滤**:全部/运行中/本终端/收藏/已关闭/单轮 | — |
134
+ | `s` | **星标循环**:无 → ⭐ → ★ → 无(收藏永久置顶) | — |
135
+ | `Tab` | **进入会话预览**(最近 50 条消息流) | 返回列表(保持原选择) |
136
+ | `Enter` | resume 选中会话(先 cd 到原项目目录;见他终端运行会触发双开确认) | resume 该会话 |
137
+ | `Ctrl-L` / `Ctrl-R` | 清空过滤 / 重新扫描 | 清空 / 刷新预览 |
138
+ | `Esc` / `Ctrl-C` | 退出(码 130) | 返回列表 / 退出 |
139
+
140
+ 列表列:`◉本终端+★收藏 · 活跃时间 · ●运行状态 · 标题(或首条输入)#标签 · 项目 · 轮数 · Session ID`。闭会话若是 SDK 启动显示 `sdk` 标记;worktree 会话项目列显示 `主仓库/worktree名`。
141
+
142
+ 每 30s 静默重扫:新会话自动出现在列表顶部,不打断当前选择与滚动(sid 桥接恢复状态);正在输入过滤词时跳过当轮重扫。
143
+
144
+ ## Web 界面(`csm serve`)
145
+
146
+ 后台常驻(`csm serve start`,关终端不影响;`install-launchd` 开机自启)或前台调试(`csm serve` / 兼容别名 `--web`)。
147
+
148
+ - 左侧列表(搜索 + 分类 chips、NEW/◉本终端/SDK/worktree 徽章、星形按钮、收藏置顶浅色段)+ 右侧对话流
149
+ - **预览两级深度**:摘要(默认)/ 完整;消息按 **Markdown 渲染**(代码块/粗斜体/标题/列表/引用/链接/表格;先转义再白名单转换,免疫 XSS,离线自实现无 CDN)
150
+ - **行级 diff**:完整级别下点击 🔧 Edit/Write/MultiEdit 行展开——红删/绿增/无色上下文,LCS 对齐;MultiEdit 逐段标注
151
+ - **复制命令三变体**:`claude --resume`(终端)/ `tmux new-window -c`(并行恢复,落到原项目目录)/ `claude -p --resume`(headless 续跑)
152
+ - 每 5s 自动轮询(页面隐藏时暂停);深浅色跟随系统;窄窗口(≤860px)自动单栏
153
+ - 消息解析缓存(mtime/size 失效):14MB 会话首次解析 ~几十 ms,二次 <15ms
154
+
155
+ ## 会话生命周期
156
+
157
+ ### 双开保护
158
+
159
+ resume 一个正在**其他终端**运行的会话时,csm 警告并要求确认——两处同时写入同一会话文件(jsonl)可能导致内容交叉错乱。本终端运行的会话不拦;tty 无法识别时宁可误拦。
160
+
161
+ ### `--new`:快速发射
162
+
163
+ `csm --new ~/dev/workspace/swain` 直接在该目录起新会话。与 resume 同为 `execvp` 接管——csm 始终不持有会话进程。
164
+
165
+ ### worktree 感知
166
+
167
+ 会话工作目录是 git worktree 时(EnterWorktree / `git worktree add` 后),读 `.git` 的 gitdir **指针**反解归属(不猜目录名,submodule 不误判),显示 `主仓库/worktree名 ⎇分支 +未合并提交数`:
168
+
169
+ - jsonl 的 `cwd` 逐行随 cd 变化——检测用**最后一条 cwd**(会话当前所在);`project_path`(第一条 cwd,出生地)语义不变
170
+ - 未合并数由后台线程跑 `git rev-list --count` 补齐(超时 2s 静默降级)
171
+ - 全程只读:不创建、不清理任何 worktree
172
+
173
+ ## 收藏与标签
174
+
175
+ - 存储在 `~/.claude/csm/favorites.json`(csm 自有命名空间,唯一可写文件;原子写 + 跨进程锁)
176
+ - 星标两档:⭐ 普通收藏 / ★ 重要;永久置顶(★ 段前于 ⭐ 段,段内按活跃时间)
177
+ - 标签在 Web 详情栏添加;搜索 `#标签名` 精确筛(多标签 AND);TUI 与 Web 双向同步(≤30s)
178
+
179
+ ## 分类口径(诚实声明)
180
+
181
+ - **运行状态**:busy/idle/waiting 来自 Claude 活跃注册表,pid 三重判活(存活 + 进程名含 claude + 启动时间容差比对)防 pid 复用;已关闭 = jsonl 在而注册表无活记录
182
+ - **本终端**:会话进程 tty == csm 进程 tty(tmux 下精确到 pane);被 GUI 嵌套调用时可能无法识别,过滤器自动降级
183
+ - **单轮**:恰 1 条用户输入的会话。`claude -p` 无法从官方数据可靠识别(`entrypoint` 对交互与 `-p` 同为 `cli`),「单轮」是最接近的客观特征;SDK 子进程(`sdk-cli`)可识别并标记 SDK
184
+
185
+ ## 数据来源(只读)
186
+
187
+ | 路径 | 用途 |
188
+ |---|---|
189
+ | `~/.claude/projects/*/*.jsonl` | 会话转录;文件名即 Session ID;标题取最后一条 `ai-title`;行内 `cwd`/`entrypoint` |
190
+ | `~/.claude/sessions/*.json` | 运行中会话注册表 → 状态 + tty 关联 |
191
+ | `~/.claude/history.jsonl` | 无标题会话的首条输入回退 |
192
+ | `~/.claude/csm/favorites.json` | **csm 自有**:收藏与标签(唯一可写) |
193
+
194
+ 进程信息:单次 `ps -axo pid,ppid,tty,lstart,command` 快照三用(会话 tty / 进程名校验防 pid 回绕 / PPID 链上溯识别本终端)。
195
+ 支持 `CLAUDE_CONFIG_DIR` 重定向配置目录(测试注入用)。
196
+
197
+ ## 性能
198
+
199
+ 三级渐进扫描:启动只 stat + 头尾各 64KB 轻扫(<0.2s);消息轮数/worktree 未合并数由后台线程补齐;全文件解析仅在预览时发生且有 LRU 缓存,14MB 会话二次读取 <15ms。
200
+
201
+ ## 开发
202
+
203
+ ```zsh
204
+ python3 -m pytest # 全部单测:离线假数据 + 真 git worktree 集成,不碰真实 ~/.claude
205
+ ```
206
+
207
+ - 包布局 `src/csm_cli/`:`cli.py` 入口/CLI/resume/双开保护 · `scanner.py` 数据层+消息解析(唯一文件 I/O)·
208
+ `ui.py` TUI · `web.py` Web 服务端 · `web.html` Web 前端(单文件,无构建,importlib.resources 读取)·
209
+ `serve.py` 守护进程 · `fmt.py` 纯函数格式化;仓库根 `csm.py` 为兼容 shim
210
+ - `fmt.py` 中 `rel_time()` / `fuzzy_score()` 为故意留空的降级实现(学习场景),实装后 `test_fmt.py` 的 `skipif` 自动生效
211
+ - `web.html` 顶部 CSS 变量可整体换肤;打包见 `pyproject.toml`(hatchling,`csm-cli`)
@@ -0,0 +1,181 @@
1
+ # csm — Claude Code 会话管理器
2
+
3
+ 终端里开了一堆 Claude 会话分不清哪个是哪个?`csm` 一屏列出**全局所有项目**的 Claude 会话——AI 生成的标题、首条输入、运行状态、所属项目、消息轮数、worktree 归属、Session ID——输入即过滤,回车直接 resume。
4
+
5
+ - **只读**:对 `~/.claude` 严格只读,绝不写入或清理用户数据(唯一可写的是 csm 自有的收藏文件)
6
+ - **轻量**:Python ≥ 3.10;`prompt_toolkit`/`rich` 随包安装,开箱即用
7
+ - **发射后不管**:resume 用 `execvp` 接管进程,csm 不持有、不托管任何会话(Web 后台服务除外,见 `serve`)
8
+
9
+ 三种前端:**TUI**(默认,fzf 式体验)、**Web 界面**(`csm serve`,含对话流预览与 diff,可后台守护/开机自启)、**表格/JSON**(`--list`,管道友好)。
10
+
11
+ ## 功能速览
12
+
13
+ | 能力 | TUI | Web | `--list/--json` |
14
+ |---|:-:|:-:|:-:|
15
+ | 全局会话列表 + 即时过滤(多词 AND、`#标签`) | ✅ | ✅ | ✅(管道 grep/jq) |
16
+ | 运行状态(●busy/idle/waiting,pid 三重判活防复用) | ✅ | ✅ | ✅ |
17
+ | ◉本终端标记(tmux 下精确到 pane) | ✅ | ✅ | ✅ |
18
+ | 收藏两档(⭐/★)置顶 + 标签 | ✅ `s` 键 | ✅ 点星/编辑标签 | ✅ 字段输出 |
19
+ | 六档分类过滤(全部/运行中/本终端/收藏/已关闭/单轮) | ✅ `1`-`6` | ✅ chips | — |
20
+ | **worktree 感知**(`repo/wt ⎇分支 +未合并数`) | ✅ | ✅ | ✅ |
21
+ | 对话流预览(Markdown 渲染 + 工具调用折叠) | ✅ Tab 最近 50 条 | ✅ 完整分页 | — |
22
+ | **Edit/Write/MultiEdit 行级 diff**(红删绿增) | — | ✅ 完整级别 | — |
23
+ | **双开保护**(活会话在他终端 → 确认拦截) | ✅ | — | — |
24
+ | 复制 resume 命令(终端/tmux/headless 三变体) | — | ✅ | — |
25
+ | SDK 子进程会话标记(`sdk-cli` → SDK) | ✅ | ✅ | ✅ |
26
+ | **Web 后台守护**(`csm serve start/stop/status`,launchd 开机自启) | — | ✅ | — |
27
+
28
+ ## 安装
29
+
30
+ PyPI 正式分发(包名 `csm-cli`,安装后命令为 `csm`):
31
+
32
+ ```zsh
33
+ pipx install csm-cli # 或:uv tool install csm-cli
34
+ ```
35
+
36
+ 升级 / 卸载:`pipx upgrade csm-cli` / `pipx uninstall csm-cli`(uv 同理 `uv tool upgrade` / `uv tool uninstall`)。
37
+
38
+ 需要 Python ≥ 3.10;`prompt_toolkit`/`rich` 随包自动安装。
39
+
40
+ <details><summary>从源码运行(开发/旧 alias)</summary>
41
+
42
+ ```zsh
43
+ git clone https://github.com/cainli/csm.git && cd csm
44
+ python3 -m pytest # 跑测试
45
+ alias csm="$PWD/csm.py" # 仓库自带的兼容 shim
46
+ ```
47
+
48
+ </details>
49
+
50
+ ## 快速开始
51
+
52
+ ```zsh
53
+ csm # TUI:打字过滤,回车 resume
54
+ csm serve start # 后台起 Web 界面(127.0.0.1:8737,打印 URL)
55
+ csm --list # 终端表格;csm --list --json | jq '.[] | .title'
56
+ ```
57
+
58
+ ## 命令行参数
59
+
60
+ ```zsh
61
+ csm # 交互式 TUI(默认;stdout 非 tty 时自动降级 --list)
62
+ csm --list # 非交互表格
63
+ csm --list --json # JSON 输出,可配 jq
64
+ csm --list --full-scan # 表格带完整消息数(较慢 ~0.6s)
65
+ csm --project voicemouse # 按项目路径过滤(大小写不敏感)
66
+ csm --new [PATH] # 在 PATH(默认当前目录)起新会话,不进列表
67
+ csm --no-cd # resume 时停留在当前目录(默认切到原项目目录)
68
+ csm --limit 50 # 最多列出 50 条(默认全部)
69
+ csm --no-color / --version
70
+ ```
71
+
72
+ ### Web 服务:`csm serve`
73
+
74
+ ```zsh
75
+ csm serve # 前台运行(调试用,端口占用自动顺延,Ctrl-C 停)
76
+ csm serve start # 后台启动(固定 8737,打印 URL;日志 ~/.claude/csm/serve.log)
77
+ csm serve start --port 9000 --open
78
+ csm serve status # running/stopped(pid + 探活)
79
+ csm serve restart
80
+ csm serve stop # SIGTERM 优雅停(5s 超时强杀兜底)
81
+ csm serve install-launchd # macOS 开机自启 + 崩溃自动拉起(launchd KeepAlive)
82
+ csm serve uninstall-launchd
83
+ csm --web # 兼容别名 = csm serve(前台)
84
+ ```
85
+
86
+ launchd 模式日志在 `~/.claude/csm/launchd.{out,err}.log`;停 launchd 管理的服务请用 `uninstall-launchd`(手动 `stop` 会提示)。
87
+
88
+ ## TUI
89
+
90
+ ```
91
+ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星标 Tab预览 ^L清空 ^R重扫 esc退出
92
+ ◉★ 11:20 ●busy 修复登录超时问题 #线上 claude-tools/fleet-features 12 757f8670-…
93
+ 10:29 ●idle Orca 多 Agent 开发环境 swain 8 892a5d70-…
94
+ ```
95
+
96
+ ### 键位
97
+
98
+ | 键 | 列表视图 | 预览视图 |
99
+ |---|---|---|
100
+ | `↑` `↓` / `j` `k`(输入为空时) | 选择 | 滚动消息 |
101
+ | `PgUp` `PgDn` `Home` `End` | 翻页/跳转 | 翻页/顶底 |
102
+ | 直接打字 | 过滤(标题/首输入/项目路径/SID,多词 AND;`#标签` 精确筛) | 同左 |
103
+ | `1`-`6` | **分类过滤**:全部/运行中/本终端/收藏/已关闭/单轮 | — |
104
+ | `s` | **星标循环**:无 → ⭐ → ★ → 无(收藏永久置顶) | — |
105
+ | `Tab` | **进入会话预览**(最近 50 条消息流) | 返回列表(保持原选择) |
106
+ | `Enter` | resume 选中会话(先 cd 到原项目目录;见他终端运行会触发双开确认) | resume 该会话 |
107
+ | `Ctrl-L` / `Ctrl-R` | 清空过滤 / 重新扫描 | 清空 / 刷新预览 |
108
+ | `Esc` / `Ctrl-C` | 退出(码 130) | 返回列表 / 退出 |
109
+
110
+ 列表列:`◉本终端+★收藏 · 活跃时间 · ●运行状态 · 标题(或首条输入)#标签 · 项目 · 轮数 · Session ID`。闭会话若是 SDK 启动显示 `sdk` 标记;worktree 会话项目列显示 `主仓库/worktree名`。
111
+
112
+ 每 30s 静默重扫:新会话自动出现在列表顶部,不打断当前选择与滚动(sid 桥接恢复状态);正在输入过滤词时跳过当轮重扫。
113
+
114
+ ## Web 界面(`csm serve`)
115
+
116
+ 后台常驻(`csm serve start`,关终端不影响;`install-launchd` 开机自启)或前台调试(`csm serve` / 兼容别名 `--web`)。
117
+
118
+ - 左侧列表(搜索 + 分类 chips、NEW/◉本终端/SDK/worktree 徽章、星形按钮、收藏置顶浅色段)+ 右侧对话流
119
+ - **预览两级深度**:摘要(默认)/ 完整;消息按 **Markdown 渲染**(代码块/粗斜体/标题/列表/引用/链接/表格;先转义再白名单转换,免疫 XSS,离线自实现无 CDN)
120
+ - **行级 diff**:完整级别下点击 🔧 Edit/Write/MultiEdit 行展开——红删/绿增/无色上下文,LCS 对齐;MultiEdit 逐段标注
121
+ - **复制命令三变体**:`claude --resume`(终端)/ `tmux new-window -c`(并行恢复,落到原项目目录)/ `claude -p --resume`(headless 续跑)
122
+ - 每 5s 自动轮询(页面隐藏时暂停);深浅色跟随系统;窄窗口(≤860px)自动单栏
123
+ - 消息解析缓存(mtime/size 失效):14MB 会话首次解析 ~几十 ms,二次 <15ms
124
+
125
+ ## 会话生命周期
126
+
127
+ ### 双开保护
128
+
129
+ resume 一个正在**其他终端**运行的会话时,csm 警告并要求确认——两处同时写入同一会话文件(jsonl)可能导致内容交叉错乱。本终端运行的会话不拦;tty 无法识别时宁可误拦。
130
+
131
+ ### `--new`:快速发射
132
+
133
+ `csm --new ~/dev/workspace/swain` 直接在该目录起新会话。与 resume 同为 `execvp` 接管——csm 始终不持有会话进程。
134
+
135
+ ### worktree 感知
136
+
137
+ 会话工作目录是 git worktree 时(EnterWorktree / `git worktree add` 后),读 `.git` 的 gitdir **指针**反解归属(不猜目录名,submodule 不误判),显示 `主仓库/worktree名 ⎇分支 +未合并提交数`:
138
+
139
+ - jsonl 的 `cwd` 逐行随 cd 变化——检测用**最后一条 cwd**(会话当前所在);`project_path`(第一条 cwd,出生地)语义不变
140
+ - 未合并数由后台线程跑 `git rev-list --count` 补齐(超时 2s 静默降级)
141
+ - 全程只读:不创建、不清理任何 worktree
142
+
143
+ ## 收藏与标签
144
+
145
+ - 存储在 `~/.claude/csm/favorites.json`(csm 自有命名空间,唯一可写文件;原子写 + 跨进程锁)
146
+ - 星标两档:⭐ 普通收藏 / ★ 重要;永久置顶(★ 段前于 ⭐ 段,段内按活跃时间)
147
+ - 标签在 Web 详情栏添加;搜索 `#标签名` 精确筛(多标签 AND);TUI 与 Web 双向同步(≤30s)
148
+
149
+ ## 分类口径(诚实声明)
150
+
151
+ - **运行状态**:busy/idle/waiting 来自 Claude 活跃注册表,pid 三重判活(存活 + 进程名含 claude + 启动时间容差比对)防 pid 复用;已关闭 = jsonl 在而注册表无活记录
152
+ - **本终端**:会话进程 tty == csm 进程 tty(tmux 下精确到 pane);被 GUI 嵌套调用时可能无法识别,过滤器自动降级
153
+ - **单轮**:恰 1 条用户输入的会话。`claude -p` 无法从官方数据可靠识别(`entrypoint` 对交互与 `-p` 同为 `cli`),「单轮」是最接近的客观特征;SDK 子进程(`sdk-cli`)可识别并标记 SDK
154
+
155
+ ## 数据来源(只读)
156
+
157
+ | 路径 | 用途 |
158
+ |---|---|
159
+ | `~/.claude/projects/*/*.jsonl` | 会话转录;文件名即 Session ID;标题取最后一条 `ai-title`;行内 `cwd`/`entrypoint` |
160
+ | `~/.claude/sessions/*.json` | 运行中会话注册表 → 状态 + tty 关联 |
161
+ | `~/.claude/history.jsonl` | 无标题会话的首条输入回退 |
162
+ | `~/.claude/csm/favorites.json` | **csm 自有**:收藏与标签(唯一可写) |
163
+
164
+ 进程信息:单次 `ps -axo pid,ppid,tty,lstart,command` 快照三用(会话 tty / 进程名校验防 pid 回绕 / PPID 链上溯识别本终端)。
165
+ 支持 `CLAUDE_CONFIG_DIR` 重定向配置目录(测试注入用)。
166
+
167
+ ## 性能
168
+
169
+ 三级渐进扫描:启动只 stat + 头尾各 64KB 轻扫(<0.2s);消息轮数/worktree 未合并数由后台线程补齐;全文件解析仅在预览时发生且有 LRU 缓存,14MB 会话二次读取 <15ms。
170
+
171
+ ## 开发
172
+
173
+ ```zsh
174
+ python3 -m pytest # 全部单测:离线假数据 + 真 git worktree 集成,不碰真实 ~/.claude
175
+ ```
176
+
177
+ - 包布局 `src/csm_cli/`:`cli.py` 入口/CLI/resume/双开保护 · `scanner.py` 数据层+消息解析(唯一文件 I/O)·
178
+ `ui.py` TUI · `web.py` Web 服务端 · `web.html` Web 前端(单文件,无构建,importlib.resources 读取)·
179
+ `serve.py` 守护进程 · `fmt.py` 纯函数格式化;仓库根 `csm.py` 为兼容 shim
180
+ - `fmt.py` 中 `rel_time()` / `fuzzy_score()` 为故意留空的降级实现(学习场景),实装后 `test_fmt.py` 的 `skipif` 自动生效
181
+ - `web.html` 顶部 CSS 变量可整体换肤;打包见 `pyproject.toml`(hatchling,`csm-cli`)
@@ -0,0 +1,53 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "csm-cli"
7
+ dynamic = ["version"]
8
+ description = "Claude Code 会话管理器:一屏浏览/过滤/收藏全部会话,回车 resume;TUI + 本地 Web 界面"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ authors = [{ name = "cainli" }]
13
+ keywords = ["claude", "claude-code", "session", "manager", "cli", "tui"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Environment :: Console",
17
+ "Environment :: Web Environment",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: MacOS",
20
+ "Operating System :: POSIX",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Programming Language :: Python :: 3.14",
27
+ "Topic :: Software Development",
28
+ "Topic :: Utilities",
29
+ ]
30
+ dependencies = [
31
+ "prompt_toolkit>=3.0",
32
+ "rich>=13",
33
+ ]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/cainli/csm"
37
+ Issues = "https://github.com/cainli/csm/issues"
38
+ Changelog = "https://github.com/cainli/csm/blob/main/CHANGELOG.md"
39
+
40
+ [project.scripts]
41
+ csm = "csm_cli.cli:main"
42
+
43
+ [tool.hatch.version]
44
+ path = "src/csm_cli/__init__.py"
45
+
46
+ [tool.hatch.build.targets.wheel]
47
+ packages = ["src/csm_cli"]
48
+
49
+ [tool.hatch.build.targets.sdist]
50
+ include = ["src/csm_cli", "test_*.py", "README.md", "CHANGELOG.md", "LICENSE"]
51
+
52
+ [tool.pytest.ini_options]
53
+ pythonpath = ["src"]
@@ -0,0 +1,7 @@
1
+ """csm_cli — Claude Code 会话管理器(csm 命令)。
2
+
3
+ TUI / Web / 表格三种前端,详见 README。版本号单一来源在本文件,
4
+ pyproject.toml 通过 hatch dynamic version 读取。
5
+ """
6
+
7
+ __version__ = "0.1.0"
@@ -0,0 +1,8 @@
1
+ """python -m csm_cli 支持(serve daemon 也用它派生子进程)。"""
2
+
3
+ import sys
4
+
5
+ from csm_cli.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())