Claude 任务查看器

一个用于观察 Claude Code 任务的实时看板（Kanban）。查看 Claude 正在处理什么，跟踪任务之间的依赖关系，并管理任务清理和优先级。

为什么要使用？

当 Claude Code 将复杂工作分解为任务时，你可以了解其思考过程——但仅限于终端（Terminal）中。Claude 任务查看器为你提供一个持久化的可视化仪表板（Dashboard），用于：

• 一览全局 —— 所有会话和任务集中在一个地方
• 知晓当前动态 —— 实时更新（Live Updates）显示 Claude 在所有会话中的确切操作
• 理解任务依赖 —— 查看哪些任务被阻塞以及是什么阻碍了它们
• 接收通知 —— 任务完成时发送桌面通知（Desktop notifications）和声音提示
• 可视化时间线 —— 时间线视图以甘特图（Gantt）风格展示任务持续时间
• 保持整洁 —— 过期会话自动归档以保持侧边栏整洁
• 清理已完成的工作 —— 不再需要时删除任务（含依赖检查）

主要功能

以观察为核心的设计

Claude Code 控制任务状态 —— 查看器向你展示正在发生的事情：

• 实时状态 —— 查看任务随着 Claude 工作从“待处理（Pending）”到“进行中（In Progress）”再到“已完成（Completed）”的流转
• 活跃会话检测 —— 指示器显示哪些会话有进行中的任务
• 任务依赖 —— 可视化 blockedBy/blocks 关系以理解关键路径
• 实时活动流 —— 每个会话中所有进行中任务的实时流

桌面与声音通知

• 标题栏中的铃铛图标可切换通知开启/关闭（跨会话持久化）
• 桌面通知在任务从“进行中”变为“已完成”时触发 —— 点击可跳转至该任务
• **音频提示音（Audio chime）**伴随桌面通知播放简短的双音调（C5→E5）
• 首次启用时需要浏览器通知权限

会话时间线

• 标题栏中的看板/时间线切换可在看板与甘特图风格图表之间切换
• 任务以水平条显示，从创建到最后更新，按状态着色
• 时间轴自动缩放 —— 根据会话跨度显示秒、分钟、小时或天
• 悬停查看确切时间戳和持续时间；点击打开详情面板
• 视图偏好保存在 localStorage（本地存储）中

自动归档过期会话

• 没有进行中任务且超过 7 天未修改的会话折叠进**已归档（Archived）**部分
• 默认折叠 —— 点击展开。展开/折叠状态在重载间持久化
• 搜索或使用“仅活跃（Active Only）”过滤器时仍会显示已归档会话

清理操作

• 删除任务 —— 使用删除按钮或按 D 键移除任务（包含依赖安全检查）
• 批量删除 —— 一次性删除会话中的所有任务

会话管理

查看并组织你的 Claude Code 会话：

• 会话发现 —— 自动查找 ~/.claude/tasks/ 和 ~/.claude/projects/ 中的所有会话
• 查看项目路径 —— 查看每个项目的完整文件系统路径
• 模糊搜索 —— 跨会话名称、任务描述和项目路径搜索，即时过滤
• 会话限制 —— 过滤仅显示活跃会话或特定数量的最近会话

键盘快捷键

• ? —— 显示所有键盘快捷键的帮助
• D —— 删除当前选中的任务（带确认和依赖检查）
• Esc —— 关闭详情面板或模态框（modals）

安装

快速开始

npx claude-task-viewer

打开 http://localhost:3456

从源码构建

git clone https://github.com/L1AD/claude-task-viewer.git
cd claude-task-viewer
npm install
npm start

工作原理

Claude Code 将任务存储在 ~/.claude/tasks/。每个会话都有独立的文件夹：

~/.claude/tasks/
  └── {session-uuid}/
      ├── 1.json
      ├── 2.json
      └── ...

查看器监视此目录并通过 Server-Sent Events（服务器发送事件）推送更新。更改立即出现 —— 无需轮询，无需刷新。

任务结构

{
  "id": "1",
  "subject": "Implement user authentication",
  "description": "Add JWT-based auth with refresh tokens",
  "activeForm": "Setting up auth middleware",
  "status": "in_progress",
  "blocks": ["2", "3"],
  "blockedBy": []
}

• activeForm —— Claude 当前正在做什么（显示在实时更新中）
• blocks / blockedBy —— 任务依赖关系

配置

# Custom port
PORT=8080 npx claude-task-viewer

# Open browser automatically
npx claude-task-viewer --open

# Use a different Claude config directory (for multiple accounts)
npx claude-task-viewer --dir=~/.claude-work

API

端点	方法	描述
/api/sessions	GET	列出所有会话及任务计数
/api/sessions/:id	GET	获取会话的所有任务
/api/tasks/all	GET	获取所有会话的所有任务
/api/tasks/:session/:task	DELETE	删除任务（检查依赖）
/api/tasks/:session/:task/note	POST	向任务添加备注
/api/events	GET	SSE 流用于实时更新

设计理念

观察优于控制：Claude Code 拥有任务状态。任务查看器的作用是向你展示 Claude 正在做什么，而不是指挥它。这确保查看器与现实同步，并防止混淆任务状态是反映 Claude 的实际操作还是仅仅反映人类意图。

有限的交互：你可以删除任务和添加备注，但任务状态、主题和描述反映 Claude 的实际工作，只能由 Claude Code 本身更改。

路线图

✅ 已完成

• 实时观察 —— 实时更新流显示 Claude 在所有会话中的操作
• 任务依赖 —— 可视化 blockedBy/blocks 关系
• 任务删除 —— 带依赖检查的任务删除
• 键盘快捷键 —— ?, D, Esc 用于快速操作
• 会话发现 —— 自动检测所有 Claude Code 会话
• 搜索 —— 跨会话和任务搜索
• 桌面通知 —— 任务完成时的通知和音频提示音
• 任务时间线 —— 显示任务创建和完成时间的甘特图风格视图
• 会话归档 —— 过期会话自动折叠进归档部分

🚧 计划中

• 增强的搜索与过滤 —— 按状态、依赖、日期范围过滤
• 导出 —— 导出数据用于分析或报告

提交问题 提出想法或反馈。

许可证

MIT

claude-task-viewer 快速上手指南

claude-task-viewer 是一款专为 Claude Code 设计的实时看板工具。它允许你在浏览器中直观地观察任务状态、追踪依赖关系并管理任务清理，无需在终端中频繁切换查看。

环境准备

在使用本工具前，请确保您的开发环境满足以下要求：

• 操作系统：支持 macOS、Linux 或 Windows（需支持 Node.js）。
• 前置依赖：已安装 Node.js 环境。
• 核心依赖：本地已安装并配置好 Claude Code（工具会自动读取 ~/.claude/tasks/ 目录下的数据）。

安装步骤

推荐使用 npx 方式快速启动，无需手动克隆仓库。

方式一：快速启动（推荐）

直接通过 npm 运行：

npx claude-task-viewer

方式二：从源码安装

如需自定义修改或调试，可克隆项目源码：

git clone https://github.com/L1AD/claude-task-viewer.git
cd claude-task-viewer
npm install
npm start

注意：国内用户若 git clone 速度较慢，建议使用 Git 镜像源加速。

基本使用

安装完成后，工具默认会在本地启动 Web 服务。

1. 访问界面

打开浏览器访问以下地址：

http://localhost:3456

2. 功能概览

• 实时看板：自动发现 ~/.claude/tasks/ 下的所有会话，展示任务状态流转（Pending → In Progress → Completed）。
• 依赖可视化：查看任务间的阻塞关系（blocks/blockedBy）。
• 通知提醒：任务完成时触发桌面通知及提示音（需在浏览器授权通知权限）。
• 时间轴视图：切换至 Gantt 风格图表查看任务耗时。

3. 常用配置

可通过命令行参数调整运行行为：

# 指定端口
PORT=8080 npx claude-task-viewer

# 启动后自动打开浏览器
npx claude-task-viewer --open

# 指定不同的 Claude 配置文件目录
npx claude-task-viewer --dir=~/.claude-work

4. 键盘快捷键

在界面中可使用以下快捷键提升效率：

快捷键	功能
?	显示帮助信息（列出所有快捷键）
D	删除当前选中的任务（含依赖检查）
Esc	关闭详情面板或弹窗