# ccm

**Repository Path**: xiaoerlangqqq/ccm

## Basic Information

- **Project Name**: ccm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: claude, session

## README

# CCM - Claude Code Session Manager

一个 k9s 风格的终端 UI 工具，用于管理 Claude Code 的历史会话。

## 功能特点

- **交互式 TUI**: k9s 风格的终端界面，支持键盘导航
- **项目视图**: 列出所有 Claude Code 项目，显示会话数量、最后活动时间、占用空间
- **会话视图**: 深入每个项目查看会话列表，含摘要、状态、时间
- **批量删除**: Space 多选会话，x 一键清理所有关联数据
- **日志查看**: less 风格滚动查看会话完整对话记录，支持 Windows 终端
- **实时过滤**: / 键进入过滤模式，输入文本实时筛选表格数据
- **会话排序**: s/S 键按不同列排序，支持升降序
- **详情弹窗**: 查看会话的详细信息
- **CLI 模式**: 支持命令行快速查看状态、列出项目/会话、删除会话
- **跨平台**: 支持 macOS、Linux、Windows（颜色方案针对 Windows 16 色终端优化）

## 安装

```bash
# npm
npm install -g @wangxiaoerqqq/ccm

# 或使用 pnpm
pnpm add -g @wangxiaoerqqq/ccm
```

## 使用

### TUI 模式

```bash
ccm                  # 启动交互式 TUI
```

### CLI 模式

```bash
ccm status           # 查看环境概览（项目数、会话数、生命周期分布、Top 5 项目）
ccm status --json    # JSON 格式输出

ccm projects         # 列出所有项目
ccm projects --json  # JSON 格式输出

ccm sessions [project]   # 列出会话，可选按项目名筛选
ccm sessions --json      # JSON 格式输出

ccm delete <id>      # 删除会话（支持 sessionId 精确匹配 + 标题搜索）
ccm delete <id> -f   # 跳过确认，直接删除

# 别名删除示例（按项目名分组合并展示）
ccm delete "会话标题"

ccm --help           # 查看帮助
ccm --version        # 查看版本
```

## 键盘快捷键

### Projects 视图

| 键 | 功能 |
|----|------|
| `↑↓` / `j k` | 导航项目列表 |
| `PgUp` / `PgDn` | 翻页 |
| `g` / `G` | 跳到顶部 / 底部 |
| `Enter` | 进入项目，查看会话 |
| `s` / `S` | 切换排序列 / 切换排序方向（不排序 → 降序 → 升序） |
| `r` | 刷新数据 |
| `/` | 过滤项目（按路径实时过滤） |
| `q` | 退出 |

### Sessions 视图

| 键 | 功能 |
|----|------|
| `↑↓` / `j k` | 导航会话列表 |
| `PgUp` / `PgDn` | 翻页 |
| `g` / `G` | 跳到顶部 / 底部 |
| `Space` | 选中 / 取消选中会话 |
| `d` | 查看会话详情 |
| `l` | 查看会话完整日志 |
| `s` / `S` | 切换排序列 / 切换排序方向（不排序 → 降序 → 升序） |
| `r` | 刷新数据 |
| `/` | 过滤会话（按 ID / 摘要实时过滤） |
| `x` | 删除已选中会话（需确认） |
| `Esc` | 返回 Projects 列表 |
| `q` | 退出 |

### 日志视图

| 键 | 功能 |
|----|------|
| `↑↓` / `j k` | 逐行滚动 |
| `PgUp` / `PgDn` / `C-u` / `C-d` | 翻页 |
| `g` / `G` / `Home` / `End` | 跳到开头 / 结尾 |
| `Esc` | 返回 Sessions 列表 |
| `q` | 退出 |

## 会话状态

每个会话根据其活跃程度显示不同的生命周期状态：

| 图标 | 状态 | 含义 |
|------|------|------|
| ● | `active` | 最近 **15 分钟**内有活动 |
| ◐ | `idle` | 15 分钟 ~ 24 小时前有活动，或有活跃进程标记 |
| ○ | `completed` | 超过 **24 小时**无活动 |
| ▲ | `stale` | 会话文件不可靠（损坏或不完整） |

## 删除会话

删除会话时会清理以下所有关联数据：

- 会话对话记录（`~/.claude/projects/{slug}/{sessionId}.jsonl`）
- 会话子数据目录（subagents 等）
- 会话环境数据（`~/.claude/session-env/{sessionId}/`）
- 文件历史（`~/.claude/file-history/{sessionId}/`）
- 会话元信息（`~/.claude/sessions/{pid}.json`）
- 历史记录（`~/.claude/history.jsonl` 中对应条目）

### TUI 删除

在 Sessions 视图中按 `Space` 选中会话，按 `x` 触发删除确认。

### CLI 删除

```bash
ccm delete <sessionId>       # 按 sessionId 精确删除
ccm delete <alias>           # 按会话标题搜索删除（支持自定义标题 + AI 生成标题）
ccm delete <id> -f           # 跳过确认，直接删除
```

**别名删除确认展示**：
当通过别名匹配到多个会话时，会按项目名分组合并展示 sessionId 列表：

```
通过别名 "标题" 匹配到 3 个会话:
  -Users-wangxiaoer-IdeaProjects-ccd:
    session-id-1
    session-id-2
  -Users-wangxiaoer-IdeaProjects-ccm:
    session-id-3
确认删除? (y/N)
```

⚠️ 删除操作不可撤销！

## 开发

```bash
# 克隆仓库
git clone https://gitee.com/xiaoerlangqqq/ccm.git
cd ccm

# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 本地链接（开发调试）
npm link
ccm
```

## 技术栈

- TypeScript
- [blessed](https://github.com/chjj/blessed) — 终端 TUI 框架
- Commander — CLI 命令行解析
- Vitest — 单元测试

## 架构特点

- **文件系统驱动**: Slug ↔ 路径映射基于文件系统实际数据（.jsonl 的 `cwd` 字段），不依赖有损字符转换
- **并发优化**: 项目扫描、会话删除等操作支持并发执行，显著提升性能
- **跨平台兼容**: 颜色方案针对 Windows 16 色终端优化，使用纯 ASCII 标签避免布局偏移
- **错误隔离**: 单个文件/会话读取失败不影响其他文件，确保系统稳定性

## 许可证

MIT License