A lightweight native macOS timer, stopwatch, and Pomodoro focus companion with retro CRT aesthetics.
Countdown · Pomodoro · Stopwatch · Menu Bar · Pixel-art Duck Companion · 100% Offline
-black?style=flat-square&logo=apple){kind=icon}
Download v1.1.0 Release · Roadmap & Update Plan · Release Notes · Changelog
TimeDuck is a lightweight, open-source native macOS AppKit desktop timer and focus companion. It combines wall-clock-accurate countdown, stopwatch, and Pomodoro timing with an animated pixel duck who breathes, waddles, sleeps, eats breadcrumbs, and celebrates when your session is complete.
Zero external dependencies. Zero telemetry. No accounts, no cloud sync, and no background networking. Everything runs locally on your Mac with instant startup and state saved to a single local JSON file.
TimeDuck v1.1 brings a major expression and customization update:
- 4 Tactical Bandanas: Midnight Operative, Crimson Ronin, Forest Camo, and Desert Camo headwear with trailing fluttering ties.
- Richer Expressive Idle Life: Multi-frame Feather Ruffle wing shake and Curious Peek inquisitive head tilt.
- 3 New CRT Themes: Terminal Green (VT220 phosphor), Paperwhite (glare-free e-ink grayscale), and Electric Pond (high-voltage neon navy & cyan).
- Expanded Situational Dialogue: Over 20 new context-aware lines across late-night sessions, tactical countdowns, and progress milestones, backed by anti-repetition memory.
- Version-Aware Update Experience: Automatic one-time-per-version "What's New / What's Next" release announcement popup.
- Menu Bar "Show TimeDuck": Instantly bring the existing window to the front from the menu bar without resetting active timers.
See the v1.1 Release Notes and Changelog for full details.
Install via Homebrew on Apple Silicon Macs:
brew install --cask VinceGuyMan/tap/timeduckAlternative two-step tap syntax:
brew tap VinceGuyMan/tap
brew install --cask timeduckGatekeeper disclosure: TimeDuck v1.1.0 is ad-hoc signed for open-source distribution. If macOS blocks first launch, click Open Anyway in System Settings → Privacy & Security, or run:
xattr -d com.apple.quarantine /Applications/TimeDuck.app
The screenshots below are captured directly from the shipping release.
| Mode | What it does |
|---|---|
| Countdown Timer | Countdown from a default 01:00 with quick-set presets (1M / 5M / 15M / 25M) and fine adjustments (-1M / +1M / +5M). Tenths-of-a-second appear during the final 10 seconds. |
| Pomodoro Focus | Standard 25-minute work cycles (or custom focus lengths) with automated short/long break sequencing across a 4-cycle workflow. |
| Stopwatch | Wall-clock elapsed timing with split-time LAP recording, fastest/slowest lap highlighting, and clipboard summary export (C). |
| Mini HUD | Compact, always-handy floating strip (M) with live digits, pause/lap controls, progress meter, and companion duck. |
| Menu Bar Companion | Native macOS menu bar accessory (LSUIElement). Displays live countdown in the status bar, offers quick starts, and keeps timing active even when the main window is hidden. |
When a countdown completes:
The duck is an animated desktop companion with dynamic behavioral states. Pet the duck with mouse clicks, drop breadcrumbs with B, or trigger celebratory hops with Q. Companion behavior reacts dynamically to your session: Relaxed, Mission, Focus, Suspicious, Urgency, Victory, Break, and Sleepy.
TimeDuck features eleven costumes (H) and eight retro CRT color palettes (T), rendered using crisp nearest-neighbor pixel graphics:
| Costumes (H) | Themes (T) |
|---|---|
| Classic Duck | Arcade Neon |
| Wizard Hat | Game Boy DMG |
| Detective Cap | Amber CRT |
| Cyber Shades | Synthwave |
| Barista | Duck Pond |
| Sleepy Cap | Terminal Green |
| Royal Crown | Paperwhite |
| Tactical (Midnight) | Electric Pond |
| Crimson Ronin | |
| Forest Camo | |
| Desert Camo |
| Key | Action |
|---|---|
| Space | Start / pause (or advance a finished Pomodoro phase) |
| Return | Start / pause, or exit mini HUD mode |
| L | Record stopwatch lap, or skip current Pomodoro phase |
| R | Reset / clear current timer |
| 1 2 3 | Switch mode: Stopwatch (1) / Timer (2) / Pomodoro (3) |
| H | Cycle costume / hat |
| T | Cycle retro CRT theme |
| M | Toggle Mini HUD mode |
| P | Pin window always-on-top |
| S | Toggle sound effects |
| Q | Hop + quack companion trigger |
| B | Feed duck a breadcrumb |
| C | Copy today's focus stats & lap times to clipboard |
| X / Cmd-Q | Quit (state is saved automatically) |
Requirements: macOS 12 Monterey or later, Xcode Command Line Tools.
# Build the release application bundle (build/TimeDuck.app)
./build.sh --release
# Run automated test suite
./build.sh --test
# Clean build artifacts
./build.sh --cleanAudio features an original looping 8-bit soundtrack (Resources/Audio/TimeDuckTheme.m4a) plus procedural audio synthesis for ticks, fanfares, quacks, and clicks. Music and sound effects can be toggled independently.
Timing accuracy never relies on the UI display refresh loop. All remaining and elapsed durations are calculated from wall-clock timestamps (Date) against persistent reference anchors, ensuring that system sleep, window hiding, or background throttling cannot cause the clock to drift.
src/
├── App/ Window management, menu bar, What's New popup, persistence, hotkeys
├── Audio/ Theme playback + cached PCM audio synthesis
├── Engine/ Countdown, Pomodoro, Stopwatch, Duck Brain, Stats
├── Graphics/ Software pixel stage, CRT scanlines, sprites, palettes
└── Views/ Native AppKit host + pixel canvas renderer
- Adaptive Refresh: 60 FPS for active stopwatch/tenths, 30 FPS for countdowns, 15 FPS when idle, 10 FPS in background, 0 FPS when hidden.
- State Storage: Atomic, debounced JSON persistence at
~/Library/Application Support/TimeDuck/state.json. - Zero Framework Overhead: Handcrafted Swift and AppKit with zero external package dependencies.
TimeDuck is built with an offline-first philosophy:
- Zero network calls, zero sockets, zero analytics, zero crash reporters.
- No user accounts, no cloud dependencies, no machine identifiers.
- Open source under the MIT License.
Thank you to everyone who has downloaded, shared, starred, or simply spent some focus time with TimeDuck. Your support means a lot, and I'm excited to keep making this little duck stranger, livelier, and more useful with every update.
TimeDuck is intentionally designed as a focused, delightful desktop timer and companion instrument—not an enterprise productivity suite.
Please review CONTRIBUTING.md and our Public Roadmap before opening pull requests. Our core design rule is keeping the application fast, lightweight, and offline. Any future additions must preserve TimeDuck's zero-telemetry privacy, native performance, and handcrafted pixel-art character.
MIT License © 2026 TimeDuck Contributors