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.