cover

Claude Task Viewer 完整指南：实时可视化 Claude Code 任务执行的开源工具

当 Claude Code 处理复杂任务时，你是否想知道它到底在做什么？Claude Task Viewer 让 AI 的思考过程变得透明可见。

为什么需要任务可视化？

使用 Claude Code 处理复杂项目时，你可能遇到过这些困扰：

  • 终端里只能看到零散的任务片段，无法把握全局进度
  • 不知道 Claude 当前在执行哪个具体操作
  • 任务之间的依赖关系不清晰，难以判断阻塞原因
  • 任务完成时没有明确提示，需要频繁查看终端

Claude Task Viewer（作者 @L1AD）是一个开源工具，专门解决这些痛点。

核心功能

1. 实时任务看板

工具在本地 3456 端口启动一个 Web 看板，自动扫描 ~/.claude/tasks/ 目录下的所有会话。每个任务以卡片形式展示：

  • 任务状态：待处理、进行中、已完成
  • 当前操作：显示 Claude 正在执行的具体动作（通过 activeForm 字段）
  • 依赖关系：可视化任务的 blocks 和 blockedBy 关系

2. 桌面通知

任务从"进行中"变为"已完成"时：

  • 播放 C5 到 E5 的音效提示
  • 弹出桌面通知
  • 无需盯着终端，专注其他工作

3. 时间线视图

类似甘特图的时间线模式，展示：

  • 每个任务的持续时间
  • 任务执行的时间分布
  • 帮助分析效率瓶颈

4. 智能归档

闲置超过 7 天的会话自动归档，保持界面整洁。

设计理念：观察优于控制

Claude Task Viewer 采用"只读"设计：

  • 不干预任务状态：看板只显示 Claude 实际在做什么，不允许手动修改任务
  • 避免状态混淆：人为操作和 AI 执行之间不会产生冲突
  • 实时同步：通过监视文件系统变化并推送 Server-Sent Events 实现毫秒级更新

这种设计确保了数据的准确性和一致性。

技术实现

任务数据结构

工具解析 ~/.claude/tasks/ 目录下的 JSON 文件，提取关键字段：

{
  "id": "task-123",
  "subject": "重构用户认证模块",
  "status": "in_progress",
  "activeForm": "正在重构认证逻辑",
  "blocks": ["task-124"],
  "blockedBy": []
}

实时更新机制

  • 使用文件系统监视器（如 chokidar）检测任务文件变化
  • 通过 Server-Sent Events (SSE) 推送更新到浏览器
  • 前端接收事件后立即刷新对应任务卡片

依赖关系映射

  • blocks 字段：当前任务完成后才能解锁的任务
  • blockedBy 字段：必须等待完成的前置任务
  • 看板用箭头或颜色标识依赖关系

快速开始

安装

使用 npx 一键启动（无需全局安装）：

npx claude-task-viewer

默认在 http://localhost:3456 打开看板。

自定义配置

指定端口：

npx claude-task-viewer --port 8080

多账户支持：

npx claude-task-viewer --tasks-dir /path/to/custom/tasks

键盘快捷键

  • d：删除任务（带依赖检查）
  • h 或 ?：查看帮助
  • t：切换时间线视图

实际使用场景

场景 1：并行多任务管理

使用 Git Worktree 多会话 时，Claude Task Viewer 可以在一个看板中同时监控所有会话的任务状态。

场景 2：复杂重构项目

当 Claude Code 处理涉及 10+ 文件的重构时，看板清晰展示：

  • 哪些文件已处理完成
  • 当前正在处理哪个文件
  • 哪些任务因依赖关系被阻塞

场景 3：团队协作

团队成员可以通过看板了解 Claude Code 的工作进度，无需频繁询问"AI 做到哪一步了"。

常见问题

Q: 支持其他 AI 编码助手吗？

A: 目前专注于 Claude Code，因为任务数据结构是 Claude Code 特有的。未来可能扩展支持。

Q: 任务 ID 映射如何处理重试和子任务？

A: 工具通过解析会话文件夹中的 JSON 文件，识别任务的唯一 ID，避免重复创建卡片。子任务会显示为独立卡片，并通过 blockedBy 字段关联父任务。

Q: 看板数据会保存吗？

A: 看板是实时读取 ~/.claude/tasks/ 目录的数据，不额外存储。归档的会话数据仍保留在原目录中。

总结

核心优势：

  • ✅ 实时可视化 Claude Code 任务执行过程
  • ✅ 清晰展示任务依赖关系和阻塞原因
  • ✅ 桌面通知 + 音效提示任务完成
  • ✅ 开源免费，MIT 协议

适用人群：

  • 使用 Claude Code 处理复杂项目的开发者
  • 需要监控多个并行会话的团队
  • 希望深入了解 AI 工作流程的技术爱好者

相关推荐阅读

关于订阅选项

如果你需要使用 Claude Code，可以选择官方订阅或拼车服务（如 Easy Claude Code 等）。Easy Claude Code 提供经济实惠的订阅方案。了解更多