ClipTimer ⏱️

A clipboard-driven time tracking app for macOS that helps you monitor time spent on different tasks. Simply paste your task list and start tracking!

✨ Features

🎯 Core Functionality

• Clipboard Integration: Paste task lists directly from your clipboard - no manual typing needed
• Time Tracking: Accurate time measurement with live updates
• Auto-Pause: Automatically pauses active tasks when you quit the app
• Data Persistence: Your tasks and elapsed times are automatically saved
• Task Editor Window: Write or edit multiple tasks in a dedicated window (⌘E), including arithmetic expressions such as Newsletter: 4:29:32 - 2:09:00
• Task Completion: Mark tasks as finished and restart them later if needed

🔄 Smart Workflow

• Clipboard-First Design: Paste task lists from any source (notes, emails, documents)
• One-Click Operation: Start/pause tasks with a single click
• Visual Feedback: Clear indicators for active tasks with blinking colons
• Export to Clipboard: Copy task summaries with total time back to clipboard

💾 Reliability

• Automatic Saving: All changes are saved instantly to prevent data loss
• App Lifecycle Management: Proper handling of app termination
• State Preservation: Resume exactly where you left off

🚀 Getting Started

Requirements

• macOS 14.1 or later
• Xcode 15.0+ (for development)

Installation

From App Store (Recommended)

Build from Source

1. Clone the repository:

   git clone https://github.com/domingogallardo/ClipTimer.git
   cd ClipTimer

   The default public workflow uses main. If you need the private beacon presence functionality for personal use, switch to beacon and build it locally only; never use beacon for App Store submissions.

2. Open the project in Xcode:

   open ClipTimer.xcodeproj

3. Build and run the project (⌘+R)

🎮 Usage

Basic Operations

1. Add Tasks: Paste task lists from your clipboard (supports time formats like "Task: 1:30:45")
2. Start Tracking: Click the play button next to any task
3. Pause/Resume: Click the pause button or start another task
4. Finish Tasks: Right-click a task and choose Finish to mark it completed (use Restart to resume)
5. Export Summary: Copy all tasks with elapsed times back to clipboard

Supported Clipboard Formats

ClipTimer automatically parses various time formats when pasting tasks or editing them in the Task Editor:

• Task name: 1:30:45 (H:MM:SS)
• Task name: 90:30 (MM:SS)
• Task name (starts at 0:00:00)
• Task name: 4:29:32 - 2:09:00 + 45 (add or subtract multiple time fragments)
• Multi-line task lists (one task per line)

Keyboard Shortcuts

• ⌘+V: Paste tasks from clipboard
• ⌘+C: Copy task summary back to clipboard
• ⌘+F: Finish active task
• ⌘+?: Show help overlay
• ⌘E: Open Task Editor window
• ⇧⌘⏎: Add tasks from editor
• ⌘⏎: Replace tasks from editor

🏗️ Architecture

ClipTimer is built with modern Swift and SwiftUI, following best practices:

Key Components

• TaskStore: Centralized state management with @ObservableObject
• Task Model: Codable data structure for persistence
• AppDelegate: Handles app lifecycle events
• UserDefaults: Local data persistence

Design Patterns

• Single Source of Truth: Centralized activeTaskID management
• Reactive UI: SwiftUI with automatic updates
• Separation of Concerns: Clear separation between UI and business logic

🧪 Testing

ClipTimer includes a comprehensive test suite with 41+ tests covering:

• Task creation and management
• Time tracking accuracy
• Data persistence
• App lifecycle scenarios
• Edge cases and error handling

Run tests in Xcode with ⌘+U or via command line:

xcodebuild test -scheme ClipTimer -destination 'platform=macOS'

🛠️ Development

Branches

• main: App Store release branch.
• beacon: Private-feature branch built on top of main. It can live on GitHub, but it must never be used for App Store submissions.

Branch Workflow

1. Start shared or App Store-safe changes from main and merge them back into main.
2. Start beacon-only work from beacon and merge it back into beacon.
3. Keep the private branch current with main by merging main into beacon regularly:

   git switch main
   git pull
   
   git switch beacon
   git merge main
   git push

4. Do not use beacon for App Store releases. Public release builds and App Store submissions must always come from main.
5. Prefer merge main -> beacon for ongoing maintenance. Reserve cherry-pick for exceptional cases where only a single fix should move between branches.

Project Structure

ClipTimer/
├── ClipTimer/              # Main app source
│   ├── ClipTimerApp.swift  # App entry point
│   ├── TaskStore.swift     # State management
│   ├── Task.swift          # Data model
│   ├── ContentView.swift   # Main UI
│   └── ...
├── ClipTimerTests/         # Test suite
└── ClipTimer.xcodeproj/    # Xcode project

Key Technologies

• SwiftUI: Modern declarative UI framework
• Combine: Reactive programming for state management
• UserDefaults: Local data persistence
• XCTest: Unit and integration testing

Recent Updates

• ✅ Auto-pause on app termination (v1.1.0)
• ✅ Enhanced data persistence (v1.1.0)
• ✅ Improved reliability and performance (v1.1.0)
• ✅ Task Editor window (v1.2.0)
• ✅ Arithmetic expressions when updating task times (v1.3.0)

Code Style

• Follow Swift API Design Guidelines
• Use SwiftUI best practices
• Include tests for new functionality
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ❤️ using Swift and SwiftUI
• Icons and design inspired by macOS Human Interface Guidelines
• Thanks to the Swift community for excellent tooling and resources

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Support

---

Made with ❤️ for the macOS community