Skip to content

Latest commit

 

History

History
169 lines (129 loc) · 5.93 KB

README.md

File metadata and controls

169 lines (129 loc) · 5.93 KB

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!

macOS Swift SwiftUI License

✨ 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)

Download on Mac App Store

Build from Source

  1. Clone the repository:

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

  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.
  • local: Internal branch that includes beacon-based presence features.

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

Made with ❤️ for the macOS community