csm — Claude Code 会话管理器
终端里开了一堆 Claude 会话分不清哪个是哪个?csm 一屏列出全局所有项目的 Claude 会话——AI 生成的标题、首条输入、运行状态、所属项目、消息轮数、worktree 归属、Session ID——输入即过滤,回车直接 resume。
- 只读:对
~/.claude用户数据严格只读,绝不写入或清理(仅可写 csm 自有的~/.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(红删绿增) | — | ✅ 完整级别 | — |
| 双开保护(活会话在他终端 → 确认拦截) | ✅ | — | — |
跳转 g(直达会话所在终端:tmux switch-client/attach · iTerm2/Terminal 聚焦) |
✅ | — | — |
会话进度(TodoWrite 3/7 快照 + 📋 plan 文档关联) |
✅ 徽标/预览清单 | ✅ 徽标/详情清单 | ✅ 字段 |
跨会话全文检索(?词1 词2 / --full-text;FTS5 trigram,中文 2 字可搜,会话级 AND) |
✅ footer 摘要 | ✅ 行内摘要 | ✅ 表格/JSON |
| 复制 resume 命令(终端/tmux/headless 三变体) | — | ✅ | — |
SDK 子进程会话标记(sdk-cli → SDK) |
✅ | ✅ | ✅ |
Web 后台守护(csm serve start/stop/status,launchd 开机自启) |
— | ✅ | — |
安装
PyPI 正式分发(包名 csm-cli,安装后命令为 csm):
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 随包自动安装。
从源码运行(开发/旧 alias)
git clone https://github.com/cainli/csm.git && cd csm
python3 -m pytest # 跑测试
alias csm="$PWD/csm.py" # 仓库自带的兼容 shim
快速开始
csm # TUI:打字过滤,回车 resume
csm serve start # 后台起 Web 界面(127.0.0.1:8737,打印 URL)
csm --list # 终端表格;csm --list --json | jq '.[] | .title'
命令行参数
csm # 交互式 TUI(默认;stdout 非 tty 时自动降级 --list)
csm --list # 非交互表格
csm --list --json # JSON 输出,可配 jq
csm --full-text "登录超时" # 跨会话全文检索(首次自动建索引 ~2s,之后增量)
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
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星标 g跳转 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 |
星标循环:无 → ⭐ → ★ → 无(收藏永久置顶) | — |
g |
跳转到会话所在终端(见下) | — |
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 无法识别时宁可误拦。
跳转 g:会话在哪,就去哪
双开保护的另一半答案:不另起一份,而是直达会话正在运行的终端。按目标环境自动选择(全部只读查询):
- 会话在 tmux(任意 session):按 tty 反查 pane。csm 自己也在 tmux →
switch-client瞬移(csm 存活,随时切回列表);不在 →execvp让位给tmux attach(resume 同款哲学) - 会话在 iTerm2 / Terminal.app:AppleScript 按 tty 找到 tab/窗口并置前
- 都不是:降级提示 tty(
fmt.fallback_location_hint)
--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)
全文检索
「那个讨论 SSE 重连的会话在哪?」——元数据过滤够不着消息正文时,用 ? 前缀进入全文模式:
- TUI:直接输入
?词1 词2——结果按命中数降序,footer 显示首条命中摘要;与数字键分类过滤叠加 - Web:搜索框
?词——命中行内联摘要(accent 色),按命中数重排,退出?模式即恢复置顶序 - CLI:
csm --full-text "词1 词2"(--json同样适用,管道友好)
机制:sqlite FTS5 trigram 增量索引(stdlib,零新依赖):
- 索引存
~/.claude/csm/index.db(csm 自有可写区,与 favorites 同级);消息级文本 = 用户输入 / assistant 文本 / 工具名+摘要+结果摘要 - 会话级 AND:多词可命中不同消息,会话须命中所有词;子串匹配,中文 2 字词可搜(trigram 表上 LIKE,≥3 字符自动走索引)
- 失效粒度文件 (mtime, size):TUI 30s 重扫 / Web 5s 空闲轮增量重建,实测 86 会话 / 208MB 全量首建 1.4s,查询 <60ms
- FTS5 不可用的环境整体降级(
?搜索返回空并提示),不影响其他功能
分类口径(诚实声明)
- 运行状态: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 自有:收藏与标签(可写) |
~/.claude/csm/index.db |
csm 自有:全文检索 FTS5 索引(可写,自动维护) |
~/.claude/plans/*.md |
plan mode 文档;经 jsonl 行内 attachment.planFilePath 关联(只读) |
进程信息:单次 ps -axo pid,ppid,tty,lstart,command 快照三用(会话 tty / 进程名校验防 pid 回绕 / PPID 链上溯识别本终端)。
支持 CLAUDE_CONFIG_DIR 重定向配置目录(测试注入用)。
性能
三级渐进扫描:启动只 stat + 头尾各 64KB 轻扫(<0.2s);消息轮数/worktree 未合并数由后台线程补齐;全文件解析仅在预览时发生且有 LRU 缓存,14MB 会话二次读取 <15ms。
开发
python3 -m pytest # 全部单测:离线假数据 + 真 git worktree 集成,不碰真实 ~/.claude
- 包布局
src/csm_cli/:cli.py入口/CLI/resume/双开保护 ·scanner.py数据层+消息解析(唯一文件 I/O)·ui.pyTUI ·web.pyWeb 服务端 ·web.htmlWeb 前端(单文件,无构建,importlib.resources 读取)·serve.py守护进程 ·fmt.py纯函数格式化 ·ftsearch.py全文检索(FTS5 索引);仓库根csm.py为兼容 shim fmt.py中rel_time()/fuzzy_score()为故意留空的降级实现(学习场景),实装后test_fmt.py的skipif自动生效web.html顶部 CSS 变量可整体换肤;打包见pyproject.toml(hatchling,csm-cli)
Metadata
Release files for csm-cli 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| csm_cli-0.3.1.tar.gz | 82.5 kB | Without provenance | Details for csm_cli-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| csm_cli-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for csm_cli-0.3.1-py3-none-any.whl |
Total release size: 154.6 kB
Release files / csm_cli-0.3.1.tar.gz
| Download URL | csm_cli-0.3.1.tar.gz |
|---|---|
| Size | 82.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f586b5fe4291cd411830d6bfffb967d9f9dcdc20984915b13cab0f492b4e8f74
|
|
BLAKE2b-256 checksum How to use checksums |
3fad620281ef58b29f055f7f338c98c2a953d03d92951c4da5ce19ba3c83f6b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / csm_cli-0.3.1-py3-none-any.whl
| Download URL | csm_cli-0.3.1-py3-none-any.whl |
|---|---|
| Size | 72.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
368ea1d2bbae7d43229398392310fc65d93e2e18e910c20128593f893f666a62
|
|
BLAKE2b-256 checksum How to use checksums |
6ff977d9421b8624e2d294279cd4c5d033f83311021ce8e31089f489bc1b02f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for csm-cli 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.