Chess Clock

A lightweight macOS status bar chess clock built with pure Swift.

Features

• Status Bar Integration: Runs in the macOS status bar with real-time display showing "W" for Work mode or "N" for Not Work mode
• Count-Up Timer: Tracks time spent in Work and Not Work modes (both count up from their current values)
• Flexible Time Input: Supports formats like 8h, 5m, 30s for setting/adjusting times
• Clock-based Timing: Uses actual system clock for accurate timing
• Persistent Storage: Saves configuration to ~/.config/chess_clock/
• No Dependencies: Pure Swift using built-in macOS frameworks

Quick Start

Option 1: Install (Recommended)

chmod +x install.sh
./install.sh

This will:

• Compile the app
• Install to ~/Applications/ChessClock
• Optionally add to Login Items (auto-start at boot)

Option 2: Run Directly (Testing)

chmod +x ChessClock.swift
swift ChessClock.swift

The ⏱ icon will appear in your status bar!

Compile to Binary (Faster)

# Compile
swiftc ChessClock.swift -o ChessClock

# Run
./ChessClock

Build as macOS App Bundle

# Create app structure
mkdir -p ChessClock.app/Contents/MacOS

# Compile
swiftc ChessClock.swift -o ChessClock.app/Contents/MacOS/ChessClock

# Create Info.plist
cat > ChessClock.app/Contents/Info.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleExecutable</key>
    <string>ChessClock</string>
    <key>CFBundleIdentifier</key>
    <string>com.chessclock.app</string>
    <key>CFBundleName</key>
    <string>ChessClock</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>LSUIElement</key>
    <true/>
</dict>
</plist>
EOF

# Run
open ChessClock.app

Keyboard Shortcuts

• ⌃⌘P - Start/Pause (Ctrl+Cmd+P)
• ⌃⌘W - Switch to Work mode (and auto-start)
• ⌃⌘N - Switch to Not Work mode (and auto-start)
• ⌘Q - Quit

For system-wide shortcuts (working even when other apps are focused):

1. Go to System Settings > Privacy & Security > Accessibility
2. Add ChessClock (or Terminal if running via Swift)
3. Enable it

Usage

Starting the Clock

1. Click the clock icon (⏱) in the status bar
2. Select "Start/Pause" to begin timing
3. The current mode's time displays in the status bar as "W ⏱ 00:00:00" or "N ⏱ 00:00:00"

Switching Modes

• Click "Work" in the menu to switch to work mode (automatically starts the timer)
• Click "Not work" in the menu to switch to not work mode (automatically starts the timer)
• The currently active mode is marked with ► in the menu
• Use keyboard shortcuts ⌃⌘W (Work) or ⌃⌘N (Not work) for quick switching

Setting Times

1. Click "Set Times..." in the menu
2. The dialog shows current times - edit as needed (e.g., 8h, 8h or 5m, 10m or 0, 0)
3. Supported formats:
   • 8h - 8 hours
   • 30m - 30 minutes
   • 45s - 45 seconds
   • 0 - zero/reset to 0
4. Use this to adjust times mid-session if you accidentally ran the clock too long or need to correct the times

Both Work and Not Work modes always count up from their current values.

System Sleep Handling

The clock uses wall-clock time, so it correctly handles system sleep:

• If your Mac goes to sleep while the timer is running, the timer continues counting
• When your Mac wakes up, the display immediately updates to show the correct elapsed time
• Example: Start timer at 10:00, Mac sleeps at 10:05, wakes at 11:05 → timer shows 1 hour has passed

Menu Items

• Work: 00:00:00: Shows work time; click to switch to work mode (auto-starts timer)
• Not work: 00:00:00: Shows not work time; click to switch to not work mode (auto-starts timer)
• Start/Pause: Toggle the timer (⌃⌘P)
• Set Times...: Adjust current times or set new times
• Reset to Default (0/0): Reset both timers to 0/0
• Shortcuts: Menu section showing available keyboard shortcuts
• Quit: Exit the application (⌘Q)

Note: The active mode is marked with ► next to it.

Configuration Files

Stored in ~/.config/chess_clock/:

• config.json: Current configuration (times, active mode)

Note: The application automatically saves state:

• Every minute while running
• When pausing the timer
• When switching modes
• When quitting the application
• After the system wakes from sleep

Examples

Reset both to zero

Set Times: 0, 0

Set specific starting times

Set Times: 5m, 10m

Start with hours tracked

Set Times: 2h, 30m

Technical Details

• Written in pure Swift
• Uses Cocoa/AppKit frameworks (built into macOS)
• Updates every 0.1 seconds
• Wall-clock based timing - correctly handles system sleep/wake
• JSON serialization for saving state
• Runs as accessory app (no dock icon)
• Auto-saves every minute while running
• Listens for system wake notifications to update immediately
• Binary size: ~130KB (lightweight native code)

Uninstall

chmod +x uninstall.sh
./uninstall.sh

This will remove the app and optionally remove saved times.

Or manually:

# Stop auto-start
launchctl unload ~/Library/LaunchAgents/com.chessclock.app.plist

# Remove files
rm ~/Applications/ChessClock
rm ~/Library/LaunchAgents/com.chessclock.app.plist
rm -rf ~/.config/chess_clock  # Optional: removes saved times

Requirements

• macOS 10.13+ (High Sierra or later)
• Swift compiler (included with Xcode or Command Line Tools)

Troubleshooting

Swift not found

Install Xcode Command Line Tools:

xcode-select --install

Permission errors

The app automatically creates ~/.config/chess_clock/ on first run.

App won't start

Run from terminal to see error messages:

swift ChessClock.swift

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Copyright (C) 2025 Jonathan Bisson