clockwork (Techthos)

⚙️ 发条装置

*基于Git的自动时间跟踪*

*通过强大的MCP服务器和交互式终端UI，通过git提交自动跟踪您的工作时间*

特性 • 安装 • 快速开始 • 用法 • 文档

______________________________________________________________________

🎯 概述

发条装置 是一个双模时间跟踪系统，可以将git提交转换为可操作的工作日志条目。无论您喜欢通过人工智能助手（MCP模式）还是交互式终端界面（TUI模式）工作，Clockwork都能满足您的需求。

🎭 两种模式，一个数据库

🤖 MCP服务器模式 -与Claude和其他LLM应用程序集成

• 将时间跟踪作为MCP工具公开
• 自然语言交互：“追踪最后2小时的工作”
• 与您的AI工作流程无缝集成

💻 TUI模式 -交互式终端界面

• 功能齐全的终端用户界面，可直接交互
• 使用键盘快捷键浏览项目和条目
• 实时统计和过滤
• 非常适合快速评论和手动输入

✨ 特性

📊 智能时间追踪

• 自动提交聚合 -收集自上次输入以来的提交
• 智能工期计算 -根据提交时间戳估算工作时间
• 自定义覆盖 -需要时手动调整持续时间和消息
• 灵活的条目创建 -基于Git或手动输入模式

🎨 丰富的终端用户界面

• 项目仪表板 -所有项目的可视化概述
• 条目浏览器 -可排序、可过滤的条目列表及其摘要
• 统计视图 -按项目和发票状态分列的时间明细
• 键盘驱动 -无需触摸鼠标即可高效导航
• 颜色编码 -发票/未开票状态一目了然

🔧 项目管理

• 多项目支持 -跨无限项目跟踪时间
• Git仓库集成 -每个项目都链接到一个git仓库
• 发票跟踪 -将条目标记为已开票
• 高级过滤 -按项目、日期范围或发票状态

💾 数据库与集成

• 嵌入式数据库 -bbolt键值存储，无外部依赖
• 单文件存储 - ~/.local/clockwork/default.db
• MCP协议 -适用于Claude Desktop、Claude Code和其他MCP客户端
• 数据持久层 -会话之间安全存储的所有数据

🚀 安装

先决条件

• 转到1.21+ - 点击此处下载
• Git -已安装并配置

从源代码构建

# Clone the repository
git clone https://github.com/techthos/clockwork.git
cd clockwork

# Build the binary
go build -o clockwork ./cmd/clockwork

# Or install to $GOPATH/bin
go install ./cmd/clockwork

验证安装

# The binary supports two modes
./clockwork          # Starts MCP server (default)
./clockwork tui      # Starts terminal UI

⚡ 快速开始

🤖 MCP服务器模式

1.配置您的MCP客户端

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "clockwork": {
      "command": "/absolute/path/to/clockwork"
    }
  }
}

Claude 代码命令行界面 (~/.claude/config.json):

{
  "mcpServers": {
    "clockwork": {
      "command": "/absolute/path/to/clockwork"
    }
  }
}

💡 小贴士：使用 $(go env GOPATH)/bin/clockwork 如果你跑了 go install

2.重新启动MCP客户端

时钟工具现在将在您的Claude会话中可用。

3.开始跟踪

You: "Create a new project called 'Website Redesign' in /home/user/projects/website"

You: "Track the work I did today on the website project"

💻 TUI模式

1.推出TUI

./clockwork tui

2.创建你的第一个项目

• 按 n 创建新项目
• 输入项目名称和git存储库路径
• 按Tab键导航，按Enter键保存

3.创建您的第一个条目

• 按项目上的Enter键查看其条目
• 按 n 创建新条目
• 选择Git模式（自动聚合提交）或手动模式
• 填写详细信息并保存

4.探索统计

• 在条目视图中，按 s 查看统计数据
• 按项目和发票状态查看时间细分
• 使用 f 应用筛选器

📖 用法

💻 TUI模式参考

全局快捷方式

• Ctrl+C 或 Ctrl+Q -退出应用程序
• Tab -浏览表单字段
• Esc -关闭模式/取消

项目视图

• n -新项目
• e -编辑所选项目
• d -删除所选项目（确认后）
• Enter -查看项目条目
• q -退出应用程序
• ↑/↓ -导航列表

条目视图

• n -新条目（选择git或手动模式）
• e -编辑所选条目
• d -删除所选条目
• i -切换发票状态
• f -配置筛选器
• s -查看统计数据
• q -返回项目
• ↑/↓ -导航列表

统计视图

• f -配置筛选器
• r -刷新统计信息
• q -返回条目

条目创建模式

Git模式 （自动）：

1. 选择项目
2. Clockwork获取自上次输入以来的提交
3. 根据时间戳自动计算持续时间
4. 根据提交摘要自动生成消息
5. 可选：覆盖持续时间或消息

手动模式:

1. 选择项目
2. 输入持续时间（格式： 1h 30m, 90m, 1.5h)
3. 输入消息/描述
4. 标记为已开票（可选）

过滤

在条目或统计视图中应用筛选器：

• 项目 -选择特定项目或“所有项目”
• 日期范围 -开始/结束日期（格式：YYYY-MM-DD）
• 发票状态 -全部、仅开票或仅未开票

🤖 MCP模式参考

可用工具

自然语言示例

"Create a new project called 'Mobile App' at /Users/me/code/mobile"

"Track my work today on the mobile app project"

"Show me all uninvoiced time entries"

"Mark the last 3 entries as invoiced"

"How much time did I spend on the API project this week?"

"Create a manual entry for 2 hours of meeting time on the mobile project"

程序化API

// Create a project
create_project({
  name: "My Project",
  git_repo_path: "/absolute/path/to/repo"
})

// Create entry from git commits (automatic)
create_entry({
  project_id: "project-uuid",
  invoiced: false
})

// Create manual entry (no git aggregation)
create_entry({
  project_id: "project-uuid",
  duration: 120,  // minutes
  message: "Client meeting and planning",
  invoiced: false
})

// List entries with filters
list_entries({
  project_id: "project-uuid",  // optional, empty = all projects
  start_date: "2025-01-01",    // optional
  end_date: "2025-01-31",      // optional
  invoiced: false              // optional, null = all entries
})

// Update entry
update_entry({
  id: "entry-uuid",
  duration: 180,      // optional
  message: "Updated", // optional
  invoiced: true      // optional
})

🔧 运作原理

提交聚合流

┌─────────────────┐
│  Last Entry     │
│  commit_hash    │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────┐
│  git log ..HEAD       │
│  Fetch new commits          │
└────────┬────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  Aggregate commit messages  │
│  Calculate duration         │
└────────┬────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  Create worklog entry       │
│  Store latest commit hash   │
└─────────────────────────────┘

持续时间计算逻辑

• 单次提交 → 默认30分钟
• 多次提交 → (last_commit_time - first_commit_time) + 30 minutes

示例：上午9:00和11:30提交

• 时间跨度：2.5小时
• 缓冲时间：0.5小时
• 总时长：3小时（180分钟）

数据库模式

~/.local/clockwork/default.db (bbolt)
├── projects/
│   └──  → {id, name, git_repo_path, created_at, updated_at}
└── entries/
    └──  → {id, project_id, duration, message, commit_hash, invoiced, created_at, updated_at}

📊 数据模型

项目

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Website Redesign",
  "git_repo_path": "/home/user/projects/website",
  "created_at": "2025-01-27T10:00:00Z",
  "updated_at": "2025-01-27T10:00:00Z"
}

进入

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "duration": 180,
  "message": "Aggregated 3 commits:\n1. [abc123d] Implement login form\n2. [def456e] Add form validation\n3. [ghi789f] Update styles",
  "commit_hash": "ghi789f...",
  "invoiced": false,
  "created_at": "2025-01-27T14:30:00Z",
  "updated_at": "2025-01-27T14:30:00Z"
}

统计

{
  "total_minutes": 540,
  "total_hours": 9.0,
  "entry_count": 3,
  "invoiced_minutes": 180,
  "uninvoiced_minutes": 360,
  "project_breakdown": {
    "project-uuid-1": 300,
    "project-uuid-2": 240
  },
  "earliest_entry": "2025-01-20T09:00:00Z",
  "latest_entry": "2025-01-27T14:30:00Z"
}

🛠️ 发展

运行测试

# All tests
go test ./...

# With coverage
go test -cover ./...

# Verbose output
go test ./... -v

# Specific package
go test ./internal/db -v
go test ./internal/git -v

项目结构

clockwork/
├── cmd/
│   └── clockwork/          # Main entry point
├── internal/
│   ├── db/                 # Database operations (bbolt)
│   ├── models/             # Data structures
│   ├── git/                # Git integration
│   ├── server/             # MCP server implementation
│   ├── tui/                # Terminal UI components
│   │   ├── app.go          # Main TUI app structure
│   │   ├── projects.go     # Projects view
│   │   ├── entries.go      # Entries view
│   │   ├── stats.go        # Statistics view
│   │   ├── modals.go       # Dialog boxes
│   │   ├── theme.go        # Color scheme
│   │   └── helpers.go      # Utilities
│   └── utils/              # Shared utilities
├── go.mod
├── go.sum
├── CLAUDE.md               # AI assistant context
└── README.md

生产大楼

# Build with optimizations
go build -ldflags="-s -w" -o clockwork ./cmd/clockwork

# Build for specific platform
GOOS=linux GOARCH=amd64 go build -o clockwork-linux ./cmd/clockwork
GOOS=darwin GOARCH=arm64 go build -o clockwork-macos ./cmd/clockwork
GOOS=windows GOARCH=amd64 go build -o clockwork.exe ./cmd/clockwork

⚠️ 重要说明

数据库锁定

一次只能运行一个模式。 bbolt数据库使用文件锁来确保数据完整性。

• ✅ 运行TUI模式→ MCP模式被阻止
• ✅ 运行MCP模式→ TUI模式被阻止
• ❌ 不能同时运行这两个

错误: failed to open database: timeout 解决方案：在启动新模式之前，先停止另一种模式

Git存储库要求

• 每个项目都必须指向一个有效的git存储库
• 存储库必须至少有一个提交
• Git必须在系统PATH中可访问

🐛 故障排除

“未找到新提交”

原因：最后一个条目和HEAD之间不存在提交

解决方案：进行新的提交，然后创建一个条目

“获取git作者失败”

原因：Git配置不正确

解决方案:

git config user.name "Your Name"
git config user.email "your@email.com"

“未找到项目”

原因：项目ID无效或项目已删除

解决方案：列出要验证的项目：

# In TUI: View projects screen
# In MCP: Use list_projects tool

“工期格式无效”

原因：持续时间格式不可识别

解决方案：使用以下格式之一：

• 1h 30m -小时和分钟
• 90m -仅分钟
• 1.5h -十进制小时数
• 90 -普通数字（以分钟计）

数据库损坏

罕见但可能如果数据库损坏：

# Backup current database
cp ~/.local/clockwork/default.db ~/.local/clockwork/backup.db

# Remove corrupted database
rm ~/.local/clockwork/default.db

# Clockwork will create a new database on next run

🤝 贡献

欢迎投稿！方法如下：

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过(go test ./...)
6. 提交您的更改(git commit -m 'Add amazing feature')
7. 推到分支(git push origin feature/amazing-feature)
8. 打开拉取请求

代码风格

• 遵循标准Go格式(gofmt)
• 为导出的函数添加注释
• 保持功能的专注性和可测试性
• 更新测试以了解任何更改

📝 许可证

MIT许可证-请参阅 许可证 详情

🙏 致谢

基于这些优秀的开源项目构建：

• mcp走 -Mark3 Labs的模型上下文协议实现
• bbolt -Pure Go嵌入式键值数据库
• tview -丰富的终端UI库
• T细胞 -基于终端单元的视图库

🔗 链接

• GitHub:
• MCP协议: 模型上下文协议.io
• 问题: 报告错误或请求功能

______________________________________________________________________

由...制作⚙️ 和❤️ 由Techthos团队

*自动化您的时间跟踪。专注于创造伟大的事物。*