Git时间追踪工具

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

# Build the static binary to ./bin/clockwork
make build

# Or install to $GOPATH/bin
make install

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

# Either mode can point at a specific database file
./bin/clockwork --db /path/to/clockwork.db

{
  "mcpServers": {
    "clockwork": {
      "command": "/absolute/path/to/clockwork",
      "args": ["mcp"]
    }
  }
}

{
  "mcpServers": {
    "clockwork": {
      "command": "/absolute/path/to/clockwork",
      "args": ["mcp"]
    }
  }
}

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

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

./bin/clockwork

"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"

// Create a project backed by a local git repository
create_project({
  name: "My Project",
  source_type: "local",
  git_repo_path: "/absolute/path/to/repo"
})

// Create a project with no repository at all (manual entries only)
create_project({
  name: "Consulting",
  source_type: "none"
})

// Create a project whose commits you look up yourself
create_project({
  name: "Remote App",
  source_type: "mcp",
  repository: "owner/remote-app"
})

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

// Create entry from commits you fetched yourself (source_type "mcp")
get_commit_baseline({ project_id: "project-uuid" })
// → { source_type: "mcp", repository: "owner/remote-app", last_commit_hash: "abc123..." }

create_entry({
  project_id: "project-uuid",
  commits: [
    { hash: "3f2a91c...", author: "Alex", message: "feat: add widget",
      timestamp: "2026-07-20T09:00:00Z" }
  ]
})

// 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, search, ordering and pagination
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
  search: "invoice",           // optional, matches message, commit hash, project name
  sort_by: "created_at",       // optional: created_at | updated_at | duration | message
  order: "desc",               // optional: desc (default) | asc
  page: 1,                     // optional, 1-based
  page_size: 50                // optional, clamped to 50
})
// → rows plus page, page_size, total, total_pages, has_more

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

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

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

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Website Redesign",
  "source_type": "local",
  "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 (static, like release assets)
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/clockwork ./cmd/clockwork

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

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

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

# 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