Shadowzzh

README.zh-CN.md

README.zh-CN.md

ccpeek

终端下的 Claude Code 进程查看器

English | 简体中文

查看进程、读取会话、清理卡死实例

快速开始 • 功能特性 • 命令 • 工作原理 • 隐私与安全 • 常见问题 • 故障排查 • 卸载 • 路线图

为什么需要 ccpeek?

同时运行多个 Claude Code 会话很快就会变得混乱。

  • ps / top 只显示 PID,看不到 Claude 任务实际在做什么
  • 在 ~/.claude/projects/ 里翻找文件既慢又与实时进程状态脱节
  • 清理卡死的实例比应该的更麻烦

ccpeek 把进程状态、会话内容和清理操作整合到一个终端工作流中。

为什么不直接用 ps 或手动检查 ~/.claude?

方法 适合 缺少
ps / top 查看运行中的进程 无法知道 Claude 会话实际在做什么
手动检查 ~/.claude 读取存储的会话文件 慢、碎片化、与实时进程状态脱节
ccpeek 进程 + 会话 + 清理一体化工作流 仅专注于 Claude Code 工作流

快速开始

npm install -g @zhangziheng/claude-peek
ccpeek setup
ccpeek

功能特性

  • 列出所有 Claude Code 进程及项目路径
  • 在终端查看实时会话消息
  • 直接终止卡死的实例
  • 进程结束后按项目浏览历史会话
  • 导出对话为 Markdown

命令

交互模式

ccpeek

快捷键:

  • ↑/k ↓/j - 上下移动
  • Enter - 查看会话对话
  • v - 查看进程详情
  • d - 删除进程
  • r - 刷新
  • q/Esc - 退出

查看进程详情:

查看会话对话:

命令行模式

ccpeek list              # 列出所有进程
ccpeek list --json       # JSON 输出
ccpeek show <pid>        # 查看进程详情
ccpeek messages <pid>    # 查看会话对话
ccpeek kill <pid>        # 杀掉进程

messages 支持多种输入方式:

# 方式 1: 使用 PID(运行中的进程)
ccpeek messages 12345

# 方式 2: 使用项目路径(运行中或历史会话)
ccpeek messages /path/to/project

# 方式 3: 指定历史会话 ID
ccpeek messages /path/to/project abc123-session-id

输出选项:

ccpeek messages 12345           # 终端彩色输出
ccpeek messages 12345 --md      # Markdown 输出到 stdout
ccpeek messages 12345 --save    # 保存为文件
ccpeek messages 12345 --copy    # 复制到剪贴板

工作原理

ccpeek 通过 Claude Code hooks 建立 PID ↔ SessionID 映射,然后从 ~/.claude/projects/ 读取会话数据。

流程:

  1. SessionStart hook 捕获 PID 和 SessionID
  2. 映射存储在 ~/.claude/ccpeek/session-mappings.jsonl
  3. ccpeek 读取进程列表 + 映射 + 会话文件

隐私与安全

[✓] 仅本地      - 只读取 ~/.claude 文件
[✓] 不上传      - 零数据外传
[✓] 最小化 hooks - 仅记录 PID/SessionID 映射
[✓] 易卸载      - ccpeek uninstall 清理所有内容

常见问题

Q: 会修改我的 Claude Code 配置吗? A: 只在 .claude/hooks/ 添加 hooks,不动原有配置。

Q: 进程结束后还能看会话吗? A: 可以,使用 ccpeek messages /path/to/project

Q: 如果 hooks 安装失败怎么办? A: ccpeek 仍可查看已有会话,只是无法追踪新的 PID。

Q: 能在远程服务器上用吗? A: 可以,只要那里运行了 Claude Code。

故障排查

Hook 安装失败:

# 检查 Claude Code 目录
ls ~/.claude/hooks/

# 重新安装
ccpeek uninstall
ccpeek setup

找不到会话:

# 验证会话文件存在
ls ~/.claude/projects/

# 检查映射文件
cat ~/.claude/ccpeek/session-mappings.jsonl

权限被拒绝:

# 修复权限
chmod +x ~/.claude/hooks/*.sh

卸载

ccpeek uninstall
npm uninstall -g @zhangziheng/claude-peek

路线图

  • 远程机器支持