ClaudeTime
前身为ClaudeTimeMCP -使用钩子和直接SQLite报告对Claude Code CLI会话进行自动时间跟踪。
⚠️ 重要更改（v2.0.0）： 此项目已重命名为 ClaudeTimeMCP 到 ClaudeTime 并且MCP服务器已被移除。由于读取工具的限制（256KB），MCP层被证明是不切实际的，在使用几天后（~500KB，5000+行）就无法处理活动导出。所有功能现在都使用直接的SQLite脚本，没有任何限制。看 更改日志.md 了解详情。
特性
- 自动时间跟踪：Hooks日志会话自动开始/结束
- 活动监控：跟踪工具使用情况、消息和响应
- 智能工期计算：限制空闲时间以获得准确的活动时间
- 基于项目的跟踪：查看每个项目的时间细分
- 灵活的报告：为任何日期范围生成详细的时间表
- SQLite存储：快速、可靠的数据库，没有大小限制
- 直接脚本访问：无MCP约束，可处理数千项活动
- 100%本地：所有数据都存储在本地，没有云服务
- 易于出口：直接导出到JSON、CSV或查询数据库
安装
先决条件
- Node.js （v14或更高版本）
- npm （附带Node.js）
快速安装
步骤1：克隆并安装依赖项
cd C:\Users\eric\ClaudeTimeMCP
npm install步骤2：运行自动挂钩设置（必需）
node setup-hooks.js此步骤是必需的！ 该脚本修改您的Claude Code配置文件以启用自动跟踪。
它的作用：
- 验证所有钩子脚本是否存在于
scripts/目录 - 修饰
~/.claude/settings.json添加挂钩配置 - 修饰
~/AppData/Roaming/claude-code/config.json（如果存在） - 在修改之前创建现有配置文件的备份
- 配置所有5个挂钩（SessionStart、SessionEnd、UserPromptSubmit、PostToolUse、Stop）
如果不运行此脚本，时间跟踪将无法工作。
步骤3：重新启动Claude代码
就是这样！Hooks现在将自动跟踪所有项目中的所有会话。
可选：安装SQLite CLI工具进行数据库检查
# Windows
install-sqlite-windows.bat
# Mac/Linux
chmod +x install-sqlite-unix.sh
./install-sqlite-unix.sh注： 旧的MCP服务器设置已存档。如果您以前使用过MCP服务器，请参阅 MCP_REMOVAL.md 获取迁移说明。
用法
生成时间表报告（主要工具）
主要的报告工具是 generate_timesheet.js:
# Report for today (default)
npm run report
# Show help with all options
npm run report -- --help
# Report for specific date
npm run report 2025-11-01
# Report for date range
npm run report 2025-10-01 2025-11-07这将生成一个全面的时间表，其中包括：
- 每个会话的逐行活动日志
- 计费小时数计算（有活动的唯一小时数）
- 会话摘要，包括文件编辑和工具使用
- 总体统计数据和使用的顶级工具
- 每小时的视觉活动指标细分
快速数据库查询
为了快速检查状态，您可以使用 cli.js:
# Check current session
node cli.js current-session
# View recent sessions
node cli.js stats 10注：cli.js主要由钩子内部使用。要进行全面报告，请使用npm run report相反。
使用钩子进行自动跟踪
钩子在Claude Code设置中配置，并自动将所有会话活动记录到SQLite。
What Hooks Track：
- 会话开始 -当Claude Code启动时（记录项目路径、时间戳）
- 用户消息 -您发送的每个提示（记录消息内容）
- 工具使用 -Claude使用的每个工具（记录工具名称、输入、输出）
- 助理回应 -Claude的文本回复（记录回复内容）
- 会话结束 -当Claude Code退出时（计算持续时间）
吊钩配置：
- 钩子的定义见
hooks/目录作为Node.js脚本 - 在Claude代码设置中配置：
claude_desktop_config.json - 自动跨所有项目工作
- 直接写入SQLite数据库(
time-tracker.db)
钩子脚本：
scripts/onSessionStart.js-日志会话开始scripts/onSessionEnd.js-日志会话结束scripts/onUserPromptSubmit.js-记录您的消息scripts/onPostToolUse.js-记录工具使用情况scripts/onStop.js-记录克劳德的回应
所有钩子都写入一个统一的日志文件(data/hooks.log)用于调试。
数据存储
数据存储在SQLite数据库中： time-tracker.db
sessions 桌子
| 列 | 类型 | 描述 |
|---|---|---|
id | TEXT主键 | 唯一会话标识符 |
project_path | TEXT | 项目目录的完整路径 |
project_name | TEXT | 提取的项目名称 |
start_time | 文本 | ISO时间戳 |
end_time | TEXT | ISO时间戳（如果会话仍处于打开状态，则为空） |
duration_minutes | REAL | 计算持续时间 |
message_count | INTEGER | 会话中的消息数 |
tool_use_count | INTEGER | 会话中使用的工具数量 |
created_at | TEXT | 记录创建时间戳 |
activities 桌子
| 列 | 类型 | 描述 |
|---|---|---|
id | TEXT主键 | 唯一活动标识符 |
session_id | TEXT | 会话引用（外键） |
activity_type | 文本 | 活动类型 |
timestamp | 文本 | ISO时间戳 |
metadata | TEXT | 带附加数据的JSON字符串 |
created_at | TEXT | 记录创建时间戳 |
活动时间计算
为了避免计算空闲时间（例如，让Claude Code通宵打开），系统：
- 计算连续活动之间的时间
- 将间隙限制在最多30分钟
- 提供准确的“有效工作时间”
这与《 analyze_claude_time.js 脚本。
测试
测试钩子脚本
您可以通过向单个钩子脚本传输JSON数据来测试它们：
# Test session start hook
echo '{"project_path":"C:\\test","timestamp":"2025-11-01T12:00:00Z"}' | node scripts/onSessionStart.js
# Test user message hook
echo '{"prompt":"Test message"}' | node scripts/onUserPromptSubmit.js
# Check the database
node cli.js stats 5测试报告
# Generate a report
npm run report 2025-11-01
# View session stats
node cli.js stats 10验证挂钩是否正常工作
在Claude Code中配置钩子后：
- 在任何项目中启动Claude Code
- 给克劳德发消息
- 检查数据库：
node cli.js current-session
node cli.js stats 1- 验证会话和活动是否已记录
故障排除
挂钩未记录
- 验证是否在Claude Code设置中配置了挂钩(
claude_desktop_config.json) - 检查
data/hooks.log用于错误消息 - 验证是否安装了Node.js：
node --version - 手动测试挂钩脚本：
echo '{"project_path":"C:\\test"}' | node scripts/onSessionStart.js- 配置更改后重新启动Claude代码
数据存储问题
SQLite数据库 time-tracker.db 在第一次运行时自动创建。
要重置所有数据，请执行以下操作：
rm time-tracker.db
node cli.js session-start # Will recreate database and tables要直接检查数据库，请执行以下操作：
# Windows (if SQLite CLI installed)
C:\sqlite\sqlite3.exe time-tracker.db
# Or use a GUI like DB Browser for SQLite
# https://sqlitebrowser.org/权限问题
确保ClaudeTime文件夹具有创建SQLite数据库文件的写入权限。
数据导出
要导出时间数据，请执行以下操作：
- SQLite格式：复制
time-tracker.db直接（标准SQLite数据库） - JSON导出：使用SQLite导出：
C:\sqlite\sqlite3.exe time-tracker.db ".mode json" ".output sessions.json" "SELECT * FROM sessions;"- CSV导出：使用SQLite导出：
C:\sqlite\sqlite3.exe time-tracker.db ".mode csv" ".output sessions.csv" "SELECT * FROM sessions;"- 格式化报告：生成全面的时间表
npm run report
隐私
- 所有数据都存储在本地计算机上
- 没有数据发送到外部服务
- 无需API密钥或身份验证
- 您可以完全控制您的数据
当前状态
✅ 完整-核心功能
- ✅ 基于钩子的自动跟踪（会话、消息、工具、响应）
- ✅ SQLite数据库存储，没有大小限制
- ✅ 全面的时间表报告(
generate_timesheet.js) - ✅ 用于查询和手动控制的CLI工具
- ✅ 活动时间计算（30分钟怠速上限）
- ✅ 基于项目的跟踪
- ✅ 跨平台支持（Windows、macOS、Linux）
⚠️ 已删除-MCP服务器
- ❌ MCP服务器已存档（读取工具256KB的限制使其不切实际）
- ✅ 所有功能都被基于脚本的高级方法所取代
未来路线图
第3阶段：增强报告
- 周/月总结报告
- 可视化生产力图表（每天小时数、工具使用趋势）
- 每个项目的成本跟踪（计费费率）
- 导出为外部格式（Excel、PDF时间表）
第四阶段：高级功能
- 用于可视化分析的Web仪表板
- 与外部时间跟踪服务（Toggl、Harvest、Clockify）集成
- 团队时间跟踪（多用户支持）
- 基于跟踪小时数的自动开票
许可证
麻省理工学院
支持
对于问题或疑问，请在项目存储库中创建问题。