Weekmark
Any calendar week, one keystroke away.
A native macOS widget for anyone who plans in calendar weeks: software teams, PMs, release managers.
- A big week number, the date range and a 7-day strip on your desktop (on any display; it remembers which one)
- Quick Finder (⌃⌥W from any app): type
46, Dec 12, +6w, 46-50 or until CW52, then press ⏎ to copy "CW46 (9–15 Nov)"
- Milestones with week and working-day countdowns ("Release 5.0 · CW46 · 5w · 30d")
- Sprints, Program Increments and quarters ("Sprint 20 · day 5/9", "PI 4 · 5/5", "Q3 FY27")
- Holidays and working days for 10 countries, plus your company's own
.ics holiday calendar
- A warning when ISO and US week numbers differ for the same week
- Runs on your Mac: no account, no tracking. The only network request is the optional Sparkle update check.
Install
brew install --cask rockykusuma/weekmark/weekmark
Or download the notarized DMG from Releases. macOS 14 or later.
Quick Finder syntax
| Type | Example | Result |
|---|
| Week | 46, CW46, KW 46, 3 2027, 2027-W3 | Dates, how far away, working days, holidays, milestones, sprint |
| Date | Dec 12, 12/12/2026, next friday | Which CW it falls in |
| Offset | +6w, -2w, +10d, in 6 weeks, 3 weeks ago | Target week or date |
| Range | 46-50, CW52–CW2, 46 to 48 | Number of weeks and working days, holidays included |
| Countdown | until CW52, to dec 24, today -> 46 | Weeks and working days left |
| Milestone | release | Matching milestones |
| Keywords | today, next week, last week | |
⏎ copies the selected result · ⌘⏎ shows it in the widget · ↑↓ selects · esc closes.
From week 40 onward, a week number of 12 or lower means next year.
Widget
- Drag the top half to move it. Right-click for the menu; right-click a week row to add a milestone there.
- Hover a week to see its dates. Click it to pin it. Scroll over the calendar to change month.
- Holidays are shown in red, milestone weeks get a flag, and a line marks where each sprint starts.
- The menu bar shows
CW 41. Its menu has a copy action and Weeks in 2026/2027, a list of every week with its dates, holidays and milestones.
- Year at a Glance (the calendar button above the month, or the menu): the whole year as 12 months with week numbers, holidays, milestones and sprint starts. Hover a week for its details, click to pin it, ⌘C copies it, ←/→ change the year.
iPhone & Apple Watch
Mobile/ holds the iOS app (Week, Year, Find and Settings tabs), its Home Screen / Lock Screen / StandBy widgets, and
the watchOS app with complications.
They share Sources/CWCore with the Mac app. Milestones, sprints, quarters, holidays and week numbering sync between
Mac, iPhone and Watch through iCloud key-value storage (SettingsSync).
cd Mobile && xcodegen # regenerate WeekmarkMobile.xcodeproj after adding files
open WeekmarkMobile.xcodeproj # pick your iPhone, press Run
Signing uses team Y87BZN47C5 (Xcode → Settings → Accounts must include an Apple ID in that team).
For Mac ↔ iPhone sync, the Mac release build needs Resources/Weekmark.provisionprofile: run
scripts/fetch-mac-profile.sh once.
Windows
A Windows version is in preview: the same widget, plus a tray icon showing the week number. Builds are unsigned for now.
See Windows/README.md to run or build it, and the
Releases page for the Windows pre-releases (tags windows-v*).
Build
./build.sh # runs tests, builds build/Weekmark.app (universal, ad-hoc signed)
./build.sh install # also installs to /Applications and relaunches
swift test # core tests (week maths, parser, holidays, sprints)
Command-line flags: --find "<query>", --settings <general|widget|planning|holidays|milestones|about>, --year, --onboarding.
Release
./scripts/ship.sh 1.1
One command bumps the version, builds, signs, notarizes, publishes the GitHub release, updates the Homebrew tap and
the Sparkle feed, then verifies them. See RELEASING.md for the full process, one-time setup on a
new Mac, and troubleshooting.
Website
docs/index.html is the landing page (live CW lookup demo, 53-week year strip), served with docs/appcast.xml by
GitHub Pages at rockykusuma.github.io/weekmark.
scripts/week-pages.py generates docs/weeks/ ("What week is it?", a year-at-a-glance page per year and a page per
week), the subscribable docs/weeks.ics and docs/sitemap.xml. Edit scripts/weeks/ (CSS, JS) or the script, not
the output. The Week pages workflow re-runs it every 1 January to add the next year.
Company rollout (IT)
packaging/mdm/Weekmark-Company.mobileconfig is an example profile that presets week numbering, holiday
regions, sprints, fiscal quarters, company milestones and company holidays for every Mac. Managed values override user settings.
Code layout
Sources/CWCore: platform-independent logic (week maths, QueryEngine, holidays and .ics import, sprints, quarters, milestones). Fully unit-tested.
Sources/Weekmark: AppKit/SwiftUI app (widget panel, Quick Finder, global hotkey, settings, onboarding, Sparkle updater)
docs/: landing page and Sparkle appcast (GitHub Pages)
release-notes/: per-version notes shown in the update dialog
Tests/CWCoreTests: 27 tests covering 53-week years, year boundaries, DST, locales, holiday rules and the parser
License
MIT. See LICENSE. Sparkle is included under its own MIT-style license.