Skip to main content

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.py TUI · web.py Web 服务端 · web.html Web 前端(单文件,无构建,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.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for csm-cli 0.3.0
File Size Uploaded Provenance Actions
csm_cli-0.3.0.tar.gz 80.0 kB Without provenance Details for csm_cli-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for csm-cli 0.3.0
File Interpreter ABI Platform Actions
csm_cli-0.3.0-py3-none-any.whl Python 3 none any Details for csm_cli-0.3.0-py3-none-any.whl

Total release size: 151.2 kB

Release files / csm_cli-0.3.0.tar.gz

Download URL csm_cli-0.3.0.tar.gz
Size 80.0 kB
Tags Source
SHA-256 checksum
How to use checksums
891b13743c296991578b891f3709934309bb8909200e9169f2f4789558838e2d
BLAKE2b-256 checksum
How to use checksums
ac1bd10f5cf4f4176d4569750fe545279270219a65f189a75b4e3d2a14a977b0
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.0-py3-none-any.whl

Download URL csm_cli-0.3.0-py3-none-any.whl
Size 71.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
80395e3582edde6f8af346ded749bb0c35481f059d56d198d4a1deb38e40b1ff
BLAKE2b-256 checksum
How to use checksums
0e7568b8c6ef219d4071a70994183c488a6bd26fe6990bd1015878ce79380a49
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.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page